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

[Jiri Denemark]

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