From aa03b1471c334836e87f814a32d9fec914eeed94 Mon Sep 17 00:00:00 2001 From: Jan Tomko Date: Wed, 25 Jul 2012 13:17:03 +0200 Subject: [PATCH] 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. --- tools/virsh.pod | 147 ++++++++++++++++++++++++------------------------ 1 file changed, 73 insertions(+), 74 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 6ecf6ce112..fa98e35463 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]... [ARG]... + virsh [OPTION]... [ARG]... -Where I is one of the commands listed below, I -is the numeric domain id, or the domain name (which will be internally -translated to domain id), and I 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 is one of the commands listed below, I is the numeric +domain id, or the domain name, or the domain UUID and I 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 program can be used either to run one I by giving the command and its arguments on the shell command line, or a I @@ -302,7 +301,7 @@ description see: L The XML also show the NUMA topology information if available. -=item B I +=item B I 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 can be specified as a short integer, a name or a full UUID. +previously most commands take domain as the first parameter. The +I can be specified as a short integer, a name or a full UUID. =over 4 -=item B [I<--disable>] I +=item B [I<--disable>] I Configure a domain to be automatically started at boot. The option I<--disable> disables autostarting. -=item B I [I] [I<--safe>] [I<--force>] +=item B I [I] [I<--safe>] [I<--force>] Connect the virtual serial console for the guest. The optional I parameter refers to the device alias of an alternate @@ -529,7 +528,7 @@ exits. B - virsh dumpxml > domain.xml + virsh dumpxml > 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 . The domain definition is registered but not started. If domain is already running, the changes will take effect on the next boot. -=item B I [[I<--live>] [I<--config>] | +=item B I [[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 I [I<--graceful>] +=item B I [I<--graceful>] -Immediately terminate the domain domain-id. This doesn't give the domain +Immediately terminate the domain I. 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 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 is transient, then the metadata of any snapshots will +If I 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. @@ -650,7 +649,7 @@ on hypervisor. Get memory stats for a running domain. -=item B I +=item B I Show errors on block devices. This command usually comes handy when B command says that a domain was paused due to I/O error. @@ -820,17 +819,17 @@ I is a scaled integer (see B above) which defaults to KiB "B" to get bytes (note that for historical reasons, this differs from B which defaults to bytes without a suffix). -=item B I [I<--include-password>] +=item B I [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 I +=item B I Returns the hostname of a domain, if the hypervisor makes it available. -=item B I +=item B I Returns basic information about the domain. @@ -842,11 +841,11 @@ Convert a domain name or id to domain UUID Convert a domain name (or UUID) to a domain id -=item B I +=item B I Abort the currently running domain job. -=item B I +=item B I Returns information about jobs running on a domain. @@ -854,12 +853,12 @@ Returns information about jobs running on a domain. Convert a domain Id (or UUID) to domain name -=item B I [I<--reason>] +=item B I [I<--reason>] Returns state about a domain. I<--reason> tells virsh to also print reason for the state. -=item B I +=item B I 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 @@ -879,7 +878,7 @@ configuration format named by I. For QEMU/KVM hypervisor, the I argument must be B. For Xen hypervisor, the I argument may be B or B. -=item B I I [I<--bypass-cache>] +=item B I I [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. @@ -903,7 +902,7 @@ B 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. -=item B I [I<--inactive>] [I<--security-info>] +=item B I [I<--inactive>] [I<--security-info>] [I<--update-cpu>] Output the domain information as an XML dump to stdout, this format can be used @@ -914,7 +913,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 I +=item B I Edit the XML configuration file for a domain, which will affect the next boot of the guest. @@ -930,7 +929,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. -=item B I [I<--bypass-cache>] +=item B I [I<--bypass-cache>] [{I<--running> | I<--paused>}] [I<--verbose>] Save and destroy (stop) a running domain, so it can be restarted from the same @@ -952,7 +951,7 @@ state the B should use. The B command can be used to query whether a domain currently has any managed save image. -=item B I +=item B I Remove the B state file for a domain, if it exists. This ensures the domain will do a full boot the next time it is started. @@ -974,7 +973,7 @@ stats. =item B [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 I [I] [I] +I I [I] [I] [I<--timeout> B] [I<--xml> B] Migrate domain to another host. Add I<--live> for live migration; I<--p2p> @@ -1034,18 +1033,18 @@ seen from the source machine. =back -=item B I I +=item B I I Set maximum tolerable downtime for a domain which is being live-migrated to another host. The I is a number of milliseconds the guest is allowed to be down at the end of live migration. -=item B I I +=item B I I Set the maximum migration bandwidth (in Mbps) for a domain which is being migrated to another host. -=item B I +=item B I Get the maximum migration bandwidth (in Mbps) for a domain. @@ -1068,7 +1067,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 I [I<--mode acpi|agent>] +=item B I [I<--mode acpi|agent>] Reboot a domain. This acts just as if the domain had the B command run from the console. The command returns as soon as it has @@ -1082,7 +1081,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 or C. -=item B I +=item B I Reset a domain immediately without any guest shutdown. B emulates the power reset button on a machine, where all guest @@ -1114,7 +1113,7 @@ should not reuse the saved state file for a second B unless you have also reverted all storage volumes back to the same contents as when the state file was created. -=item B I I [I<--bypass-cache>] [I<--xml> B] +=item B I I [I<--bypass-cache>] [I<--xml> B] [{I<--running> | I<--paused>}] [I<--verbose>] Saves a running domain (RAM, but not disk state) to a state file so that @@ -1191,11 +1190,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. -=item B [I<--set> B] I [[I<--config>] +=item B [I<--set> B] I [[I<--config>] [I<--live>] | [I<--current>]] =item B [I<--weight> B] [I<--cap> B] -I +I Allows you to show (and set) the domain scheduler parameters. The parameters available for each hypervisor are: @@ -1225,7 +1224,7 @@ B: 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 I [I] [I<--screen> B] +=item B I [I] [I<--screen> B] Takes a screenshot of a current domain console and stores it into a file. Optionally, if hypervisor supports more displays for a domain, I @@ -1234,10 +1233,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 I [I<--codeset> B] +=item B I [I<--codeset> B] [I<--holdtime> B] I... -Parse the I sequence as keystrokes to send to I. +Parse the I sequence as keystrokes to send to I. Each I 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 @@ -1315,7 +1314,7 @@ B # send a tab, held for 1 second virsh send-key --holdtime 1000 0xf -=item B I B [[I<--config>] [I<--live>] | +=item B I B [[I<--config>] [I<--live>] | [I<--current>]] Change the memory allocation for a guest domain. @@ -1336,7 +1335,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 I B [[I<--config>] [I<--live>] | +=item B I B [[I<--config>] [I<--live>] | [I<--current>]] Change the maximum memory allocation limit for a guest domain. @@ -1356,7 +1355,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 I [I<--hard-limit> B] +=item B I [I<--hard-limit> B] [I<--soft-limit> B] [I<--swap-hard-limit> B] [I<--min-guarantee> B] [[I<--config>] [I<--live>] | [I<--current>]] @@ -1406,7 +1405,7 @@ The guaranteed minimum memory allocation for the guest. Specifying -1 as a value for these limits is interpreted as unlimited. -=item B I [I<--weight> B] +=item B I [I<--weight> B] [I<--device-weights> B] [[I<--config>] [I<--live>] | [I<--current>]] @@ -1427,7 +1426,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 I I [I<--maximum>] [[I<--config>] +=item B I I [I<--maximum>] [[I<--config>] [I<--live>] | [I<--current>]] Change the number of virtual CPUs active in a guest domain. By default, @@ -1458,7 +1457,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 I [I<--mode acpi|agent>] +=item B I [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 @@ -1468,7 +1467,7 @@ services must be shutdown in the domain. The exact behavior of a domain when it shuts down is set by the I parameter in the domain's XML definition. -If I is transient, then the metadata of any snapshots will +If I 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. @@ -1477,8 +1476,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 or C. -=item B I [I<--console>] [I<--paused>] [I<--autodestroy>] -[I<--bypass-cache>] [I<--force-boot>] +=item B I [I<--console>] [I<--paused>] +[I<--autodestroy>] [I<--bypass-cache>] [I<--force-boot>] Start a (previously defined) inactive domain, either from the last B state, or via a fresh boot if no managedsave state is @@ -1492,18 +1491,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 I +=item B I Suspend a running domain. It is kept in memory but won't be scheduled anymore. -=item B I +=item B I 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 I I [I<--duration>] +=item B I I [I<--duration>] Suspend a running domain into one of these states (possible I values): @@ -1519,18 +1518,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 I +=item B I 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 I +=item B I 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 I [I<--managed-save>] [I<--snapshots-metadata>] +=item B I [I<--managed-save>] [I<--snapshots-metadata>] [ {I<--storage> B | I<--remove-all-storage>} I<--wipe-storage>] Undefine a domain. If the domain is running, this converts it to a @@ -1565,13 +1564,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. +I. -=item B I [{I<--maximum> | I<--active>} +=item B I [{I<--maximum> | I<--active>} {I<--config> | I<--live> | I<--current>}] Print information about the virtual cpu counts of the given -I. If no flags are specified, all possible counts are +I. 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 @@ -1587,12 +1586,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 I +=item B I Returns basic information about the domain virtual CPUs, like the number of vCPUs, the running time, the affinity to physical processors. -=item B I [I] [I] [[I<--live>] +=item B I [I] [I] [[I<--live>] [I<--config>] | [I<--current>]] Query or change the pinning of domain VCPUs to host physical CPUs. To @@ -1614,7 +1613,7 @@ If no flag is specified, behavior is different depending on hypervisor. B: 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 I +=item B I 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. @@ -1624,14 +1623,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 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 on the format of the device sections to get the most accurate set of accepted values. =over 4 -=item B I I [I<--config>] +=item B I I [I<--config>] Attach a device to the domain, using a device definition in an XML file using a device definition element such as or @@ -1646,7 +1645,7 @@ within an existing device; consider using B for this usage. For passthrough host devices, see also B, needed if the device does not use managed mode. -=item B I I I +=item B I I I [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>] @@ -1674,7 +1673,7 @@ scsi:controller.bus.unit or ide:controller.bus.unit. I indicates specified pci address is a multifunction pci device address. -=item B I I I +=item B I I I [I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>] [I<--config>] [I<--inbound average,peak,burst>] [I<--outbound average,peak,burst>] @@ -1698,7 +1697,7 @@ B: 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 I I [I<--config>] +=item B I I [I<--config>] Detach a device from the domain, takes the same kind of XML descriptions as command B. @@ -1708,7 +1707,7 @@ I<--config>. For passthrough host devices, see also B, needed if the device does not use managed mode. -=item B I I [I<--config>] +=item B I I [I<--config>] Detach a disk device from a domain. The I is the device as seen from the domain. @@ -1716,7 +1715,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 I I [I<--mac mac>] [I<--config>] +=item B I I [I<--mac mac>] [I<--config>] Detach a network interface from a domain. I can be either I to indicate a physical network device or @@ -1727,9 +1726,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 I I [I<--config>] [I<--force>] +=item B I I [I<--config>] [I<--force>] -Update the characteristics of a device associated with I, +Update the characteristics of a device associated with I, based on the device definition in an XML I. 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 @@ -1739,7 +1738,7 @@ the domain. See the documentation at L to learn about libvirt XML format for a device. -=item B I I [I<--eject>] [I<--insert>] +=item B I I [I<--eject>] [I<--insert>] [I<--update>] [I] [I<--force>] [[I<--live>] [I<--config>] | [I<--current>]] Change media of CDROM or floppy drive. I can be the fully-qualified path -- GitLab