From 9f337ef7525e44d32afaef5f650ede2d07a482b2 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Mon, 5 Apr 2010 17:21:02 -0600 Subject: [PATCH] virsh: improve documentation Document several missing commands. There's more work that could be done, but incremental improvements is better than no patch at all. * tools/virsh.pod (autostart, connect): Improve grammar. (create): Improve example. (domjobabort, domjobinfo, domxml-from-native, domxml-to-native): Document. (storage pool commands): New section. --- tools/virsh.pod | 173 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 160 insertions(+), 13 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 0e14de99db..a59e9b0bf6 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -103,10 +103,12 @@ Will print the current directory. =item B I optional I<--readonly> -(Re)-Connect to the hypervisor. This is a build-in command after shell -start up, and usually get an I parameter specifying how to connect -to the hypervisor. The documentation page at L -list the values supported but the most common are: +(Re)-Connect to the hypervisor. When the shell is first started, this +is automatically run with the I parameter requested by the C<-c> +option on the command line. The I parameter specifies how to +connect to the hypervisor. The documentation page at +L list the values supported, but the most +common are: =over 4 @@ -116,11 +118,11 @@ this is used to connect to the local Xen hypervisor, this is the default =item qemu:///system -allow to connect locally as root to the daemon supervising QEmu and KVM domains +connect locally as root to the daemon supervising QEmu and KVM domains =item qemu:///session -allow to connect locally as a normal user to his own set of QEmu and KVM domains +connect locally as a normal user to his own set of QEmu and KVM domains =item lxc:/// @@ -252,7 +254,7 @@ I can be specified as an short integer, a name or a full UUID. Configure a domain to be automatically started at boot. -The option I<--disable> disable autostarting. +The option I<--disable> disables autostarting. =item B I @@ -260,11 +262,15 @@ Connect the virtual serial console for the guest. =item B I -Create a domain from an XML . An easy way to create the XML is to use the B command to obtain the definition of a pre-existing guest. +Create a domain from an XML . An easy way to create the XML + is to use the B command to obtain the definition of a +pre-existing guest. B -virsh dumpxml > file. +virsh dumpxml > domain.xml +edit domain.xml +virsh create < domain.xml =item B I @@ -306,6 +312,14 @@ Convert a domain name (or UUID) to a domain id Returns basic information about the domain. +=item B + +Abort the currently running domain job. + +=item B I + +Returns information about jobs running on a domain. + =item B I Convert a domain Id (or UUID) to domain name @@ -314,22 +328,35 @@ Convert a domain Id (or UUID) to domain name Returns state about a running domain. +=item B I I + +Convert the file I in the native guest configuration format +named by I to a domain XML format. + +=item B I I + +Convert the file I in domain XML format to the native guest +configuration format named by I. + =item B I I Dumps the core of a domain to a file for analysis. =item B I -Output the domain information as an XML dump to stdout, this format can be used by the B command. +Output the domain information as an XML dump to stdout, this format +can be used by the B command. =item B I Edit the XML configuration file for a domain. This is equivalent to: + virsh dumpxml domain > domain.xml edit domain.xml virsh define domain.xml + except that it does some error checking. The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment @@ -564,9 +591,11 @@ Output the virtual network information as an XML dump to stdout. Edit the XML configuration file for a network. This is equivalent to: + virsh net-dumpxml network > network.xml edit network.xml - virsh define network.xml + virsh net-define network.xml + except that it does some error checking. The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment @@ -596,6 +625,124 @@ Convert a network name to network UUID. =back +=head1 STORAGE POOL COMMANDS + +The following commands manipulate storage pools. Libvirt has the +capability to manage various storage solutions, including files, raw +partitions, and domain-specific formats, used to provide the storage +volumes visible as devices within virtual machines. For more detailed +information about this feature, see the documentation at +L . A lot of the commands for +pools are similar to the ones used for domains. + +=over 4 + +=item B I optional I + +Returns XML describing all storage pools of a given I that could +be found. If I is provided, it is a file that contains XML +to further restrict the query for pools. + +=item B I optional I I + +Returns XML describing all storage pools of a given I that could +be found. If I and I are provided, they control where the +query is performed. + +=item B I optional I<--disable> + +Configure whether I should automatically start at boot. + +=item B I + +Build a given pool. + +=item B I + +Create and start a pool object from the XML I. + +=item B I I<--print-xml> I optional I +I I I + +Create and start a pool object I from the raw parameters. If +I<--print-xml> is specified, then print the XML of the pool object +without creating the pool. Otherwise, the pool has the specified +I. + +=item B I + +Create, but do not start, a pool object from the XML I. + +=item B I I<--print-xml> I optional I +I I I + +Create, but do not start, a pool object I from the raw parameters. If +I<--print-xml> is specified, then print the XML of the pool object +without defining the pool. Otherwise, the pool has the specified +I. + +=item B I + +Destroy a given I object. Libvirt will no longer manage the +storage described by the pool object, but the raw data contained in +the pool is not changed, and can be later recovered with +B. + +=item B I + +Destroy the resources used by a given I object. This operation +is non-recoverable. The I object will still exist after this +command. + +=item B I + +Returns the XML information about the I object. + +=item B I + +Edit the XML configuration file for a storage pool. + +This is equivalent to: + + virsh pool-dumpxml pool > pool.xml + edit pool.xml + virsh pool-define pool.xml + +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. + +=item B I + +Returns basic information about the I object. + +=item B optional I<--inactive> I<--all> + +List pool objects known to libvirt. By default, only pools in use by +active domains are listed; I<--inactive> lists just the inactive +pools, and I<--all> lists all pools. + +=item B I + +Convert the I to a pool name. + +=item B I + +Refresh the list of volumes contained in I. + +=item B I + +Start the storage I, which is previously defined but inactive. + +=item B I + +Undefine the configuration for an inactive I. + +=item B I + +Returns the UUID of the named I. + =head1 SECRET COMMMANDS The following commands manipulate "secrets" (e.g. passwords, passphrases and @@ -702,11 +849,11 @@ format as accepted by the B option. =item VISUAL -The editor to use by the B and B options. +The editor to use by the B and related options. =item EDITOR -The editor to use by the B and B options, if C +The editor to use by the B and related options, if C is not set. =item LIBVIRT_DEBUG=LEVEL -- GitLab