[libvirt] [PATCH v2 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; --- v2: * Linewrap to 80 chars except pre-formatted <terminal> tag [Eric] * 'path' argument can be <target dev='name'> or <source file='name'> [Eric] * s/cancelation/cancellation/ [Eric] * Use blockpull --base option to avoid bandwidth 0 positional argument [Eric] * Drop blockjob --pivot argument, it doesn't work yet and I didn't document it common.sh | 8 ++-- source/blockjob.xml | 81 ++++++++++++++++++++++++++++++++++++ source/blockpull.xml | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 196 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..1763c3c --- /dev/null +++ b/source/blockjob.xml @@ -0,0 +1,81 @@ +<?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> + Either the <italic>&lt;source file='path'&gt;</italic> filename or the + <italic>&lt;target dev='path'&gt;</italic> device name. 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 cancellation to complete, + when specified together with "--abort". + </description> + </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..15014a6 --- /dev/null +++ b/source/blockpull.xml @@ -0,0 +1,111 @@ +<?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> + Either the <italic>&lt;source file='path'&gt;</italic> filename or the + <italic>&lt;target dev='path'&gt;</italic> device name. 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> <italic>--wait</italic></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> <italic>--base</italic> <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. + </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