diff options
| -rw-r--r-- | docs/man/xm.pod.1 | 166 |
1 files changed, 140 insertions, 26 deletions
diff --git a/docs/man/xm.pod.1 b/docs/man/xm.pod.1 index 442c55f383..a49675eaaa 100644 --- a/docs/man/xm.pod.1 +++ b/docs/man/xm.pod.1 @@ -278,7 +278,7 @@ attempting to do other useful work. =item I<pause> <DomId> Pause a domain. When in a paused state the domain will still consume -allocated resources like memory, but will not be eligible for +allocated resources such as memory, but will not be eligible for scheduling by the Xen hypervisor. =item I<reboot> [Options] <DomId> @@ -309,46 +309,84 @@ as all services in the domain will have to be shut down cleanly. =item I<restore> <File> -Create a domain from saved state File. +Build a domain from an B<xm save> state file. See I<save> for more info. =item I<save> <DomId> <File> -Save domain state to File. Saves domain configuration to File as well. +Saves a running domain to a state file so that it can be restored +later. Once saved, the domain will no longer be running on the +system, thus the memory allocated for the domain will be free for +other domains to use. B<xm restore> restores from this state file. + +This is roughly equivalent to doing a hibernate on a running computer, +with all the same limitations. Open network connections may be +severed upon restore, as TCP timeouts may have expired. =item I<shutdown> [Options] <DomId> -Shutdown a domain. +Gracefully shuts down a domain. This coordinates with the domain OS +to perform graceful shutdown, so there is no guaruntee that it will +succeed, and may take a variable length of time depending on what +services must be shutdown in the domain. The command returns +immediately after signally the domain unless that I<-w> flag is used. + +The behavior of what happens to a domain when it reboots is set by the +B<on_shutdown> parameter of the xmdomain.cfg file when the domain was +created. + +B<OPTIONS> =over 4 -Additional Options: +=item I<-a> + +Shutdown B<all> domains. Often used when doing a complete shutdown of +a Xen system. - -a, --all Shutdown all domains. - -H, --halt Shutdown domain without reboot. - -R, --reboot Shutdown and reboot domain. - -w, --wait Wait for shutdown to complete. +=item I<-w> + +Wait for the domain to complete shutdown before returning. =back =item I<sysrq> <DomId> <letter> -Send a sysrq to a domain. +Send a I<Magic System Request> signal to the domain. For more +information on available magic sys req operations, see sysrq.txt in +your Linux Kernel sources. =item I<unpause> <DomId> -Unpause a paused domain. +Moves a domain out of the paused state. This will allow a previously +paused domain to now be eligible for scheduling by the Xen hypervisor. + +=item I<set-vcpus> <DomId> <VCPUCount> -=item I<set-vcpus> <DomId> <VCPUs> +Enables the I<VCPUcount> virtual CPUs for the domain in question. +Like mem-set, this command can only allocate up to the maximum virtual +CPU count configured at boot for the domain. -Enable a specific number of VCPUs for a domain. Subcommand only enables or disables already configured VCPUs for domain. +If the VCPUcount is smaller than the current number of active VCPUs, +the highest number VCPUs will be hotplug removed. This may be +important for pinning purposes. + +Attempting to set-vcpus to a number larger than the initially +configured VCPU count is an error. Trying to set-vcpus to < 1 will be +quietly ignored. =item I<vpcu-list> [DomID] -Lists VCPU information for a specific domain or all domains if DomID not given. +Lists VCPU information for a specific domain. If no domain is +specified, VCPU information for all domains will be provided. =item I<vcpu-pin> <DomId> <VCPU> <CPUs> -Sets VCPU to only run on specific CPUs. +Pins the the VCPU to only run on the specific CPUs. + +Normally VCPUs can float between available CPUs whenever Xen deems a +different run state is appropriate. Pinning can be used to restrict +this, by ensuring certain VCPUs can only run on certain physical +CPUs. =back @@ -358,37 +396,106 @@ Sets VCPU to only run on specific CPUs. =item I<dmesg> [OPTION] -Read or clear Xen's message buffer. The buffer contains Xen boot, warning, and error messages. +Reads the Xen message buffer, similar to dmesg on a Linux system. The +buffer contains informational, warning, and error messages created +during Xen's boot process. If you are having problems with Xen, this +is one of the first places to look as part of problem determination. + +B<OPTIONS> =over 4 -Additional Option: +=item I<-c, --clear> - -c, --clear Clears Xen's message buffer. +Clears Xen's message buffer. =back =item I<info> -Get information about Xen host. +Print information about the Xen host in I<name : value> format. When +reporting a Xen bug, please provide this information as part of the +bug report. + +Sample xen domain info looks as follows: + + system : Linux + host : talon + release : 2.6.12.6-xen0 + version : #1 Mon Nov 14 14:26:26 EST 2005 + machine : i686 + nr_cpus : 2 + nr_nodes : 1 + sockets_per_node : 2 + cores_per_socket : 1 + threads_per_core : 1 + cpu_mhz : 696 + hw_caps : 0383fbff:00000000:00000000:00000040 + memory : 767 + free_memory : 37 + xen_major : 3 + xen_minor : 0 + xen_extra : -devel + xen_caps : xen-3.0-x86_32 + xen_params : virt_start=0xfc000000 + xen_changeset : Mon Nov 14 18:13:38 2005 +0100 7793:090e44133d40 + cc_compiler : gcc version 3.4.3 (Mandrakelinux 10.2 3.4.3-7mdk) + cc_compile_by : sdague + cc_compile_domain : (none) + cc_compile_date : Mon Nov 14 14:16:48 EST 2005 + +B<FIELDS> + +=over 4 + +Not all fields will be explained here, but some of the less obvious +ones deserve explanation: + +=item I<hw_caps> + +A vector showing what hardware capabilities are supported by your +processor. This is equivalent to, though more cryptic, the flags +field in /proc/cpuinfo on a normal Linux machine. + +=item I<free_memory> + +Available memory (in MB) not allocated to Xen, or any other Domains. + +=item I<xen_caps> + +The xen version, architecture. Architecture values can be one of: +x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64. + +=item I<xen_changeset> + +The xen mercurial changeset id. Very useful for determining exactly +what version of code your Xen system was built from. + +=back =item I<log> -Print B<xend> log. +Print out the B<xend> log. This log file can be found in +/var/log/xend.log. =item I<top> -Monitor system and domains in real-time. +Executes the xentop command, which provides real time monitoring of +domains. Xentop is a curses interface, and reasonably self +explainitory. =back =head1 SCHEDULER SUBCOMMANDS +FIXME: we really need a scheduler expert to write up this section. + =over 4 =item I<sched-bvt> <Parameters> -Set Borrowed Virtual Time (BVT) scheduler parameters. There are five parameters, which are given in order below. +Set Borrowed Virtual Time (BVT) scheduler parameters. There are five +parameters, which are given in order below. =over 4 @@ -404,11 +511,13 @@ Parameters: =item I<sched-bvt-ctxallow> <Allow> -Sets the BVT scheduler's context switch allowance. Allow is the minimum time slice allowed to run before being pre-empted. +Sets the BVT scheduler's context switch allowance. Allow is the +minimum time slice allowed to run before being pre-empted. =item I<sched-sedf> <Parameters> -Set simple sEDF scheduler parameters. Use the following parametersin order. +Set simple sEDF scheduler parameters. Use the following parametersin +order. =over 4 @@ -426,15 +535,20 @@ Parameters: =head1 VIRTUAL DEVICE COMMANDS +Most virtual devices can be added and removed while guests are +running. The effect to the guest OS is much the same as any hotplug +event. + =over 4 =item I<block-attach <DomId> <BackDev> <FrontDev> <Mode> [BackDomId] -Create a new virtual block device. +Create a new virtual block device =item I<block-detach> <DomId> <DevId> -Destroy a domain's virtual block device. DevId may either be a device ID or the device name as mounted in the guest. +Destroy a domain's virtual block device. DevId may either be a device +ID or the device name as mounted in the guest. =item I<block-list> <DomId> |