[libvirt] [PATCH libvirt-virshcmdref] Add blockpull and blockjob commands

The blockpull and blockjob commands have been present since 0.9.4. This patch adds basic usage examples and command syntax. Signed-off-by: Stefan Hajnoczi <stefanha(a)linux.vnet.ibm.com&gt; --- common.sh | 8 ++-- source/blockjob.xml | 79 +++++++++++++++++++++++++++++++++++++++ source/blockpull.xml | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 184 insertions(+), 4 deletions(-) create mode 100644 source/blockjob.xml create mode 100644 source/blockpull.xml diff --git a/common.sh b/common.sh index 9da1b13..7e3a3a0 100755 --- a/common.sh +++ b/common.sh @@ -1,9 +1,9 @@ # List of source files DOMAIN_COMMANDS="attach-device attach-disk attach-interface autostart - blkiotune console cpu-baseline cpu-compare create define destroy - detach-device detach-disk detach-interface domid domjobabort domjobinfo - domname domuuid domxml-from-native domxml-to-native dump dumpxml echo - edit freecell hostname inject-nmi managedsave managedsave-remove + blkiotune blockjob blockpull console cpu-baseline cpu-compare create define + destroy detach-device detach-disk detach-interface domid domjobabort + domjobinfo domname domuuid domxml-from-native domxml-to-native dump dumpxml + echo edit freecell hostname inject-nmi managedsave managedsave-remove maxvcpus memtune migrate migrate-setmaxdowntime migrate-getspeed migrate-setspeed reboot restore resume save schedinfo send-key setmaxmem setmem setvcpus shutdown start suspend ttyconsole undefine diff --git a/source/blockjob.xml b/source/blockjob.xml new file mode 100644 index 0000000..0c34bae --- /dev/null +++ b/source/blockjob.xml @@ -0,0 +1,79 @@ +<?xml version='1.0' encoding='utf-8' ?> + +<command> + <name>blockjob</name> + + <description> + <text> + Manage active block operations + </text> + </description> + + <options> + <parameter requirement="required"> + <value type="string" requirement="required">domain</value> + <description> + The name of the domain on which to act. + </description> + </parameter> + <parameter requirement="required"> + <value type="string" requirement="required">path</value> + <description> + The fully-qualified path of the disk. See "domblklist" for listing these names. + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--abort</keyword> + <description> + Abort the active job on the specified disk. + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--async</keyword> + <description> + Return immediately instead of waiting for cancelation to complete, when specified together with "--abort". + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--pivot</keyword> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--info</keyword> + <description> + Print information about any active block operation. + </description> + </parameter> + </options> + + <availability from="0.9.4" /> + + <notes /> + + <examples type="usage"> + <example> + <terminal>virsh # <bold>blockjob</bold> <value>example-domain</value> <value>vda</value> <italic>--info</italic></terminal> + <text> + Prints information about any active block operation on <value>vda</value> from <value>example-domain</value>. + </text> + </example> + <example> + <terminal>virsh # <bold>blockjob</bold> <value>example-domain</value> <value>vda</value> <italic>--abort</italic></terminal> + <text> + Cancels the active block operation on <value>vda</value> from <value>example-domain</value>. + </text> + </example> + </examples> + + <examples type="fullcontext" /> + + <reference type="seealso"> + <item> + <link type="internal" href="blockpull" /> + <name>blockpull</name> + <description> + populate a disk from its backing image chain + </description> + </item> + </reference> + +</command> diff --git a/source/blockpull.xml b/source/blockpull.xml new file mode 100644 index 0000000..81b58da --- /dev/null +++ b/source/blockpull.xml @@ -0,0 +1,101 @@ +<?xml version='1.0' encoding='utf-8' ?> + +<command> + <name>blockpull</name> + + <description> + <text> + Populate a disk from its backing image chain + </text> + </description> + + <options> + <parameter requirement="required"> + <value type="string" requirement="required">domain</value> + <description> + The name of the domain on which to act. + </description> + </parameter> + <parameter requirement="required"> + <value type="string" requirement="required">path</value> + <description> + The fully-qualified path of the disk. See "domblklist" for listing these names. + </description> + </parameter> + <parameter requirement="optional"> + <value type="number" requirement="required">bandwidth</value> + <description> + Copying bandwidth limit in MiB/s. + </description> + </parameter> + <parameter requirement="optional"> + <value type="string" requirement="required">base</value> + <description> + Stop at a specific backing image instead of flattening the entire chain. + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--wait</keyword> + <description> + Block until the operation completes instead of returning as soon as possible while the operation runs in the background. + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--verbose</keyword> + <description> + Print periodic status updates when used together with "--wait". + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--timeout</keyword> + <value type="number" requirement="required">seconds</value> + <description> + Cancel the operation if the timeout elapses. Use together with "--wait". + </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--async</keyword> + <description> + Return as soon as possible. + </description> + </parameter> + </options> + + <availability from="0.9.4" /> + + <notes /> + + <examples type="usage"> + <example> + <terminal>virsh # <bold>blockpull</bold> <value>example-domain</value> <value>vda</value></terminal> + <text> + Start populating <value>vda</value> from its backing image chain and return immediately. + </text> + </example> + <example> + <terminal>virsh # <bold>blockpull</bold> <value>example-domain</value> <value>vda</value> <value>--wait</value></terminal> + <text> + Populate <value>vda</value> from its backing image chain and wait for the operation to complete. + </text> + </example> + <example> + <terminal>virsh # <bold>blockpull</bold> <value>example-domain</value> <value>vda</value> <value>0</value> <value>/path/to/backing.img</value></terminal> + <text> + Start populating <value>vda</value> from its backing image chain up to <value>/path/to/backing.img</value> and return immediately. <value>/path/to/backing.img</value> and its backing images will not be flattened. Note that the <value>0</value> means unlimited bandwidth and is necessary because <value>bandwidth</value> and <value>base</value> are positional arguments. + </text> + </example> + </examples> + + <examples type="fullcontext" /> + + <reference type="seealso"> + <item> + <link type="internal" href="blockjob" /> + <name>blockjob</name> + <description> + manage active block operations + </description> + </item> + </reference> + +</command> -- 1.7.10.4