[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@linux.vnet.ibm.com> --- 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
On Wed, Aug 22, 2012 at 02:40:57PM +0100, Stefan Hajnoczi wrote:
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@linux.vnet.ibm.com> --- 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
Convenience links for easy reviewing: http://vmsplice.net/~stefan/blockpull.html http://vmsplice.net/~stefan/blockjob.html Stefan
On 08/22/2012 07:40 AM, Stefan Hajnoczi wrote:
The blockpull and blockjob commands have been present since 0.9.4. This patch adds basic usage examples and command syntax.
Thanks for tackling this.
Signed-off-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com> --- 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
+++ b/source/blockjob.xml + <parameter requirement="required"> + <value type="string" requirement="required">path</value> + <description> + The fully-qualified path of the disk. See "domblklist" for listing these names.
Maybe mention that you can give either the path (/path/to/disk) or the devname (vda).
+ <parameter requirement="optional"> + <keyword requirement="required">--async</keyword> + <description> + Return immediately instead of waiting for cancelation to complete, when specified together with "--abort".
s/cancelation/cancellation/
+ </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--pivot</keyword> + </parameter>
What a shame that qemu 1.2 still doesn't support block copy, and therefore --pivot is still a no-op (it only makes sense when ending a copy job).
+ <parameter requirement="optional"> + <keyword requirement="required">--info</keyword> + <description> + Print information about any active block operation. + </description> + </parameter> + </options> + + <availability from="0.9.4" />
Should we start listing which version of virsh added various options? For example, --pivot wasn't present until 0.9.12 (commit 1f06c00), but still has no backend that supports it (except RHEL 6.3, via RHEL-specific patches).
+++ b/source/blockpull.xml
+ <parameter requirement="required"> + <value type="string" requirement="required">path</value> + <description> + The fully-qualified path of the disk. See "domblklist" for listing these names.
Same story about accepting full path or devname.
+ <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.
Long line (here and elsewhere, but this one stood out to me). Can you please wrap things to fit in 80 columns? Your comment is not quite true; this is an equivalent command line that omits the bandwidth: blockpull example-domain vda --base /path/to/backing.img by instead using an explicit '--base'. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On Wed, Aug 22, 2012 at 12:07:51PM -0600, Eric Blake wrote:
On 08/22/2012 07:40 AM, Stefan Hajnoczi wrote:
+++ b/source/blockjob.xml + <parameter requirement="required"> + <value type="string" requirement="required">path</value> + <description> + The fully-qualified path of the disk. See "domblklist" for listing these names.
Maybe mention that you can give either the path (/path/to/disk) or the devname (vda).
Good idea.
+ <parameter requirement="optional"> + <keyword requirement="required">--async</keyword> + <description> + Return immediately instead of waiting for cancelation to complete, when specified together with "--abort".
s/cancelation/cancellation/
Okay.
+ </description> + </parameter> + <parameter requirement="optional"> + <keyword requirement="required">--pivot</keyword> + </parameter>
What a shame that qemu 1.2 still doesn't support block copy, and therefore --pivot is still a no-op (it only makes sense when ending a copy job).
I was thinking whether to drop --pivot completely from this page. I also haven't attempted to document blockcopy since I've never used the command and mirroring isn't upstream in QEMU.
+ <parameter requirement="optional"> + <keyword requirement="required">--info</keyword> + <description> + Print information about any active block operation. + </description> + </parameter> + </options> + + <availability from="0.9.4" />
Should we start listing which version of virsh added various options? For example, --pivot wasn't present until 0.9.12 (commit 1f06c00), but still has no backend that supports it (except RHEL 6.3, via RHEL-specific patches).
I'm not aware of XML for per-option version info and plan to leave it at 0.9.4 for now.
+++ b/source/blockpull.xml
+ <parameter requirement="required"> + <value type="string" requirement="required">path</value> + <description> + The fully-qualified path of the disk. See "domblklist" for listing these names.
Same story about accepting full path or devname.
+ <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.
Long line (here and elsewhere, but this one stood out to me). Can you please wrap things to fit in 80 columns?
Sure.
Your comment is not quite true; this is an equivalent command line that omits the bandwidth:
blockpull example-domain vda --base /path/to/backing.img
by instead using an explicit '--base'.
Thanks, --base is nicer. I'll drop the '0'. Stefan
participants (2)
-
Eric Blake -
Stefan Hajnoczi