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

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