WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-changelog

[Xen-changelog] Further changes to xm.1 man page.

# HG changeset patch
# User emellor@xxxxxxxxxxxxxxxxxxxxxx
# Node ID 4f247dc79d0ae3ab31f84c6016650815fff0174c
# Parent  5ee1f7f3fc9bf635e4ca7f25c5d92fd2cb7e4e0b
Further changes to xm.1 man page.

Signed-off-by: Sean Dague <sean@xxxxxxxxx>

diff -r 5ee1f7f3fc9b -r 4f247dc79d0a docs/man/xm.pod.1
--- a/docs/man/xm.pod.1 Sat Nov 12 17:41:37 2005
+++ b/docs/man/xm.pod.1 Sat Nov 12 17:52:16 2005
@@ -36,6 +36,13 @@
 communications channels used to talk to the hypervisor.  Running as
 non root will return an error.
 
+Most B<xm> commands act asynchronously, so just because the B<xm>
+command returned, doesn't mean the action is complete.  This is
+important, as many operations on domains, like create and shutdown,
+can take considerable time (30 seconds or more) to bring the machine
+into a fully compliant state.  If you want to know when one of these
+actions has finished you must poll through xm list periodically.
+
 =head1 DOMAIN SUBCOMMANDS
 
 The following sub commands manipulate domains directly, as stated
@@ -86,19 +93,19 @@
 
 =over 4
 
-=item Config file in /etc/xen
-
-xm create Fedora4
+=item I<with config file>
+
+  xm create Fedora4
 
 This creates a domain with the file /etc/xen/Fedora4, and returns as
 soon as it is run.
 
-=item Creating a domain without ConfigFile
-
- xm create /dev/null ramdisk=initrd.img \
-    kernel=/boot/vmlinuz-2.6.12.6-xenU \
-    name=ramdisk nics=0 vcpus=1 \
-    memory=64 root=/dev/ram0
+=item I<without config file>
+ 
+  xm create /dev/null ramdisk=initrd.img \
+     kernel=/boot/vmlinuz-2.6.12.6-xenU \
+     name=ramdisk nics=0 vcpus=1 \
+     memory=64 root=/dev/ram0
 
 This creates the domain without using a config file (more specifically
 using /dev/null as an empty config file), kernel and ramdisk as
@@ -131,7 +138,8 @@
 
 =item I<list> [--long] [DomId, ...]
 
-Prints information about running domains.
+Prints information about one or more domains.  If no domains are
+specified it prints out information about all domains.
 
 An example format for the list is as follows:
 
@@ -148,44 +156,154 @@
 VCPUS allocated to domain.  State is the run state (see below).  Time
 is the total run time of the domain as accounted for by Xen.
 
+B<STATES>
+
+=over 4
+
 The State field lists 6 states for a Xen Domain, and which ones the
 current Domain is in.
 
+=item I<r - running>
+
+The domain is currently running on a CPU
+
+=item I<b - blocked>
+
+The domain is blocked, and not running or runable.  This can be caused
+because the domain is waiting on IO (a traditional wait state) or has
+gone to sleep because there was nothing else for it to do.
+
+=item I<p - paused>
+
+The domain has been paused, usually occurring through the administrator
+running B<xm pause>.  When in a paused state the domain will still
+consume allocated resources like memory, but will not be eligible for
+scheduling by the Xen hypervisor.
+
+=item I<s - shutdown>
+
+FIXME: Why would you ever see this state?
+
+=item I<c - crashed>
+
+The domain has crashed, which is always a violent ending.  Usually
+this state can only occur if the domain has been configured not to
+restart on crash.  See L<xmdomain.cfg> for more info.
+
+=item I<d - dying>
+
+The domain is in process of dying, but hasn't completely shutdown or
+crashed.
+
+FIXME: Is this right?
+
+=back
+
+B<LONG OUTPUT>
+
+=over 4
+
+If I<--long> is specified, the output for xm list is not the table
+view shown above, but instead is an S-Expression representing all
+information known about all domains asked for.  This is mostly only
+useful for external programs to parse the data.
+
+B<Note:> there is no stable guarantees on the format of this data.
+Use at your own risk.
+
+=back
+
+B<NOTES>
+
+=over 4
+
+The Time column is deceptive.  Virtual IO (network and block devices)
+used by Domains requires coordination by Domain0, which means that
+Domain0 is actually charged for much of the time that a DomainU is
+doing IO.  Use of this time value to determine relative utilizations
+by domains is thus very suspect, as a high IO workload may show as
+less utilized than a high CPU workload.  Consider yourself warned.
+
+=back
+
 =item I<mem-max> <DomId> <Mem>
 
-Set domain maximum memory limit to Mem. Mem is in Megabytes. This is the upper 
memory mark for how much memory a domain can have.
+Specify the maximum amount of memory the Domain is able to use.  Mem
+is specified in megabytes. 
+
+The mem-max value may not correspond to the actual memory used in the
+Domain, as it may balloon down it's memory to give more back to the OS.
 
 =item I<mem-set> <DomId> <Mem>
 
-Set domain's memory, in Megabytes. Mem must be less than or equal to the 
maximum memory for the domain.
+Set the domain's used memory using the balloon driver.  Because this
+operation requires cooperation from the domain operating system, there
+is no guarantee that it will succeed.
+
+B<Warning:> there is no good way to know in advance how small of a
+mem-set will make a domain unstable and cause it to crash.  Be very
+careful when using this command on running domains.
 
 =item I<migrate> <DomId> <Host> [Options]
 
-Migrate a domain to another Host machine. B<Xend> must be running on other 
host machine and there must be sufficient resources as well.
-
-=over 4
-
-Additional Options:
-
-    -l, --live                    Use live migration.
-    -r, --resource <Mbit value>   Set resource level.
+Migrate a domain to another Host machine. B<Xend> must be running on
+other host machine, it must be running the same version of xen, it
+must have the migration tcp port open and accepting connections from
+the source host, and there must be sufficient resources for the domain
+to run (memory, disk, etc).
+
+Migration is pretty complicated, and has many security implications,
+please read the Xen Users Guide to ensure you understand the
+ramifications and limitations on migration before attempting it in
+production.
+
+B<OPTIONS>
+
+=over 4
+
+=item I<-l, --live>
+
+Use live migration.  This will migrate the domain between hosts
+without shutting down the domain.  See the Xen Users Guide for more
+information.
+
+=item I<-r, --resource> Mbs
+
+Set maximum Mbs allowed for migrating the domain.  This ensures that
+the network link is not saturated with migration traffic while
+attempting to do other useful work.
 
 =back
 
 =item I<pause> <DomId>
 
-Pause a domain's execution.
+Pause a domain.  When in a paused state the domain will still consume
+allocated resources like memory, but will not be eligible for
+scheduling by the Xen hypervisor.
 
 =item I<reboot> [Options] <DomId>
 
-Reboot a domain.
-
-=over 4
-
-Additional Options:
-
-    -a, --all        reboot all domains.
-    -w, --wait       Wait for shutdown to complete.
+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
+executed the reboot action, which may be significantly before the
+domain actually reboots.
+
+The behavior of what happens to a domain when it reboots is set by the
+B<on_reboot> parameter of the xmdomain.cfg file when the domain was
+created.
+
+B<OPTIONS>
+
+=over 4
+
+=item I<-a, --all>
+
+Reboot all domains
+
+=item I<-w, --wait>
+
+Wait for reboot to complete before returning.  This may take a while,
+as all services in the domain will have to be shut down cleanly.
 
 =back
 

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog

<Prev in Thread] Current Thread [Next in Thread>
  • [Xen-changelog] Further changes to xm.1 man page., Xen patchbot -unstable <=