External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-02-21 10:52:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

virsh: improve documentation

Browse Source 
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.
This commit is contained in:
Eric Blake 2010-04-05 17:21:02 -06:00
parent 28b9a6c769
commit 9f337ef752
1 changed files with 160 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
tools/virsh.pod
View File

@ -103,10 +103,12 @@ Will print the current directory.
=item B<connect> I<URI> optional I<--readonly>
(Re)-Connect to the hypervisor. This is a build-in command after shell
start up, and usually get an I<URI> parameter specifying how to connect
to the hypervisor. The documentation page at L<http://libvirt.org/uri.html>
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<URI> parameter requested by the C<-c>
option on the command line. The I<URI> parameter specifies how to
connect to the hypervisor. The documentation page at
L<http://libvirt.org/uri.html> 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<domain-id> 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<console> I<domain-id>
@ -260,11 +262,15 @@ Connect the virtual serial console for the guest.
=item B<create> I<FILE>
Create a domain from an XML <file>. An easy way to create the XML <file> is to use the B<dumpxml> command to obtain the definition of a pre-existing guest.
Create a domain from an XML <file>. An easy way to create the XML
<file> is to use the B<dumpxml> command to obtain the definition of a
pre-existing guest.
B<Example>
virsh dumpxml <domain-id> > file.
virsh dumpxml <domain-id> > domain.xml
edit domain.xml
virsh create < domain.xml
=item B<define> I<FILE>
@ -306,6 +312,14 @@ Convert a domain name (or UUID) to a domain id
Returns basic information about the domain.
=item B<domjobabort I<domain-id-or-uuid>
Abort the currently running domain job.
=item B<domjobinfo> I<domain-id-or-uuid>
Returns information about jobs running on a domain.
=item B<domname> I<domain-id-or-uuid>
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<domxml-from-native> I<format> I<config>
Convert the file I<config> in the native guest configuration format
named by I<format> to a domain XML format.
=item B<domxml-to-native> I<format> I<xml>
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>
Dumps the core of a domain to a file for analysis.
=item B<dumpxml> I<domain-id>
Output the domain information as an XML dump to stdout, this format can be used by the B<create> command.
Output the domain information as an XML dump to stdout, this format
can be used by the B<create> command.
=item B<edit> I<domain-id>
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<http://libvirt.org/formatstorage.html> . A lot of the commands for
pools are similar to the ones used for domains.
=over 4
=item B<find-storage-pool-sources> I<type> optional I<srcSpec>
Returns XML describing all storage pools of a given I<type> that could
be found. If I<srcSpec> is provided, it is a file that contains XML
to further restrict the query for pools.
=item B<find-storage-pool-sources> I<type> optional I<host> I<port>
Returns XML describing all storage pools of a given I<type> that could
be found. If I<host> and I<port> are provided, they control where the
query is performed.
=item B<pool-autostart> I<pool-or-uuid> optional I<--disable>
Configure whether I<pool> should automatically start at boot.
=item B<pool-build> I<pool-or-uuid>
Build a given pool.
=item B<pool-create> I<file>
Create and start a pool object from the XML I<file>.
=item B<pool-create-as> I<name> I<--print-xml> I<type> optional I<source-host>
I<source-path> I<source-dev> I<source-name> <target>
Create and start a pool object I<name> 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<type>.
=item B<pool-define> I<file>
Create, but do not start, a pool object from the XML I<file>.
=item B<pool-define-as> I<name> I<--print-xml> I<type> optional I<source-host>
I<source-path> I<source-dev> I<source-name> <target>
Create, but do not start, a pool object I<name> 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<type>.
=item B<pool-destroy> I<pool-or-uuid>
Destroy a given I<pool> 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<pool-create>.
=item B<pool-delete> I<pool-or-uuid>
Destroy the resources used by a given I<pool> object. This operation
is non-recoverable. The I<pool> object will still exist after this
command.
=item B<pool-dumpxml> I<pool-or-uuid>
Returns the XML information about the I<pool> object.
=item B<pool-edit> I<pool-or-uuid>
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<vi>.
=item B<pool-info> I<pool-or-uuid>
Returns basic information about the I<pool> object.
=item B<pool-list> 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<pool-name> I<uuid>
Convert the I<uuid> to a pool name.
=item B<pool-refresh> I<pool-or-uuid>
Refresh the list of volumes contained in I<pool>.
=item B<pool-start> I<pool-or-uuid>
Start the storage I<pool>, which is previously defined but inactive.
=item B<pool-undefine> I<pool-or-uuid>
Undefine the configuration for an inactive I<pool>.
=item B<pool-uuid> I<pool>
Returns the UUID of the named I<pool>.
=head1 SECRET COMMMANDS
The following commands manipulate "secrets" (e.g. passwords, passphrases and
@ -702,11 +849,11 @@ format as accepted by the B<connect> option.
=item VISUAL
The editor to use by the B<edit> and B<net-edit> options.
The editor to use by the B<edit> and related options.
=item EDITOR
The editor to use by the B<edit> and B<net-edit> options, if C<VISUAL>
The editor to use by the B<edit> and related options, if C<VISUAL>
is not set.
=item LIBVIRT_DEBUG=LEVEL