xm docs: Added new,delete,dump-core,resume,suspend,uptime and fixed others

Signed-off-by: Bill Rieske <brieske@novell.com>

1 files changed, 268 insertions, 38 deletions

diff --git a/docs/man/xm.pod.1 b/docs/man/xm.pod.1
index 74b58dbf14..ad36fce6ab 100644
--- a/docs/man/xm.pod.1
+++ b/docs/man/xm.pod.1
@@ -67,13 +67,12 @@ The attached console will perform much like a standard serial console,
 so running curses based interfaces over the console B<is not
 advised>.  Vi tends to get very odd when using it over this interface.
 
-=item B<create> [B<-c>] I<configfile> [I<name>=I<value>]..
+=item B<create> I<configfile> [I<OPTIONS>] [I<vars>]..
 
-The create sub command requires a config file and can optionally take a
-series of name value pairs that add to or override variables defined
+The create subcommand requires a config file and can optionally take a
+series of I<vars> that add to or override variables defined
 in the config file.  See L<xmdomain.cfg> for full details of that file
-format, and possible options used in either the configfile or
-I<name>=I<value> combinations.
+format, and possible options used in either the configfile or for I<vars>.
 
 I<configfile> can either be an absolute path to a file, or a relative
 path to a file located in /etc/xen.
@@ -86,9 +85,65 @@ B<OPTIONS>
 
 =over 4 
 
-=item B<-c>
+=item B<--help_config>
 
-Attache console to the domain as soon as it has started.  This is
+Print the available configuration variables I<vars>.  These variables may be
+used on the command line or in the configuration file I<configfile>.
+
+=item B<-q>, B<--quiet>
+
+No console output.
+
+=item B<--path>
+
+Search path for configuration scripts. The value of PATH is a 
+colon-separated directory list.
+
+=item B<-f=FILE>, B<--defconfig=FILE>
+
+Use the given Python configuration script. The configuration 
+script is loaded after arguments have been processed. Each 
+command-line option sets a configuration variable named after 
+its long option name, and these variables are placed in the
+environment of the script before it is loaded. Variables 
+for options that may be repeated have list values. Other 
+variables can be set using name=value on the command line. 
+After the script is loaded, option values that were not set 
+on the command line are replaced by the values set in the script.
+
+=item B<-F=FILE>, B<--config=FILE>
+
+Use the given SXP formated configuration script.
+SXP is the underlying configuration format used by Xen.
+SXP configuration scripts can be hand-written or generated
+from Python configuration scripts, using the -n
+(dryrun) option to print the configuration.  An SXP formatted
+configuration file may also be generated for a given I<domain-id> by 
+redirecting the output from the the B<xm list --long I<domain-id>> 
+to a file.
+
+=item B<-n>, B<--dryrun>
+
+Dry run - prints the resulting configuration in SXP
+but does not create the domain.
+
+=item B<-x>, B<--xmldryrun>
+
+XML dry run - prints the resulting configuration in
+XML but does not create the domain.
+
+=item B<-s>, B<--skipdtd>
+
+Skip DTD checking - skips checks on XML before
+creating. Experimental. Can decrease create time.
+
+=item B<-p>, B<--paused>
+
+Leave the domain paused after it is created.
+
+=item B<-c>, B<--console_autoconnect>
+
+Attach console to the domain as soon as it has started.  This is
 useful for determining issues with crashing domains.
 
 =back
@@ -118,6 +173,11 @@ virtual networking.  (This example comes from the xm-test test suite.)
 
 =back
 
+=item B<delete>
+
+Remove a domain from Xend domain management. The B<xm list> command
+shows the domain names.
+
 =item B<destroy> I<domain-id>
 
 Immediately terminate the domain I<domain-id>.  This doesn't give the
@@ -133,6 +193,28 @@ Converts a domain name to a domain id using xend's internal mapping.
 
 Converts a domain id to a domain name using xend's internal mapping.
 
+=item B<dump-core> [I<OPTIONS>] I<domain-id> [I<filename>]
+
+Dumps the virtual machine's memory for the specified domain to the
+I<filename> specified.  The dump file will be written to a distribution
+specific directory for dump files.  Such as: /var/lib/xen/dump or 
+/var/xen/dump  Defaults to dumping the core without pausing the domain
+if no I<OPTIONS> are specified.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-L>, B<--live>
+
+Dump core without pausing the domain.
+
+=item B<-C>, B<--crash>
+
+Crash domain after dumping core.
+
+=back
+
 =item B<help> [B<--long>]
 
 Displays the short help message (i.e. common commands).
@@ -140,11 +222,36 @@ Displays the short help message (i.e. common commands).
 The B<--long> option prints out the complete set of B<xm> subcommands,
 grouped by function.
 
-=item B<list> [B<--long> | B<--label>] [I<domain-id> ...]
+=item B<list> [I<OPTIONS>] [I<domain-id> ...]
 
 Prints information about one or more domains.  If no domains are
 specified it prints out information about all domains.
 
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-l>, B<--long>
+
+The output for B<xm list> is not the table view shown below, but 
+instead presents the data in SXP format.
+
+=item B<--label>
+
+Security labels are added to the output of xm list and the lines 
+are sorted by the labels (ignoring case). 
+See the ACCESS CONTROL SUBCOMMAND section of this man page for more 
+information about labels.
+
+=item B<--state=<state>>
+
+Output information for VMs in the specified state.
+
+=back
+
+B<EXAMPLE>
+
 An example format for the list is as follows:
 
     Name                         ID Mem(MiB) VCPUs State  Time(s)
@@ -164,11 +271,11 @@ Xen.
 
 B<STATES>
 
-=over 4
-
 The State field lists 6 states for a Xen domain, and which ones the
 current domain is in.
 
+=over 4
+
 =item B<r - running>
 
 The domain is currently running on a CPU.
@@ -205,32 +312,6 @@ FIXME: Is this right?
 
 =back
 
-B<LONG OUTPUT>
-
-=over 4
-
-If B<--long> is specified, the output for B<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<LABEL OUTPUT>
-
-=over 4
-
-If B<--label> is specified, the security labels are added to the
-output of B<xm list> and the lines are sorted by the labels (ignoring
-case). The B<--long> option prints the labels by default and cannot be
-combined with B<--label>. See the ACCESS CONTROL SUBCOMMAND section of
-this man page for more information about labels.
-
-==back
-
 B<NOTES>
 
 =over 4
@@ -296,6 +377,90 @@ attempting to do other useful work.
 
 =back
 
+=item B<new> I<configfile> [I<OPTIONS>] [I<vars>]...
+
+Adds a domain to Xend domain management.
+
+The new subcommand requires a config file and can optionally 
+take a series of I<vars> that add to or override variables 
+defined in the config file.  See xmdomain.cfg for full details of that 
+file format, and possible options used in either the configfile or for
+I<vars>.
+
+I<configfile> can either be an absolute path to a file, or a relative 
+path to a file located in /etc/xen.
+
+The new subcommand will return without starting the domain.  The 
+domain needs to be started using the B<xm start> command.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<--help_config>
+
+Print the available configuration variables I<vars>.  These variables may be
+used on the command line or in the configuration file I<configfile>.
+
+=item B<-q>, B<--quiet>
+
+No console output.
+
+=item B<--path>
+
+Search path for configuration scripts. The value of PATH is a 
+colon-separated directory list.
+
+=item B<-f=FILE>, B<--defconfig=FILE>
+
+
+Use the given Python configuration script. The configuration 
+script is loaded after arguments have been processed. Each 
+command-line option sets a configuration variable named after 
+its long option name, and these variables are placed in the
+environment of the script before it is loaded. Variables 
+for options that may be repeated have list values. Other 
+variables can be set using name=value on the command line. 
+After the script is loaded, option values that were not set 
+on the command line are replaced by the values set in the script.
+
+=item B<-F=FILE>, B<--config=FILE>
+
+Use the given SXP formated configuration script.
+SXP is the underlying configuration format used by Xen.
+SXP configuration scripts can be hand-written or generated
+from Python configuration scripts, using the -n
+(dryrun) option to print the configuration.  An SXP formatted
+configuration file may also be generated for a given I<domain-id> by 
+redirecting the output from the the B<xm list --long I<domain-id>> 
+to a file.
+
+=item B<-n>, B<--dryrun>
+
+Dry run - prints the resulting configuration in SXP
+but does not create the domain.
+
+=item B<-x>, B<--xmldryrun>
+
+XML dry run - prints the resulting configuration in
+XML but does not create the domain.
+
+=item B<-s>, B<--skipdtd>
+
+Skip DTD checking - skips checks on XML before
+creating. Experimental. Can decrease create time.
+
+=item B<-p>, B<--paused>
+
+Leave the domain paused after it is created.
+
+=item B<-c>, B<--console_autoconnect>
+
+Attach console to the domain as soon as it has started.  This is
+useful for determining issues with crashing domains.
+
+=back
+
 =item B<pause> I<domain-id>
 
 Pause a domain.  When in a paused state the domain will still consume
@@ -332,6 +497,22 @@ as all services in the domain will have to be shut down cleanly.
 
 Build a domain from an B<xm save> state file.  See B<save> for more info.
 
+=item B<resume> I<domain-name> [I<OPTIONS>]
+
+Moves a domain out of the suspended state and back into memory.  
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-p>, <--paused>
+
+Moves a domain back into memory but leaves the domain in a paused state.
+The B<xm unpause> subcommand may then be used to bring it out of the 
+paused state.
+
+=back
+
 =item B<save> I<domain-id> I<state-file>
 
 Saves a running domain to a state file so that it can be restored
@@ -370,6 +551,31 @@ Wait for the domain to complete shutdown before returning.
 
 =back
 
+=item B<start> I<domain-name> [I<OPTIONS>]
+
+Start a Xend managed domain that was added using the B<xm new> command.
+
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-p>, B<--paused>
+
+Do not unpause domain after starting it.
+
+=item B<-c>, B<--console_autoconnect>
+
+Connect to the console after the domain is created.
+
+=back
+
+=item B<suspend> I<domain-name>
+
+Suspend a domain to a state file so that it can be later
+resumed using the B<xm resume> subcommand.  Similar to the B<xm save> 
+subcommand although the state file may not be specified.
+
 =item B<sysrq> I<domain-id> I<letter>
 
 Send a I<Magic System Request> signal to the domain.  For more
@@ -477,11 +683,11 @@ page more readable):
 
 B<FIELDS>
 
-=over 4
-
 Not all fields will be explained here, but some of the less obvious
 ones deserve explanation:
 
+=over 4
+
 =item B<hw_caps>
 
 A vector showing what hardware capabilities are supported by your
@@ -515,6 +721,10 @@ Executes the B<xentop> command, which provides real time monitoring of
 domains.  Xentop is a curses interface, and reasonably self
 explanatory.
 
+=item B<uptime>
+
+Prints the current uptime of the domains running.
+
 =back
 
 =head1 SCHEDULER SUBCOMMANDS
@@ -698,14 +908,20 @@ in the domain.
 List virtual block devices for a domain.  The returned output is
 formatted as a list or as an S-Expression if the B<--long> option was given.
 
+=back
+
 =head2 NETWORK DEVICES
 
+=over 4
+
 =item B<network-attach> I<domain-id> [B<script=>I<scriptname>] [B<ip=>I<ipaddr>]
 [B<mac=>I<macaddr>] [B<bridge=>I<bridge-name>] [B<backend=>I<bedomain-id>]
 
 Creates a new network device in the domain specified by I<domain-id>.  It
 takes the following optional options:
 
+=back
+
 B<OPTIONS>
 
 =over 4
@@ -739,6 +955,8 @@ The backend domain id.  By default this is domain 0.
 
 =back
 
+=over 4
+
 =item B<network-detach> I<domain-id> I<devid>
 
 Removes the network device from the domain specified by I<domain-id>.
@@ -753,8 +971,12 @@ removed from domain 0.
 List virtual network interfaces for a domain.  The returned output is
 formatted as a list or as an S-Expression if the B<--long> option was given.
 
+=back
+
 =head2 VIRTUAL TPM DEVICES
 
+=over 4
+
 =item B<vtpm-list> [B<-l>|B<--long>] I<domain-id>
 
 Show the virtual TPM device for a domain.  The returned output is
@@ -828,6 +1050,8 @@ security in Xen, you must compile Xen with ACM support enabled as
 described under "Configuring Security" below. There, you will find
 also examples of each subcommand described here.
 
+=over 4
+
 =item B<setpolicy> ACM I<policy>
 
 Makes the given ACM policy available to xend as a I<xend-managed policy>.
@@ -836,6 +1060,8 @@ version of the policy is created. The policy is loaded and the system's
 bootloader is prepared to boot the system with this policy the next time
 it is started.
 
+=back
+
 =over 4
 
 I<policy> is a dot-separated list of names. The last part is the file
@@ -849,6 +1075,8 @@ global policy root directory.
 
 =back
 
+=over 4
+
 =item B<resetpolicy>
 
 Reset the system's policy to the default state where the DEFAULT policy
@@ -1155,6 +1383,8 @@ their binary identifiers (ssidrefs) used inside Xen.
 
 =back
 
+=back
+
 =head1 SEE ALSO
 
 B<xmdomain.cfg>(5), B<xentop>(1)