[libvirt] [PATCH] virsh: Enhance documentation of commands starting jobs

Some virsh commands start a (long-running) job that can be monitored using domjobinfo and aborted with domjobabort. Let's be explicit about this in virsh man page. --- tools/virsh.pod | 18 ++++++++++++++++++ 1 files changed, 18 insertions(+), 0 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 43ed1ea..fbde57f 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -627,30 +627,35 @@ named by I<format> to a domain XML format. Convert the file I<xml> in domain XML format to the native guest configuration format named by I<format>. =item B<dump> I<domain-id> I<corefilepath> [I<--live>] [I<--crash>] [I<--bypass-cache>] Dumps the core of a domain to a file for analysis. If I<--live> is specified, the domain continues to run until the core dump is complete, rather than pausing up front. If I<--crash> is specified, the domain is halted with a crashed status, rather than merely left in a paused state. If I<--bypass-cache> is specified, the save will avoid the file system cache, although this may slow down the operation. +The progress may be monitored using B<domjobinfo> virsh command and canceled +with B<domjobabort> command (sent by another virsh instance). Interrupting +(usually with C<Ctrl-C>) the virsh process which runs B<dump> command is not +enough to actually cancel the operation. + NOTE: Some hypervisors may require the user to manually ensure proper permissions on file and path specified by argument I<corefilepath>. =item B<dumpxml> I<domain-id> [I<--inactive>] [I<--security-info>] [I<--update-cpu>] Output the domain information as an XML dump to stdout, this format can be used by the B<create> command. Additional options affecting the XML dump may be used. I<--inactive> tells virsh to dump domain configuration that will be used on next start of the domain as opposed to the current domain configuration. Using I<--security-info> will also include security sensitive information in the XML dump. I<--update-cpu> updates domain CPU requirements according to host CPU. =item B<echo> [I<--shell>] [I<--xml>] [I<arg>...] @@ -672,30 +677,35 @@ This is equivalent to: except that it does some error checking. The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment variables, and defaults to C<vi>. =item B<managedsave> I<domain-id> [I<--bypass-cache>] [{I<--running> | I<--paused>}] Save and destroy (stop) a running domain, so it can be restarted from the same state at a later time. When the virsh B<start> command is next run for the domain, it will automatically be started from this saved state. If I<--bypass-cache> is specified, the save will avoid the file system cache, although this may slow down the operation. +The progress may be monitored using B<domjobinfo> virsh command and canceled +with B<domjobabort> command (sent by another virsh instance). Interrupting +(usually with C<Ctrl-C>) the virsh process which runs B<managedsave> command +is not enough to actually cancel the operation. + Normally, starting a managed save will decide between running or paused based on the state the domain was in when the save was done; passing either the I<--running> or I<--paused> flag will allow overriding which state the B<start> should use. The B<dominfo> command can be used to query whether a domain currently has any managed save image. =item B<managedsave-remove> I<domain-id> Remove the B<managedsave> state file for a domain, if it exists. This ensures the domain will do a full boot the next time it is started. =item B<maxvcpus> [I<type>] @@ -724,30 +734,33 @@ used to reject the migration if the hypervisor lacks change protection support. I<--verbose> displays the progress of migration. The I<desturi> is the connection URI of the destination host, and I<migrateuri> is the migration URI, which usually can be omitted. I<dname> is used for renaming the domain to new name during migration, which also usually can be omitted. Likewise, I<--xml> B<file> is usually omitted, but can be used to supply an alternative XML file for use on the destination to supply a larger set of changes to any host-specific portions of the domain XML, such as accounting for naming differences between source and destination in accessing underlying storage. I<--timeout> B<seconds> forces guest to suspend when live migration exceeds that many seconds, and then the migration will complete offline. It can only be used with I<--live>. +Running migration can be canceled by interrupting virsh (usually using +C<Ctrl-C>) or by B<domjobabort> command sent from another virsh instance. + B<Note>: The I<desturi> parameter for normal migration and peer2peer migration has different semantics: =over 4 =item * normal migration: the I<desturi> is an address of the target host as seen from the client machine. =item * peer2peer migration: the I<desturi> is an address of the target host as seen from the source machine. =back =item B<migrate-setmaxdowntime> I<domain-id> I<downtime> @@ -797,30 +810,35 @@ B<Note>: To avoid corrupting file system contents within the domain, you should not reuse the saved state file for a second B<restore> unless you have also reverted all storage volumes back to the same contents as when the state file was created. =item B<save> I<domain-id> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>] [{I<--running> | I<--paused>}] Saves a running domain (RAM, but not disk state) to a state file so that it can be restored later. Once saved, the domain will no longer be running on the system, thus the memory allocated for the domain will be free for other domains to use. B<virsh restore> restores from this state file. If I<--bypass-cache> is specified, the save will avoid the file system cache, although this may slow down the operation. +The progress may be monitored using B<domjobinfo> virsh command and canceled +with B<domjobabort> command (sent by another virsh instance). Interrupting +(usually with C<Ctrl-C>) the virsh process which runs B<save> command is not +enough to actually cancel the operation. + This is roughly equivalent to doing a hibernate on a running computer, with all the same limitations. Open network connections may be severed upon restore, as TCP timeouts may have expired. I<--xml> B<file> is usually omitted, but can be used to supply an alternative XML file for use on the restored guest with changes only in the host-specific portions of the domain XML. For example, it can be used to account for file naming differences that are planned to be made via disk snapshots of underlying storage after the guest is saved. Normally, restoring a saved image will decide between running or paused based on the state the domain was in when the save was done; passing either the I<--running> or I<--paused> flag will allow overriding which state the B<restore> should use. -- 1.7.6.1