[libvirt] [PATCH v2] virsh man page - domain-id consistency

Using 'domain' to represent domain name, domain id or uuid all over the man page, to be consistent with virsh help. --- diff to v1: I used domain-id instead of domain, per Eric's review comments. tools/virsh.pod | 145 +++++++++++++++++++++++++++---------------------------- 1 files changed, 72 insertions(+), 73 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 4bddf15..a5a2297 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -24,15 +24,14 @@ KVM, LXC, OpenVZ, VirtualBox and VMware ESX. The basic structure of most virsh usage is: - virsh [OPTION]... <command> <domain-id> [ARG]... + virsh [OPTION]... <command> <domain> [ARG]... -Where I<command> is one of the commands listed below, I<domain-id> -is the numeric domain id, or the domain name (which will be internally -translated to domain id), and I<ARGS> are command specific -options. There are a few exceptions to this rule in the cases where -the command in question acts on all domains, the entire machine, -or directly on the xen hypervisor. Those exceptions will be clear for -each of those commands. +Where I<command> is one of the commands listed below, I<domain> is the numeric +domain id, or the domain name, or the domain UUID and I<ARGS> are command +specific options. There are a few exceptions to this rule in the cases where +the command in question acts on all domains, the entire machine, or directly +on the xen hypervisor. Those exceptions will be clear for each of those +commands. The B<virsh> program can be used either to run one I<COMMAND> by giving the command and its arguments on the shell command line, or a I<COMMAND_STRING> @@ -302,7 +301,7 @@ description see: L<http://libvirt.org/formatcaps.html> The XML also show the NUMA topology information if available. -=item B<inject-nmi> I<domain-id> +=item B<inject-nmi> I<domain> Inject NMI to the guest. @@ -492,18 +491,18 @@ specified, then the output will be escaped for use in XML. =head1 DOMAIN COMMANDS The following commands manipulate domains directly, as stated -previously most commands take domain-id as the first parameter. The -I<domain-id> can be specified as a short integer, a name or a full UUID. +previously most commands take domain as the first parameter. The +I<domain> can be specified as a short integer, a name or a full UUID. =over 4 -=item B<autostart> [I<--disable>] I<domain-id> +=item B<autostart> [I<--disable>] I<domain> Configure a domain to be automatically started at boot. The option I<--disable> disables autostarting. -=item B<console> I<domain-id> [I<devname>] [I<--safe>] [I<--force>] +=item B<console> I<domain> [I<devname>] [I<--safe>] [I<--force>] Connect the virtual serial console for the guest. The optional I<devname> parameter refers to the device alias of an alternate @@ -529,7 +528,7 @@ exits. B<Example> - virsh dumpxml <domain-id> > domain.xml + virsh dumpxml <domain> > domain.xml vi domain.xml (or make changes with your other text editor) virsh create < domain.xml @@ -539,7 +538,7 @@ Define a domain from an XML <file>. The domain definition is registered but not started. If domain is already running, the changes will take effect on the next boot. -=item B<desc> I<domain-id> [[I<--live>] [I<--config>] | +=item B<desc> I<domain> [[I<--live>] [I<--config>] | [I<--current>]] [I<--title>] [I<--edit>] [I<--new-desc> New description or title message] @@ -562,16 +561,16 @@ Flag I<--title> selects operation on the title field instead of description. If neither of I<--edit> and I<--new-desc> are specified the note or description is displayed instead of being modified. -=item B<destroy> I<domain-id> [I<--graceful>] +=item B<destroy> I<domain> [I<--graceful>] -Immediately terminate the domain domain-id. This doesn't give the domain +Immediately terminate the domain I<domain>. This doesn't give the domain OS any chance to react, and it's the equivalent of ripping the power cord out on a physical machine. In most cases you will want to use the B<shutdown> command instead. However, this does not delete any storage volumes used by the guest, and if the domain is persistent, it can be restarted later. -If I<domain-id> is transient, then the metadata of any snapshots will +If I<domain> is transient, then the metadata of any snapshots will be lost once the guest stops running, but the snapshot contents still exist, and a new domain with the same name and UUID can restore the snapshot metadata with B<snapshot-create>. @@ -650,7 +649,7 @@ on hypervisor. Get memory stats for a running domain. -=item B<domblkerror> I<domain-id> +=item B<domblkerror> I<domain> Show errors on block devices. This command usually comes handy when B<domstate> command says that a domain was paused due to I/O error. @@ -820,13 +819,13 @@ I<size> is a scaled integer (see B<NOTES> above) which defaults to KiB "B" to get bytes (note that for historical reasons, this differs from B<vol-resize> which defaults to bytes without a suffix). -=item B<domdisplay> I<domain-id> [I<--include-password>] +=item B<domdisplay> I<domain> [I<--include-password>] Output a URI which can be used to connect to the graphical display of the domain via VNC, SPICE or RDP. If I<--include-password> is specified, the SPICE channel password will be included in the URI. -=item B<dominfo> I<domain-id> +=item B<dominfo> I<domain> Returns basic information about the domain. @@ -838,11 +837,11 @@ Convert a domain name or id to domain UUID Convert a domain name (or UUID) to a domain id -=item B<domjobabort> I<domain-id-or-uuid> +=item B<domjobabort> I<domain> Abort the currently running domain job. -=item B<domjobinfo> I<domain-id-or-uuid> +=item B<domjobinfo> I<domain> Returns information about jobs running on a domain. @@ -850,12 +849,12 @@ Returns information about jobs running on a domain. Convert a domain Id (or UUID) to domain name -=item B<domstate> I<domain-id> [I<--reason>] +=item B<domstate> I<domain> [I<--reason>] Returns state about a domain. I<--reason> tells virsh to also print reason for the state. -=item B<domcontrol> I<domain-id> +=item B<domcontrol> I<domain> Returns state of an interface to VMM used to control a domain. For states other than "ok" or "error" the command also prints number of @@ -875,7 +874,7 @@ configuration format named by I<format>. For QEMU/KVM hypervisor, the I<format> argument must be B<qemu-argv>. For Xen hypervisor, the I<format> argument may be B<xen-xm> or B<xen-sxpr>. -=item B<dump> I<domain-id> I<corefilepath> [I<--bypass-cache>] +=item B<dump> I<domain> I<corefilepath> [I<--bypass-cache>] { [I<--live>] | [I<--crash>] | [I<--reset>] } [I<--verbose>] [I<--memory-only>] Dumps the core of a domain to a file for analysis. @@ -899,7 +898,7 @@ B<dump> command. I<--verbose> displays the progress of dump. NOTE: Some hypervisors may require the user to manually ensure proper permissions on file and path specified by argument I<corefilepath>. -=item B<dumpxml> I<domain-id> [I<--inactive>] [I<--security-info>] +=item B<dumpxml> I<domain> [I<--inactive>] [I<--security-info>] [I<--update-cpu>] Output the domain information as an XML dump to stdout, this format can be used @@ -910,7 +909,7 @@ Using I<--security-info> will also include security sensitive information in the XML dump. I<--update-cpu> updates domain CPU requirements according to host CPU. -=item B<edit> I<domain-id> +=item B<edit> I<domain> Edit the XML configuration file for a domain, which will affect the next boot of the guest. @@ -926,7 +925,7 @@ 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<managedsave> I<domain-id> [I<--bypass-cache>] +=item B<managedsave> I<domain> [I<--bypass-cache>] [{I<--running> | I<--paused>}] [I<--verbose>] Save and destroy (stop) a running domain, so it can be restarted from the same @@ -948,7 +947,7 @@ state the B<start> should use. The B<dominfo> command can be used to query whether a domain currently has any managed save image. -=item B<managedsave-remove> I<domain-id> +=item B<managedsave-remove> I<domain> Remove the B<managedsave> state file for a domain, if it exists. This ensures the domain will do a full boot the next time it is started. @@ -970,7 +969,7 @@ stats. =item B<migrate> [I<--live>] [I<--direct>] [I<--p2p> [I<--tunnelled>]] [I<--persistent>] [I<--undefinesource>] [I<--suspend>] [I<--copy-storage-all>] [I<--copy-storage-inc>] [I<--change-protection>] [I<--unsafe>] [I<--verbose>] -I<domain-id> I<desturi> [I<migrateuri>] [I<dname>] +I<domain> I<desturi> [I<migrateuri>] [I<dname>] [I<--timeout> B<seconds>] [I<--xml> B<file>] Migrate domain to another host. Add I<--live> for live migration; I<--p2p> @@ -1030,18 +1029,18 @@ seen from the source machine. =back -=item B<migrate-setmaxdowntime> I<domain-id> I<downtime> +=item B<migrate-setmaxdowntime> I<domain> I<downtime> Set maximum tolerable downtime for a domain which is being live-migrated to another host. The I<downtime> is a number of milliseconds the guest is allowed to be down at the end of live migration. -=item B<migrate-setspeed> I<domain-id> I<bandwidth> +=item B<migrate-setspeed> I<domain> I<bandwidth> Set the maximum migration bandwidth (in Mbps) for a domain which is being migrated to another host. -=item B<migrate-getspeed> I<domain-id> +=item B<migrate-getspeed> I<domain> Get the maximum migration bandwidth (in Mbps) for a domain. @@ -1064,7 +1063,7 @@ If I<--live> is specified, set scheduler information of a running guest. If I<--config> is specified, affect the next boot of a persistent guest. If I<--current> is specified, affect the current guest state. -=item B<reboot> I<domain-id> [I<--mode acpi|agent>] +=item B<reboot> I<domain> [I<--mode acpi|agent>] Reboot a domain. This acts just as if the domain had the B<reboot> command run from the console. The command returns as soon as it has @@ -1078,7 +1077,7 @@ By default the hypervisor will try to pick a suitable shutdown method. To specify an alternative method, the I<--mode> parameter can specify C<acpi> or C<agent>. -=item B<reset> I<domain-id> +=item B<reset> I<domain> Reset a domain immediately without any guest shutdown. B<reset> emulates the power reset button on a machine, where all guest @@ -1110,7 +1109,7 @@ should not reuse the saved state file for a second B<restore> unless you have also reverted all storage volumes back to the same contents as when the state file was created. -=item B<save> I<domain-id> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>] +=item B<save> I<domain> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>] [{I<--running> | I<--paused>}] [I<--verbose>] Saves a running domain (RAM, but not disk state) to a state file so that @@ -1187,11 +1186,11 @@ 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<schedinfo> [I<--set> B<parameter=value>] I<domain-id> [[I<--config>] +=item B<schedinfo> [I<--set> B<parameter=value>] I<domain> [[I<--config>] [I<--live>] | [I<--current>]] =item B<schedinfo> [I<--weight> B<number>] [I<--cap> B<number>] -I<domain-id> +I<domain> Allows you to show (and set) the domain scheduler parameters. The parameters available for each hypervisor are: @@ -1221,7 +1220,7 @@ B<Note>: The vcpu_period parameter has a valid value range of 1000-1000000 or 1000-18446744073709551 or less than 0. The value 0 for either parameter is the same as not specifying that parameter. -=item B<screenshot> I<domain-id> [I<imagefilepath>] [I<--screen> B<screenID>] +=item B<screenshot> I<domain> [I<imagefilepath>] [I<--screen> B<screenID>] Takes a screenshot of a current domain console and stores it into a file. Optionally, if hypervisor supports more displays for a domain, I<screenID> @@ -1230,10 +1229,10 @@ of screen. In case of multiple graphics cards, heads are enumerated before devices, e.g. having two graphics cards, both with four heads, screen ID 5 addresses the second head on the second card. -=item B<send-key> I<domain-id> [I<--codeset> B<codeset>] +=item B<send-key> I<domain> [I<--codeset> B<codeset>] [I<--holdtime> B<holdtime>] I<keycode>... -Parse the I<keycode> sequence as keystrokes to send to I<domain-id>. +Parse the I<keycode> sequence as keystrokes to send to I<domain>. Each I<keycode> can either be a numeric value or a symbolic name from the corresponding codeset. If I<--holdtime> is given, each keystroke will be held for that many milliseconds. The default codeset is @@ -1311,7 +1310,7 @@ B<Examples> # send a tab, held for 1 second virsh send-key --holdtime 1000 0xf -=item B<setmem> I<domain-id> B<size> [[I<--config>] [I<--live>] | +=item B<setmem> I<domain> B<size> [[I<--config>] [I<--live>] | [I<--current>]] Change the memory allocation for a guest domain. @@ -1332,7 +1331,7 @@ For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver. -=item B<setmaxmem> I<domain-id> B<size> [[I<--config>] [I<--live>] | +=item B<setmaxmem> I<domain> B<size> [[I<--config>] [I<--live>] | [I<--current>]] Change the maximum memory allocation limit for a guest domain. @@ -1352,7 +1351,7 @@ up to the nearest kibibyte. Some hypervisors require a larger granularity than KiB, and requests that are not an even multiple will be rounded up. For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). -=item B<memtune> I<domain-id> [I<--hard-limit> B<size>] +=item B<memtune> I<domain> [I<--hard-limit> B<size>] [I<--soft-limit> B<size>] [I<--swap-hard-limit> B<size>] [I<--min-guarantee> B<size>] [[I<--config>] [I<--live>] | [I<--current>]] @@ -1399,7 +1398,7 @@ The guaranteed minimum memory allocation for the guest. Specifying -1 as a value for these limits is interpreted as unlimited. -=item B<blkiotune> I<domain-id> [I<--weight> B<weight>] +=item B<blkiotune> I<domain> [I<--weight> B<weight>] [I<--device-weights> B<device-weights>] [[I<--config>] [I<--live>] | [I<--current>]] @@ -1420,7 +1419,7 @@ Both I<--live> and I<--config> flags may be given, but I<--current> is exclusive. If no flag is specified, behavior is different depending on hypervisor. -=item B<setvcpus> I<domain-id> I<count> [I<--maximum>] [[I<--config>] +=item B<setvcpus> I<domain> I<count> [I<--maximum>] [[I<--config>] [I<--live>] | [I<--current>]] Change the number of virtual CPUs active in a guest domain. By default, @@ -1451,7 +1450,7 @@ The I<--maximum> flag controls the maximum number of virtual cpus that can be hot-plugged the next time the domain is booted. As such, it must only be used with the I<--config> flag, and not with the I<--live> flag. -=item B<shutdown> I<domain-id> [I<--mode acpi|agent>] +=item B<shutdown> I<domain> [I<--mode acpi|agent>] Gracefully shuts down a domain. This coordinates with the domain OS to perform graceful shutdown, so there is no guarantee that it will @@ -1461,7 +1460,7 @@ services must be shutdown in the domain. The exact behavior of a domain when it shuts down is set by the I<on_shutdown> parameter in the domain's XML definition. -If I<domain-id> is transient, then the metadata of any snapshots will +If I<domain> is transient, then the metadata of any snapshots will be lost once the guest stops running, but the snapshot contents still exist, and a new domain with the same name and UUID can restore the snapshot metadata with B<snapshot-create>. @@ -1470,8 +1469,8 @@ By default the hypervisor will try to pick a suitable shutdown method. To specify an alternative method, the I<--mode> parameter can specify C<acpi> or C<agent>. -=item B<start> I<domain-name> [I<--console>] [I<--paused>] [I<--autodestroy>] -[I<--bypass-cache>] [I<--force-boot>] +=item B<start> I<domain-name-or-uuid> [I<--console>] [I<--paused>] +[I<--autodestroy>] [I<--bypass-cache>] [I<--force-boot>] Start a (previously defined) inactive domain, either from the last B<managedsave> state, or via a fresh boot if no managedsave state is @@ -1485,18 +1484,18 @@ the restore will avoid the file system cache, although this may slow down the operation. If I<--force-boot> is specified, then any managedsave state is discarded and a fresh boot occurs. -=item B<suspend> I<domain-id> +=item B<suspend> I<domain> Suspend a running domain. It is kept in memory but won't be scheduled anymore. -=item B<resume> I<domain-id> +=item B<resume> I<domain> Moves a domain out of the suspended state. This will allow a previously suspended domain to now be eligible for scheduling by the underlying hypervisor. -=item B<dompmsuspend> I<domain-id> I<target> [I<--duration>] +=item B<dompmsuspend> I<domain> I<target> [I<--duration>] Suspend a running domain into one of these states (possible I<target> values): @@ -1512,18 +1511,18 @@ hypervisor driver and 0 should be used.). Note that this command requires a guest agent configured and running in the domain's guest OS. -=item B<dompmwakeup> I<domain-id> +=item B<dompmwakeup> I<domain> Wakeup a domain suspended by dompmsuspend command. Injects a wakeup into the guest that previously used dompmsuspend, rather than waiting for the previously requested duration (if any) to elapse. -=item B<ttyconsole> I<domain-id> +=item B<ttyconsole> I<domain> Output the device used for the TTY console of the domain. If the information is not available the processes will provide an exit code of 1. -=item B<undefine> I<domain-id> [I<--managed-save>] [I<--snapshots-metadata>] +=item B<undefine> I<domain> [I<--managed-save>] [I<--snapshots-metadata>] [ {I<--storage> B<volumes> | I<--remove-all-storage>} I<--wipe-storage>] Undefine a domain. If the domain is running, this converts it to a @@ -1558,13 +1557,13 @@ The flag I<--wipe-storage> specifies that the storage volumes should be wiped before removal. NOTE: For an inactive domain, the domain name or UUID must be used as the -I<domain-id>. +I<domain>. -=item B<vcpucount> I<domain-id> [{I<--maximum> | I<--active>} +=item B<vcpucount> I<domain> [{I<--maximum> | I<--active>} {I<--config> | I<--live> | I<--current>}] Print information about the virtual cpu counts of the given -I<domain-id>. If no flags are specified, all possible counts are +I<domain>. If no flags are specified, all possible counts are listed in a table; otherwise, the output is limited to just the numeric value requested. For historical reasons, the table lists the label "current" on the rows that can be queried in isolation @@ -1580,12 +1579,12 @@ state of the domain (corresponding to I<--live> if running, or I<--config> if inactive); these three flags are mutually exclusive. Thus, this command always takes exactly zero or two flags. -=item B<vcpuinfo> I<domain-id> +=item B<vcpuinfo> I<domain> Returns basic information about the domain virtual CPUs, like the number of vCPUs, the running time, the affinity to physical processors. -=item B<vcpupin> I<domain-id> [I<vcpu>] [I<cpulist>] [[I<--live>] +=item B<vcpupin> I<domain> [I<vcpu>] [I<cpulist>] [[I<--live>] [I<--config>] | [I<--current>]] Query or change the pinning of domain VCPUs to host physical CPUs. To @@ -1607,7 +1606,7 @@ If no flag is specified, behavior is different depending on hypervisor. B<Note>: The expression is sequentially evaluated, so "0-15,^8" is identical to "9-14,0-7,15" but not identical to "^8,0-15". -=item B<vncdisplay> I<domain-id> +=item B<vncdisplay> I<domain> Output the IP address and port number for the VNC display. If the information is not available the processes will provide an exit code of 1. @@ -1617,14 +1616,14 @@ is not available the processes will provide an exit code of 1. =head1 DEVICE COMMANDS The following commands manipulate devices associated to domains. -The domain-id can be specified as a short integer, a name or a full UUID. +The I<domain> 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<attach-device> I<domain-id> I<FILE> [I<--config>] +=item B<attach-device> I<domain> I<FILE> [I<--config>] Attach a device to the domain, using a device definition in an XML file using a device definition element such as <disk> or <interface> @@ -1639,7 +1638,7 @@ within an existing device; consider using B<update-device> for this usage. For passthrough host devices, see also B<nodedev-detach>, needed if the device does not use managed mode. -=item B<attach-disk> I<domain-id> I<source> I<target> +=item B<attach-disk> I<domain> I<source> I<target> [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>] [I<--type type>] [I<--mode mode>] [I<--config>] [I<--sourcetype soucetype>] [I<--serial serial>] [I<--shareable>] [I<--rawio>] [I<--address address>] @@ -1667,7 +1666,7 @@ scsi:controller.bus.unit or ide:controller.bus.unit. I<multifunction> indicates specified pci address is a multifunction pci device address. -=item B<attach-interface> I<domain-id> I<type> I<source> +=item B<attach-interface> I<domain> I<type> I<source> [I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>] [I<--config>] [I<--inbound average,peak,burst>] [I<--outbound average,peak,burst>] @@ -1691,7 +1690,7 @@ B<Note>: the optional target value is the name of a device to be created as the back-end on the node. If not provided a device named "vnetN" or "vifN" will be created automatically. -=item B<detach-device> I<domain-id> I<FILE> [I<--config>] +=item B<detach-device> I<domain> I<FILE> [I<--config>] Detach a device from the domain, takes the same kind of XML descriptions as command B<attach-device>. @@ -1701,7 +1700,7 @@ I<--config>. For passthrough host devices, see also B<nodedev-reattach>, needed if the device does not use managed mode. -=item B<detach-disk> I<domain-id> I<target> [I<--config>] +=item B<detach-disk> I<domain> I<target> [I<--config>] Detach a disk device from a domain. The I<target> is the device as seen from the domain. @@ -1709,7 +1708,7 @@ If I<--config> is specified, alter persistent configuration, effect observed on next boot, for compatibility purposes, I<--persistent> is alias of I<--config>. -=item B<detach-interface> I<domain-id> I<type> [I<--mac mac>] [I<--config>] +=item B<detach-interface> I<domain> I<type> [I<--mac mac>] [I<--config>] Detach a network interface from a domain. I<type> can be either I<network> to indicate a physical network device or @@ -1720,9 +1719,9 @@ If I<--config> is specified, alter persistent configuration, effect observed on next boot, for compatibility purposes, I<--persistent> is alias of I<--config>. -=item B<update-device> I<domain-id> I<file> [I<--config>] [I<--force>] +=item B<update-device> I<domain> I<file> [I<--config>] [I<--force>] -Update the characteristics of a device associated with I<domain-id>, +Update the characteristics of a device associated with I<domain>, based on the device definition in an XML I<file>. If the I<--config> option is used, the changes will take affect the next time libvirt starts the domain. For compatibility purposes, I<--persistent> is @@ -1732,7 +1731,7 @@ the domain. See the documentation at L<http://libvirt.org/formatdomain.html#elementsDevices> to learn about libvirt XML format for a device. -=item B<change-media> I<domain-id> I<path> [I<--eject>] [I<--insert>] +=item B<change-media> I<domain> I<path> [I<--eject>] [I<--insert>] [I<--update>] [I<source>] [I<--force>] [[I<--live>] [I<--config>] | [I<--current>]] Change media of CDROM or floppy drive. I<path> can be the fully-qualified path -- 1.7.8.6