commit 84bc3ac38e6dde7e2fdad12394edda31b73a26f4
Author: Chris Curran <ccurran(a)redhat.com>
Date: Wed Jun 30 14:34:49 2010 +1000
updating virsh reference
en-US/Reference_virsh.xml | 722 ++++++++++++++++++++++++---------------------
1 files changed, 381 insertions(+), 341 deletions(-)
---
diff --git a/en-US/Reference_virsh.xml b/en-US/Reference_virsh.xml
index e0e4af5..98c059d 100644
--- a/en-US/Reference_virsh.xml
+++ b/en-US/Reference_virsh.xml
@@ -330,99 +330,13 @@
</tgroup>
</table>
<para>
- The <command>virsh</command> commands for managing and creating storage
pools:
+ The <command>virsh</command> commands for managing and creating storage
pools and volumes.
+ </para>
+ <para>For more information on using storage pools with virsh, refer to <ulink
url="http://libvirt.org/formatstorage.html">http://libvirt.o...
</para>
- <screen>
- TODO
-
- 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
http://libvirt.org/formatstorage.html . A lot of the commands for
- pools are similar to the ones used for domains.
-
- find-storage-pool-sources type optional srcSpec
- Returns XML describing all storage pools of a given type that could be found.
If srcSpec is provided, it is a file that contains
- XML to further restrict the query for pools.
-
- find-storage-pool-sources type optional host port
- Returns XML describing all storage pools of a given type that could be found.
If host and port are provided, they control where
- the query is performed.
-
- pool-autostart pool-or-uuid optional --disable
- Configure whether pool should automatically start at boot.
-
-
- pool-build pool-or-uuid
- Build a given pool.
-
- pool-create file
- Create and start a pool object from the XML file.
-
- pool-create-as name --print-xml type optional source-host source-path source-dev
source-name [target]
- Create and start a pool object name from the raw parameters. If --print-xml
is specified, then print the XML of the pool object
- without creating the pool. Otherwise, the pool has the specified type.
-
- pool-define file
- Create, but do not start, a pool object from the XML file.
-
- pool-define-as name --print-xml type optional source-host source-path source-dev
source-name [target]
- Create, but do not start, a pool object name from the raw parameters. If
--print-xml is specified, then print the XML of the pool
- object without defining the pool. Otherwise, the pool has the specified
type.
-
-
-pool-destroy pool-or-uuid
- Destroy a given 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 pool-create.
-
- pool-delete pool-or-uuid
- Destroy the resources used by a given pool object. This operation is
non-recoverable. The pool object will still exist after this
- command.
-
- pool-dumpxml pool-or-uuid
- Returns the XML information about the pool object.
-
- pool-edit 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 $VISUAL or $EDITOR environment variables, and
defaults to "vi".
-
- pool-info pool-or-uuid
- Returns basic information about the pool object.
-
- pool-list optional --inactive --all
- List pool objects known to libvirt. By default, only pools in use by active
domains are listed; --inactive lists just the inactive
- pools, and --all lists all pools.
-
- pool-name uuid
- Convert the uuid to a pool name.
-
- pool-refresh pool-or-uuid
- Refresh the list of volumes contained in pool.
-
- pool-start pool-or-uuid
- Start the storage pool, which is previously defined but inactive.
-
-
-</screen>
-
-<!--
-DONE
-pool-undefine pool-or-uuid
- Undefine the configuration for an inactive pool.
-
- pool-uuid pool
- Returns the UUID of the named pool.-->
- <table frame="all"
id="tabl-Virtualization-Managing_guests_with_virsh-Storage_options">
- <title>Storage pool commands</title>
+ <table frame="all"
id="tabl-Virtualization-Managing_gunagement_options">
+ <title>Storage Pool options</title>
<tgroup cols="2">
<colspec colname="column1"></colspec>
<colspec colname="column2"></colspec>
@@ -439,94 +353,196 @@ pool-undefine pool-or-uuid
<tbody>
<row>
<entry>
- <command>pool-undefine</command>
+ find-storage-pool-sources<!-- type optional srcSpec--></entry>
+ <entry>
+ Returns the XML definition for all storage pools of a given type that could be
found.
</entry>
+ </row>
+ <row>
+ <entry>
+ <command>find-storage-pool-sources</command><!-- type optional
host--> port</entry>
+ <entry> Returns data on all storage pools of a given type that could be found
as XML. If the host and port are provided, this command can be run
remotely.</entry>
+ </row>
+ <row>
<entry>
- Deletes the configuration for an inactive pool.
+ <command>pool-autostart <!--pool-or-uuid optional
-FIXME-disable--></command>
</entry>
+ <entry>Sets the storage pool to start at boot time.</entry>
</row>
- <row>
+ <row>
<entry>
- <command>pool-uuid</command>
+ <command>pool-build<!-- pool-or-uuid--></command>
</entry>
+ <entry>The <command>pool-build</command> command builds a defined
pool. This command can format disks and create partitions. </entry>
+ </row>
+ <row>
<entry>
- Returns the UUID of the named pool.
+ <command>pool-create<!-- file--></command>
</entry>
+ <entry>
+ <command>pool-create</command> creates and starts a storage pool from
the provided XML storage pool definition file.</entry>
</row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- This table contains miscellaneous <command>virsh</command> commands:
- </para>
- <table frame="all"
id="tabl-Virtualization-Managing_guests_with_virsh-Miscellaneous_options">
- <title>Miscellaneous options</title>
- <tgroup cols="2">
- <colspec colname="column1"></colspec>
- <colspec colname="column2"></colspec>
- <thead>
- <row>
+ <row>
<entry>
- Command
+ <command>pool-create-as name<!-- -FIXME-print-xml type optional
source-host source-path source-dev source-name [target]--></command>
</entry>
+ <entry><!--FIXME -->Creates and starts a storage pool from the provided
parameters. If the <parameter>--print-xml</parameter> parameter is specified,
the command prints the XML definition for the storage pool without creating the storage
pool. </entry>
+ </row>
+ <row>
<entry>
- Description
+ <command>pool-define<!-- file--></command>
</entry>
+ <entry>Creates a storage bool from an XML definition file but does not start
the new storage pool.</entry>
</row>
- </thead>
- <tbody>
- <row>
+ <row>
<entry>
- <command>version</command>
+ <command>pool-define-as name<!-- -FIXME-print-xml type optional
source-host source-path source-dev source-name [target]--></command>
</entry>
+ <entry>Creates but does not start, a storage pool from the provided
parameters. If the <parameter>--print-xml</parameter> parameter is specified,
the command prints the XML definition for the storage pool without creating the storage
pool. </entry>
+ </row>
+ <row>
<entry>
- Displays the version of <command>virsh</command>
+ <command>pool-destroy<!-- pool-or-uuid--></command>
</entry>
+ <entry>Permanently destroys a storage pool in
<command>libvirt</command>. The raw data contained in the storage pool is not
changed and can be recovered with the <command>pool-create</command>
command.</entry>
</row>
- <row>
+ <row>
<entry>
- <command>nodeinfo</command>
+ <command>pool-delete<!-- pool-or-uuid--></command>
</entry>
+ <entry>Destroys the storage resources used by a storage pool. This operation
cannot be recovered. The storage pool still exists after this command but all data is
deleted.</entry>
+ </row>
+ <row>
<entry>
- Outputs information about the hypervisor
+ <command>pool-dumpxml<!-- pool-or-uuid--></command>
</entry>
+ <entry>Prints the XML definition for a storage pool.</entry>
</row>
- </tbody>
- </tgroup>
- </table>
-
+ <row>
+ <entry>
+ <command>pool-edit<!-- pool-or-uuid--></command>
+ </entry>
+ <entry>Opens the XML definition file for a storage pool in the users default
text editor. </entry>
+ </row>
+ <row>
+ <entry>
+ <command>pool-info<!-- pool-or-uuid--></command>
+ </entry>
+ <entry>Returns information about a storage pool.</entry>
+ </row>
+ <row>
+ <entry><command>pool-list<!-- optional -FIXME-inactive
-FIXME-all--></command>
+ </entry>
+ <entry>Lists storage pools known to libvirt. By default,
<command>pool-list</command> lists pools in use by active guests. The
<parameter>--inactive</parameter> parameter lists inactive pools and the
<parameter>--all</parameter> parameter lists all pools.</entry>
+ </row>
+ <row>
+ <entry>
+ <command>pool-undefine</command>
+ </entry>
+ <entry>
+ Deletes the definition for an inactive storage pool.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <command>pool-uuid</command>
+ </entry>
+ <entry>
+ Returns the UUID of the named pool.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <command>pool-name <!--uuid--></command>
+ </entry>
+ <entry>Prints a storage pool's name when provided the UUID of a storage
pool.</entry>
+ </row>
+ <row>
+ <entry>
+ <command>pool-refresh<!-- pool-or-uuid--></command>
+ </entry>
+ <entry>Refreshs the list of volumes contained in a storage pool.</entry>
+ </row>
+ <row>
+ <entry>
+ <command>pool-start<!-- pool-or-uuid--></command>
+ </entry>
+ <entry>Starts a storage pool that is defined but inactive.</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+</table>
+<para>
+ This table contains miscellaneous <command>virsh</command> commands:
+ </para>
+<table frame="all"
id="tabl-Virtualization-Managing_guests_with_virsh-Miscellaneous_options">
+ <title>Miscellaneous options</title>
+ <tgroup cols="2">
+ <colspec colname="column1"></colspec>
+ <colspec colname="column2"></colspec>
+ <thead>
+ <row>
+ <entry>
+ Command
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <command>version</command>
+ </entry>
+ <entry>
+ Displays the version of <command>virsh</command>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <command>nodeinfo</command>
+ </entry>
+ <entry>
+ Outputs information about the hypervisor
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Connecting_to_the_hypervisor">
- <title>Connecting to the hypervisor</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Connecting_to_the_hypervisor">
+ <title>Connecting to the hypervisor</title>
+ <para>
Connect to a hypervisor session with <command>virsh</command>:
</para>
- </formalpara>
+</formalpara>
<screen># virsh connect <parameter>{hostname OR URL}</parameter>
</screen>
- <para>
+<para>
Where <command><name></command> is the machine name of the
hypervisor. To initiate a read-only connection, append the above command with
<command>-readonly</command>.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Creating_a_virtual_machine_XML_dump_configuration_file">
- <title>Creating a virtual machine XML dump (configuration file)</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Creating_a_virtual_machine_XML_dump_configuration_file">
+ <title>Creating a virtual machine XML dump (configuration file)</title>
+ <para>
Output a guest's XML configuration file with
<command>virsh</command>:
</para>
- </formalpara>
+</formalpara>
<screen># virsh dumpxml <parameter>{guest-id, guestname or
uuid}</parameter>
</screen>
- <para>
+<para>
This command outputs the guest's XML configuration file to standard out
(<command>stdout</command>). You can save the data by piping the output to a
file. An example of piping the output to a file called
<replaceable>guest.xml</replaceable>:
</para>
<screen># virsh dumpxml <replaceable>GuestID</replaceable> >
<replaceable>guest.xml</replaceable>
</screen>
- <para>
+<para>
This file <filename>guest.xml</filename> can recreate the guest (refer to
<xref
linkend="form-Virtualization-Managing_guests_with_virsh-Editing_a_guests_configuration_file"
/>. You can edit this XML configuration file to configure additional devices or to
deploy additional guests. Refer to <xref
linkend="sect-Virtualization-Creating_custom_libvirt_scripts-Using_XML_configuration_files_with_virsh"
/> for more information on modifying files created with <command>virsh
dumpxml</command>.
</para>
- <para>
+<para>
An example of <command>virsh dumpxml</command> output:
</para>
<!--TODO dump a KVM file-->
@@ -557,155 +573,155 @@ pool-undefine pool-or-uuid
</devices>
</domain>
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Creating_a_guest_from_a_configuration_file">
- <title>Creating a guest from a configuration file</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Creating_a_guest_from_a_configuration_file">
+ <title>Creating a guest from a configuration file</title>
+ <para>
Guests can be created from XML configuration files. You can copy existing XML from
previously created guests or use the <command>dumpxml</command> option (refer
to <xref
linkend="form-Virtualization-Managing_guests_with_virsh-Creating_a_virtual_machine_XML_dump_configuration_file"
/>). To create a guest with <command>virsh</command> from an XML file:
</para>
- </formalpara>
+</formalpara>
<screen># virsh create
<replaceable>configuration_file.xml</replaceable>
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Editing_a_guests_configuration_file">
- <title>Editing a guest's configuration file</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Editing_a_guests_configuration_file">
+ <title>Editing a guest's configuration file</title>
+ <para>
Instead of using the <command>dumpxml</command> option (refer to <xref
linkend="form-Virtualization-Managing_guests_with_virsh-Creating_a_virtual_machine_XML_dump_configuration_file"
/>) guests can be edited either while they run or while they are offline. The
<command>virsh edit</command> command provides this functionality. For
example, to edit the guest named <parameter>softwaretesting</parameter>:
</para>
- </formalpara>
+</formalpara>
<screen># virsh edit <parameter>softwaretesting</parameter>
</screen>
- <para>
+<para>
This opens a text editor. The default text editor is the
<command>$EDITOR</command> shell parameter (set to
<command>vi</command> by default).
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Suspending_a_guest">
- <title>Suspending a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Suspending_a_guest">
+ <title>Suspending a guest</title>
+ <para>
Suspend a guest with <command>virsh</command>:
</para>
- </formalpara>
+</formalpara>
<screen># virsh suspend <parameter>{domain-id, domain-name or
domain-uuid}</parameter>
</screen>
- <para>
+<para>
When a guest is in a suspended state, it consumes system RAM but not processor
resources. Disk and network I/O does not occur while the guest is suspended. This
operation is immediate and the guest can be restarted with the
<command>resume</command> (<xref
linkend="form-Virtualization-Managing_guests_with_virsh-Resuming_a_guest" />)
option.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Resuming_a_guest">
- <title>Resuming a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Resuming_a_guest">
+ <title>Resuming a guest</title>
+ <para>
Restore a suspended guest with <command>virsh</command> using the
<command>resume</command> option:
</para>
- </formalpara>
+</formalpara>
<screen># virsh resume <parameter>{domain-id, domain-name or
domain-uuid}</parameter>
</screen>
- <para>
+<para>
This operation is immediate and the guest parameters are preserved for
<command>suspend</command> and <command>resume</command>
operations.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Save_a_guest">
- <title>Save a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Save_a_guest">
+ <title>Save a guest</title>
+ <para>
Save the current state of a guest to a file using the
<command>virsh</command> command:
</para>
- </formalpara>
+</formalpara>
<screen># virsh save <parameter>{domain-name, domain-id or domain-uuid}
filename</parameter>
</screen>
- <para>
+<para>
This stops the guest you specify and saves the data to a file, which may take some time
given the amount of memory in use by your guest. You can restore the state of the guest
with the <command>restore</command> (<xref
linkend="form-Virtualization-Managing_guests_with_virsh-Restore_a_guest" />)
option. Save is similar to pause, instead of just pausing a guest the present state of the
guest is saved.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Restore_a_guest">
- <title>Restore a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Restore_a_guest">
+ <title>Restore a guest</title>
+ <para>
Restore a guest previously saved with the <command>virsh save</command>
command (<xref
linkend="form-Virtualization-Managing_guests_with_virsh-Save_a_guest" />)
using <command>virsh</command>:
</para>
- </formalpara>
+</formalpara>
<screen># virsh restore <parameter>filename</parameter>
</screen>
- <para>
+<para>
This restarts the saved guest, which may take some time. The guest's name and UUID
are preserved but are allocated for a new id.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Shut_down_a_guest">
- <title>Shut down a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Shut_down_a_guest">
+ <title>Shut down a guest</title>
+ <para>
Shut down a guest using the <command>virsh</command> command:
</para>
- </formalpara>
+</formalpara>
<screen># virsh shutdown <parameter>{domain-id, domain-name or
domain-uuid}</parameter>
</screen>
- <para>
+<para>
You can control the behavior of the rebooting guest by modifying the
<command>on_shutdown</command> parameter in the guest's configuration
file.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Rebooting_a_guest">
- <title>Rebooting a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Rebooting_a_guest">
+ <title>Rebooting a guest</title>
+ <para>
Reboot a guest using <command>virsh</command> command:
</para>
- </formalpara>
+</formalpara>
<screen>#virsh reboot <parameter>{domain-id, domain-name or
domain-uuid}</parameter>
</screen>
- <para>
+<para>
You can control the behavior of the rebooting guest by modifying the
<command>on_reboot</command> element in the guest's configuration file.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Forcing_a_guest_to_stop">
- <title>Forcing a guest to stop</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Forcing_a_guest_to_stop">
+ <title>Forcing a guest to stop</title>
+ <para>
Force a guest to stop with the <command>virsh</command> command:
</para>
- </formalpara>
+</formalpara>
<screen># virsh destroy <parameter>{domain-id, domain-name or
domain-uuid}</parameter>
</screen>
- <para>
+<para>
This command does an immediate ungraceful shutdown and stops the specified guest. Using
<command>virsh destroy</command> can corrupt guest file systems . Use the
<command>destroy</command> option only when the guest is unresponsive.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Getting_the_domain_ID_of_a_guest">
- <title>Getting the domain ID of a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Getting_the_domain_ID_of_a_guest">
+ <title>Getting the domain ID of a guest</title>
+ <para>
To get the domain ID of a guest:
</para>
- </formalpara>
+</formalpara>
<screen># virsh domid <parameter>{domain-name or
domain-uuid}</parameter>
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Getting_the_domain_name_of_a_guest">
- <title>Getting the domain name of a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Getting_the_domain_name_of_a_guest">
+ <title>Getting the domain name of a guest</title>
+ <para>
To get the domain name of a guest:
</para>
- </formalpara>
+</formalpara>
<screen># virsh domname <parameter>{domain-id or
domain-uuid}</parameter>
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Getting_the_UUID_of_a_guest">
- <title>Getting the UUID of a guest</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Getting_the_UUID_of_a_guest">
+ <title>Getting the UUID of a guest</title>
+ <para>
To get the Universally Unique Identifier (UUID) for a guest:
</para>
- </formalpara>
+</formalpara>
<screen># virsh domuuid <replaceable>{domain-id or
domain-name}</replaceable>
</screen>
- <para>
+<para>
An example of <command>virsh domuuid</command> output:
</para>
<screen># virsh domuuid r5b2-mySQL01
4a4c59a7-ee3f-c781-96e4-288f2862f011
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_guest_Information_">
- <title>Displaying guest Information </title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_guest_Information_">
+ <title>Displaying guest Information </title>
+ <para>
Using <command>virsh</command> with the guest's domain ID, domain name
or UUID you can display information on the specified guest:
</para>
- </formalpara>
+</formalpara>
<screen># virsh dominfo <parameter>{domain-id, domain-name or
domain-uuid}</parameter>
</screen>
- <para>
+<para>
This is an example of <command>virsh dominfo</command> output:
</para>
@@ -720,16 +736,16 @@ cpu time: 11.0s
max memory: 512000 kb
used memory: 512000 kb
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_host_information">
- <title>Displaying host information</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_host_information">
+ <title>Displaying host information</title>
+ <para>
To display information about the host:
</para>
- </formalpara>
+</formalpara>
<screen># virsh nodeinfo
</screen>
- <para>
+<para>
An example of <command>virsh nodeinfo</command> output:
</para>
@@ -743,28 +759,44 @@ Threads per core: 2
Numa cell(s) 1
Memory size: 1046528 kb
</screen>
- <para>
+<para>
This displays the node information and the machines that support the virtualization
process.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_the_guests">
- <title>Displaying the guests</title>
- <para>
+
+<formalpara>
+ <title>Editing a storage pool definition</title>
+ <para>The <command>virsh pool-edit</command> command takes the name or
UUID for a storage pool and opens the XML definition file for a storage pool in the users
default text editor.</para>
+</formalpara>
+<para><para>The <command>virsh pool-edit</command> command is
equivalent to running the following commands:</para>
+<screen># virsh pool-dumpxml <parameter>pool</parameter> <
<parameter>pool</parameter>.xml
+# vim <parameter>pool</parameter>.xml
+# virsh pool-define <parameter>pool</parameter>.xml
+</screen>
+
+<note>
+<title>Note</title>
+<para>The default editor is defined by the <command>$VISUAL</command>
or <command>$EDITOR</command> environment variables, and default is
<command>vi</command>.</para>
+</note>
+
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_the_guests">
+<title>Displaying the guests</title>
+<para>
To display the guest list and their current states with
<command>virsh</command>:
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh list
</screen>
- <para>
+<para>
Other options available include:
</para>
- <para>
+<para>
the <command>--inactive</command> option to list inactive guests (that is,
guests that have been defined but are not currently active), and
</para>
- <para>
+<para>
the <command>--all</command> option lists all guests. For example:
</para>
-
+
<screen># virsh list --all
Id Name State
----------------------------------
@@ -773,54 +805,54 @@ Memory size: 1046528 kb
2 Domain010 inactive
3 Domain9600 crashed
</screen>
- <para>
+<para>
The output from <command>virsh list</command> is categorized as one of the
six states (listed below).
</para>
- <itemizedlist>
- <listitem>
- <para>
+<itemizedlist>
+<listitem>
+ <para>
The <computeroutput>running</computeroutput> state refers to guests which
are currently active on a CPU.
</para>
- </listitem>
- <listitem>
- <para>
+</listitem>
+<listitem>
+ <para>
Guests listed as <computeroutput>blocked</computeroutput> are blocked,
and are not running or runnable. This is caused by a guest waiting on I/O (a traditional
wait state) or guests in a sleep mode.
</para>
- </listitem>
- <listitem>
- <para>
+</listitem>
+<listitem>
+ <para>
The <computeroutput>paused</computeroutput> state lists domains that are
paused. This occurs if an administrator uses the <guilabel>pause</guilabel>
button in <command>virt-manager</command>, <command>xm
pause</command> or <command>virsh suspend</command>. When a guest is
paused it consumes memory and other resources but it is ineligible for scheduling and CPU
resources from the hypervisor.
</para>
- </listitem>
- <listitem>
- <para>
+</listitem>
+<listitem>
+ <para>
The <computeroutput>shutdown</computeroutput> state is for guests in the
process of shutting down. The guest is sent a shutdown signal and should be in the process
of stopping its operations gracefully. This may not work with all guest operating systems;
some operating systems do not respond to these signals.
</para>
- </listitem>
- <listitem>
- <para>
+</listitem>
+<listitem>
+ <para>
Domains in the <computeroutput>dying</computeroutput> state are in is in
process of dying, which is a state where the domain has not completely shut-down or
crashed.
</para>
- </listitem>
- <listitem>
- <para>
- <computeroutput>crashed</computeroutput> guests have failed while running
and are no longer running. This state can only occur if the guest has been configured not
to restart on crash. <!-- Refer to the domain
configuration manual page (<command> man xmdomain.cfg</command>) for more
information. -->
- </para>
- </listitem>
- </itemizedlist>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_virtual_CPU_information">
- <title>Displaying virtual CPU information</title>
- <para>
+</listitem>
+<listitem>
+ <para>
+ <computeroutput>crashed</computeroutput> guests have failed while running
and are no longer running. This state can only occur if the guest has been configured not
to restart on crash. <!-- Refer to the domain
configuration manual page (<command> man xmdomain.cfg</command>) for more
information. -->
+ </para>
+</listitem>
+</itemizedlist>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_virtual_CPU_information">
+<title>Displaying virtual CPU information</title>
+<para>
To display virtual CPU information from a guest with
<command>virsh</command>:
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh vcpuinfo <replaceable>{domain-id, domain-name or
domain-uuid}</replaceable>
</screen>
- <para>
+<para>
An example of <command>virsh vcpuinfo</command> output:
</para>
-
+
<screen># virsh vcpuinfo r5b2-mySQL01
VCPU: 0
CPU: 0
@@ -828,117 +860,117 @@ State: blocked
CPU time: 0.0s
CPU Affinity: yy
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Configuring_virtual_CPU_affinity">
- <title>Configuring virtual CPU affinity</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Configuring_virtual_CPU_affinity">
+<title>Configuring virtual CPU affinity</title>
+<para>
To configure the affinity of virtual CPUs with physical CPUs:
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh vcpupin <parameter>domain-id vcpu cpulist</parameter>
</screen>
- <para>
+<para>
The <command>domain-id</command> parameter is the guest's ID number or
name.
</para>
- <para>
+<para>
The <command>vcpu</command> parameter denotes the number of virtualized
CPUs allocated to the guest.The <command>vcpu</command> parameter must be
provided.
</para>
- <para>
+<para>
The <command>cpulist</command> parameter is a list of physical CPU
identifier numbers separated by commas. The <command>cpulist</command>
parameter determines which physical CPUs the VCPUs can run on.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Configuring_virtual_CPU_count">
- <title>Configuring virtual CPU count</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Configuring_virtual_CPU_count">
+<title>Configuring virtual CPU count</title>
+<para>
To modify the number of CPUs assigned to a guest with
<command>virsh</command>:
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh setvcpus <parameter>{domain-name, domain-id or domain-uuid}
count</parameter>
</screen>
- <para>
+<para>
The new <parameter>count</parameter> value cannot exceed the count above
the amount specified when the guest was created.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Configuring_memory_allocation">
- <title>Configuring memory allocation</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Configuring_memory_allocation">
+<title>Configuring memory allocation</title>
+<para>
To modify a guest's memory allocation with <command>virsh</command> :
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh setmem {domain-id or domain-name} count
</screen>
- <para>
+<para>
You must specify the <emphasis>count</emphasis> in kilobytes. The new count
value cannot exceed the amount you specified when you created the guest. Values lower than
64 MB are unlikely to work with most guest operating systems. A higher maximum memory
value does not affect an active guests. If the new value is lower the available memory
will shrink and the guest may crash.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_guest_block_device_information">
- <title>Displaying guest block device information</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_guest_block_device_information">
+<title>Displaying guest block device information</title>
+<para>
Use <command>virsh domblkstat</command> to display block device statistics
for a running guest.
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh domblkstat <replaceable>GuestName
block-device</replaceable>
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_guest_network_device_information">
- <title>Displaying guest network device information</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Displaying_guest_network_device_information">
+<title>Displaying guest network device information</title>
+<para>
Use <command>virsh domifstat</command> to display network interface
statistics for a running guest.
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh domifstat <replaceable>GuestName interface-device
</replaceable>
</screen>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Migrating_guests_with_virsh">
- <title>Migrating guests with virsh</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Migrating_guests_with_virsh">
+<title>Migrating guests with virsh</title>
+<para>
A guest can be migrated to another host with <command>virsh</command>.
Migrate domain to another host. Add --live for live migration. The
<command>migrate</command> command accepts parameters in the following
format:
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh migrate --live <parameter>GuestName
DestinationURL</parameter>
</screen>
- <para>
+<para>
The <parameter>--live</parameter> parameter is optional. Add the
<parameter>--live</parameter> parameter for live migrations.
</para>
- <para>
+<para>
The <parameter>GuestName</parameter> parameter represents the name of the
guest which you want to migrate.
</para>
- <para>
+<para>
The <parameter>DestinationURL</parameter> parameter is the URL or hostname
of the destination system. The destination system requires:
</para>
- <itemizedlist>
- <listitem>
- <para>
- Fedora 9 or newer,
+<itemizedlist>
+<listitem>
+ <para>
+ Red Hat Enterprise Linux 5.4 (ASYNC update 4) or newer,
</para>
- </listitem>
- <listitem>
- <para>
+</listitem>
+<listitem>
+ <para>
the same hypervisor version, and
</para>
- </listitem>
- <listitem>
- <para>
+</listitem>
+<listitem>
+ <para>
the <command>libvirt</command> service must be started.
</para>
- </listitem>
- </itemizedlist>
- <para>
+</listitem>
+</itemizedlist>
+<para>
Once the command is entered you will be prompted for the root password of the
destination system.
</para>
- <formalpara
id="form-Virtualization-Managing_guests_with_virsh-Managing_virtual_networks">
- <title>Managing virtual networks</title>
- <para>
+<formalpara
id="form-Virtualization-Managing_guests_with_virsh-Managing_virtual_networks">
+<title>Managing virtual networks</title>
+<para>
This section covers managing virtual networks with the
<command>virsh</command> command. To list virtual networks:
</para>
- </formalpara>
-
+</formalpara>
+
<screen># virsh net-list
</screen>
- <para>
+<para>
This command generates output similar to:
</para>
-
+
<screen># virsh net-list
Name State Autostart
-----------------------------------------
@@ -946,16 +978,16 @@ default active yes
vnet1 active yes
vnet2 active yes
</screen>
- <para>
+<para>
To view network information for a specific virtual network:
</para>
-
+
<screen># virsh net-dumpxml <replaceable>NetworkName</replaceable>
</screen>
- <para>
+<para>
This displays information about a specified virtual network in XML format:
</para>
-
+
<screen># virsh net-dumpxml vnet1
<network>
<name>vnet1</name>
@@ -969,56 +1001,64 @@ vnet2 active yes
</ip>
</network>
</screen>
- <para>
+<para>
Other <command>virsh</command> commands used in managing virtual networks
are:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <command>virsh net-autostart
<replaceable>network-name</replaceable></command> — Autostart
a network specified as <replaceable>network-name</replaceable>.
+<itemizedlist>
+<listitem>
+ <para>
+ <command>virsh net-autostart <replaceable>network-name</replaceable>
+ </command> — Autostart a network specified as
<replaceable>network-name</replaceable>.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-create
<replaceable>XMLfile</replaceable></command> — generates and
starts a new network using an existing XML file.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-create <replaceable>XMLfile</replaceable>
+ </command> — generates and starts a new network using an existing XML
file.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-define
<replaceable>XMLfile</replaceable></command> — generates a new
network device from an existing XML file without starting it.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-define <replaceable>XMLfile</replaceable>
+ </command> — generates a new network device from an existing XML file
without starting it.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-destroy
<replaceable>network-name</replaceable></command> — destroy a
network specified as <replaceable>network-name</replaceable>.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-destroy <replaceable>network-name</replaceable>
+ </command> — destroy a network specified as
<replaceable>network-name</replaceable>.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-name
<replaceable>networkUUID</replaceable></command> — convert a
specified <replaceable>networkUUID</replaceable> to a network name.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-name <replaceable>networkUUID</replaceable>
+ </command> — convert a specified
<replaceable>networkUUID</replaceable> to a network name.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-uuid
<replaceable>network-name</replaceable></command> — convert a
specified <replaceable>network-name</replaceable> to a network UUID.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-uuid <replaceable>network-name</replaceable>
+ </command> — convert a specified
<replaceable>network-name</replaceable> to a network UUID.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-start
<replaceable>nameOfInactiveNetwork</replaceable></command> —
starts an inactive network.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-start
<replaceable>nameOfInactiveNetwork</replaceable>
+ </command> — starts an inactive network.
</para>
- </listitem>
- <listitem>
- <para>
- <command>virsh net-undefine
<replaceable>nameOfInactiveNetwork</replaceable></command> —
removes the definition of an inactive network.
+</listitem>
+<listitem>
+ <para>
+ <command>virsh net-undefine
<replaceable>nameOfInactiveNetwork</replaceable>
+ </command> — removes the definition of an inactive network.
</para>
- </listitem>
- </itemizedlist>
+</listitem>
+</itemizedlist>
<!--<formalpara
id="virshpool1"><title></title><para></para></formalpara>
<formalpara
id="virshpool2"><title></title><para></para></formalpara>
<formalpara
id="virshpool3"><title></title><para></para></formalpara>
<formalpara
id="virshpool4"><title></title><para></para></formalpara>
<formalpara
id="virshpool5"><title></title><para></para></formalpara>-->
-
+
</chapter>