[libvirt] [PATCH] nodedev: document virsh nodedev-* commands

Eric Blake eblake at redhat.com
Fri Sep 23 23:28:16 UTC 2011 

This section of the man page was completely missing; I stumbled on
it when I had no clue that I had to use nodedev-reattach after
I was done playing with <hostdev> device passthrough to one of my
guests.

* tools/virsh.pod (NODEDEV COMMANDS): New section.
---

I also need to write something useful for http://libvirt.org/formatnode.html,
but that's a patch for another day.

Please double-check this for technical accuracy.

 tools/virsh.pod |  315 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 241 insertions(+), 74 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 43ed1ea..e9f415a 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -1163,84 +1163,251 @@ is not available the processes will provide an exit code of 1.

 =back

-=head1 DEVICE COMMANDS
+=head1 NODEDEV COMMANDS
+
+The following commands manipulate host devices that are intended to be
+passed through to guest domains via <hostdev> elements in a domain's
+<devices> section.  A node device key is generally specified by the bus
+name followed by its address, using underscores between all components,
+such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
+The B<nodedev-list> gives the full list of host devices that are known
+to libvirt, although this includes devices that cannot be assigned to
+a guest (for example, attempting to detach the PCI device that controls
+the host's hard disk controller where the guest's disk images live could
+cause the host system to lock up or reboot).
+
+For more information on node device definition see:
+L<http://libvirt.org/formatnode.html>.
+
+Passthrough devices cannot be simultaneously used by the host and its
+guest domains.  Attempts to use a passthrough <hostdev> for a guest may
+have the ability to behave as if B<nodedev-dettach> had been called,
+although making this call explicitly is safe.  Once a guest no longer
+needs a passthrough device, reversing the process so that the host can
+again use the device requires the explicit use of B<nodedev-reattach>.

-The following commands manipulate devices associated to domains.
-The domain-id can be specified as a short integer, a name or a full UUID.
-To better understand the values allowed as options for the command
-reading the documentation at L<http://libvirt.org/formatdomain.html> on the
-format of the device sections to get the most accurate set of accepted values.
+=over 4
+
+=item B<nodedev-create> I<FILE>
+
+Create a device on the host node that can then be assigned to virtual
+machines. Normally, libvirt is able to automatically determine which
+host nodes are available for use, but this allows registration of
+host hardware that libvirt did not automatically detect.  I<file>
+contains xml for a top-level <device> description of a node device.
+
+=item B<nodedev-destroy> I<nodedev>
+
+Destroy (stop) a device on the host.  Note that this makes libvirt
+quit managing a host device, and may even make that device unusable
+by the rest of the physical host until a reboot.
+
+=item B<nodedev-dettach> I<nodedev>
+
+Detach I<nodedev> from the host, so that it can safely be used by
+guests via <hostdev> passthrough.  This is reversed with
+B<nodedev-reattach>.
+
+=item B<nodedev-dumpxml> I<nodedev>
+
+Dump a <device> XML representation for the given node device, including
+such information as the device name, which bus owns the device, the
+vendor and product id, and any capabilities of the device usable by
+libvirt (such as whether device reset is supported).
+
+=item B<nodedev-list> I<cap> I<--tree>
+
+List all of the devices available on the node that are known by libvirt.
+If I<cap> is used, the list is filtered to show only the nodes that
+include the given capability.  If I<--tree> is used, the output is
+formatted in a tree representing parents of each node.
+
+=item B<nodedev-reattach> I<nodedev>
+
+Declare that I<nodedev> is no longer in use by any guests, and that
+the host can resume normal use of the device.  While libvirt can
+sometimes perform an implicit B<nodedev-dettach> when creating a
+guest, it currently requires an explicit B<nodedev-reattach> after
+the last guest use of the device before the host regains full control.
+
+=item B<nodedev-reset> I<nodedev>
+
+Trigger a device reset for I<nodedev>, useful prior to transferring
+a node device between guest passthrough or the host.  Libvirt will
+often do this action implicitly when required, but this command
+allows an explicit reset when needed.
+
+=back
+
+=head1 SNAPSHOT COMMMANDS
+
+The following commands manipulate domain snapshots.  Snapshots take the
+disk, memory, and device state of a domain at a point-of-time, and save it
+for future use.  They have many uses, from saving a "clean" copy of an OS
+image to saving a domain's state before a potentially destructive operation.
+Snapshots are identified with a unique name.  See
+L<http://libvirt.org/formatsnapshot.html> for documentation of the XML format
+used to represent properties of snapshots.

 =over 4

-=item B<attach-device> I<domain-id> I<FILE>
-
-Attach a device to the domain, using a device definition in an XML file.
-See the documentation to learn about libvirt XML format for a device.
-For cdrom and floppy devices, this command only replaces the media within
-the single existing device; consider using B<update-device> for this usage.
-
-=item B<attach-disk> I<domain-id> I<source> I<target>
-[I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>]
-[I<--type type>] [I<--mode mode>] [I<--persistent>] [I<--sourcetype soucetype>]
-[I<--serial serial>] [I<--shareable>] [I<--address address>]
-
-Attach a new disk device to the domain.
-I<source> and I<target> are paths for the files and devices.
-I<driver> can be I<file>, I<tap> or I<phy> for the Xen hypervisor depending on
-the kind of access; or I<qemu> for the QEMU emulator.
-I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default,
-although this use only replaces the media within the existing virtual cdrom or
-floppy device; consider using B<update-device> for this usage instead.
-I<mode> can specify the two specific mode I<readonly> or I<shareable>.
-I<persistent> indicates the changes will affect the next boot of the domain.
-I<sourcetype> can indicate the type of source (block|file)
-I<cache> can be one of "default", "none", "writethrough", "writeback",
-"directsync" or "unsafe".
-I<serial> is the serial of disk device. I<shareable> indicates the disk device
-is shareable between domains.
-I<address> is the address of disk device in the form of pci:domain.bus.slot.function,
-scsi:controller.bus.unit or ide:controller.bus.unit.
-
-=item B<attach-interface> I<domain-id> I<type> I<source>
-[I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>]
-[I<--persistent>]
-
-Attach a new network interface to the domain.
-I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
-I<source> indicates the source device.
-I<target> allows to indicate the target device in the guest.
-I<mac> allows to specify the MAC address of the network interface.
-I<script> allows to specify a path to a script handling a bridge instead of
-the default one.
-I<model> allows to specify the model type.
-I<persistent> indicates the changes will affect the next boot of the domain.
-
-=item B<detach-device> I<domain-id> I<FILE>
-
-Detach a device from the domain, takes the same kind of XML descriptions
-as command B<attach-device>.
-
-=item B<detach-disk> I<domain-id> I<target>
-
-Detach a disk device from a domain. The I<target> is the device as seen
-from the domain.
-
-=item B<detach-interface> I<domain-id> I<type> [I<--mac mac>]
-
-Detach a network interface from a domain.
-I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
-It is recommended to use the I<mac> option to distinguish between the interfaces
-if more than one are present on the domain.
-
-=item B<update-device> I<domain-id> I<file> [I<--persistent>] [I<--force>]
-
-Update the characteristics of a device associated with I<domain-id>, based on
-the device definition in an XML I<file>.  If the I<--persistent> option is
-used, the changes will affect the next boot of the domain. The I<--force>
-option can be used to force device update, e.g., to eject a CD-ROM even if it
-is locked/mounted in the domain. See the documentation to learn about libvirt
-XML format for a device.
+=item B<snapshot-create> I<domain> [I<xmlfile>] {[I<--redefine> [I<--current>]]
+| [I<--no-metadata>] [I<--halt>] [I<--disk-only>]}
+
+Create a snapshot for domain I<domain> with the properties specified in
+I<xmlfile>.  Normally, the only properties settable for a domain snapshot
+are the <name> and <description> elements, as well as <disks> if
+I<--disk-only> is given; the rest of the fields are
+ignored, and automatically filled in by libvirt.  If I<xmlfile> is
+completely omitted, then libvirt will choose a value for all fields.
+The new snapshot will become current, as listed by B<snapshot-current>.
+
+If I<--halt> is specified, the domain will be left in an inactive state
+after the snapshot is created.
+
+If I<--disk-only> is specified, the snapshot will only include disk
+state rather than the usual system checkpoint with vm state.  Disk
+snapshots are faster than full system checkpoints, but reverting to a
+disk snapshot may require fsck or journal replays, since it is like
+the disk state at the point when the power cord is abruptly pulled;
+and mixing I<--halt> and I<--disk-only> loses any data that was not
+flushed to disk at the time.
+
+If I<--redefine> is specified, then all XML elements produced by
+B<snapshot-dumpxml> are valid; this can be used to migrate snapshot
+hierarchy from one machine to another, to recreate hierarchy for the
+case of a transient domain that goes away and is later recreated with
+the same name and UUID, or to make slight alterations in the snapshot
+metadata (such as host-specific aspects of the domain XML embedded in
+the snapshot).  When this flag is supplied, the I<xmlfile> argument
+is mandatory, and the domain's current snapshot will not be altered
+unless the I<--current> flag is also given.
+
+If I<--no-metadata> is specified, then the snapshot data is created,
+but any metadata is immediately discarded (that is, libvirt does not
+treat the snapshot as current, and cannot revert to the snapshot
+unless I<--redefine> is later used to teach libvirt about the
+metadata again).
+
+Existence of snapshot metadata will prevent attempts to B<undefine>
+a persistent domain.  However, for transient domains, snapshot
+metadata is silently lost when the domain quits running (whether
+by command such as B<destroy> or by internal guest action).
+
+=item B<snapshot-create-as> I<domain> {[I<--print-xml>]
+| [I<--no-metadata>] [I<--halt>]} [I<name>] [I<description>]
+[I<--disk-only> [[I<--diskspec>] B<diskspec>]...
+
+Create a snapshot for domain I<domain> with the given <name> and
+<description>; if either value is omitted, libvirt will choose a
+value.  If I<--print-xml> is specified, then XML appropriate for
+I<snapshot-create> is output, rather than actually creating a snapshot.
+Otherwise, if I<--halt> is specified, the domain will be left in an
+inactive state after the snapshot is created, and if I<--disk-only>
+is specified, the snapshot will not include vm state.
+
+The I<--disk-only> flag is used to request a disk-only snapshot.  When
+this flag is in use, the command can also take additional I<diskspec>
+arguments to add <disk> elements to the xml.  Each <diskspec> is in the
+form B<disk[,snapshot=type][,driver=type][,file=name]>.  To include a
+literal comma in B<disk> or in B<file=name>, escape it with a second
+comma.  A literal I<--diskspec> must preceed each B<diskspec> unless
+all three of I<domain>, I<name>, and I<description> are also present.
+For example, a diskspec of "vda,snapshot=external,file=/path/to,,new"
+results in the following XML:
+  <disk name='vda' snapshot='external'>
+    <source file='/path/to,new'/>
+  </disk>
+
+If I<--no-metadata> is specified, then the snapshot data is created,
+but any metadata is immediately discarded (that is, libvirt does not
+treat the snapshot as current, and cannot revert to the snapshot
+unless B<snapshot-create> is later used to teach libvirt about the
+metadata again).  This flag is incompatible with I<--print-xml>.
+
+=item B<snapshot-current> I<domain> {[I<--name>] | [I<--security-info]
+| [I<snapshotname>]}
+
+Without I<snapshotname>, this will output the snapshot XML for the domain's
+current snapshot (if any).  If I<--name> is specified, just the
+current snapshot name instead of the full xml.  Otherwise, using
+I<--security-info> will also include security sensitive information in
+the XML.
+
+With I<snapshotname>, this is a request to make the existing named
+snapshot become the current snapshot, without reverting the domain.
+
+=item B<snapshot-edit> I<domain> I<snapshotname> [I<--current>]
+
+Edit the XML configuration file for I<snapshotname> of a domain.  If
+I<--current> is specified, also force the edited snapshot to become
+the current snapshot.
+
+This is equivalent to:
+
+ virsh snapshot-dumpxml dom name > snapshot.xml
+ vi snapshot.xml (or make changes with your other text editor)
+ virsh snapshot-create dom snapshot.xml --redefine [--current]
+
+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<snapshot-list> I<domain> [{I<--parent> | I<--roots>}] [I<--metadata>]
+
+List all of the available snapshots for the given domain.
+
+If I<--parent> is specified, add a column to the output table giving
+the name of the parent of each snapshot.
+
+If I<--roots> is specified, the list will be filtered to just snapshots
+that have no parents; this option is not compatible with I<--parent>.
+
+If I<--metadata> is specified, the list will be filtered to just
+snapshots that involve libvirt metadata, and thus would prevent
+B<undefine> of a persistent domain, or be lost on B<destroy> of
+a transient domain.
+
+=item B<snapshot-dumpxml> I<domain> I<snapshot> [I<--security-info>]
+
+Output the snapshot XML for the domain's snapshot named I<snapshot>.
+Using I<--security-info> will also include security sensitive information.
+
+=item B<snapshot-parent> I<domain> I<snapshot>
+
+Output the name of the parent snapshot for the given I<snapshot>, if any.
+
+=item B<snapshot-revert> I<domain> I<snapshot> [{I<--running> | I<--paused>}]
+
+Revert the given domain to the snapshot specified by I<snapshot>.  Be aware
+that this is a destructive action; any changes in the domain since the last
+snapshot was taken will be lost.  Also note that the state of the domain after
+snapshot-revert is complete will be the state of the domain at the time
+the original snapshot was taken.
+
+Normally, reverting to a snapshot leaves the domain in the state it was
+at the time the snapshot was created, except that a disk snapshot with
+no vm state leaves the domain in an inactive state.  Passing either the
+I<--running> or I<--paused> flag will perform additional state changes
+(such as booting an inactive domain, or pausing a running domain).  Since
+transient domains cannot be inactive, it is required to use one of these
+flags when reverting to a disk snapshot of a transient domain.
+
+=item B<snapshot-delete> I<domain> I<snapshot> [I<--metadata>]
+[{I<--children> | I<--children-only>}]
+
+Delete the snapshot for the domain named I<snapshot>.  If this snapshot
+has child snapshots, changes from this snapshot will be merged into the
+children.  If I<--children> is passed, then delete this snapshot and any
+children of this snapshot.  If I<--children-only> is passed, then delete
+any children of this snapshot, but leave this snapshot intact.  These
+two flags are mutually exclusive.
+
+If I<--metadata> is specified, then only delete the snapshot metadata
+maintained by libvirt, while leaving the snapshot contents intact for
+access by external tools; otherwise deleting a snapshot also removes
+the data contents from that point in time.

 =back

-- 
1.7.4.4

More information about the libvir-list mailing list