direct-io.hg

changeset 15480:daa07db3ca84

docs: update xm man page

- Fixed description of "Mem" column in "xm list" output.
- Added a bit of text for the credit scheduler.
- Described the --force option to block-detach.
- Made formatting and spelling more consistent.
- etc...

Signed-off-by: Charles Coffing <ccoffing@novell.com>
author kfraser@localhost.localdomain
date Fri Jul 06 14:45:02 2007 +0100 (2007-07-06)
parents d49e6a814d9a
children 538c3d8aa4b1
files docs/man/xm.pod.1
line diff
     1.1 --- a/docs/man/xm.pod.1	Fri Jul 06 14:43:51 2007 +0100
     1.2 +++ b/docs/man/xm.pod.1	Fri Jul 06 14:45:02 2007 +0100
     1.3 @@ -4,7 +4,7 @@ xm - Xen management user interface
     1.4  
     1.5  =head1 SYNOPSIS
     1.6  
     1.7 -xm <subcommand> [args]
     1.8 +B<xm> I<subcommand> [I<args>]
     1.9  
    1.10  =head1 DESCRIPTION
    1.11  
    1.12 @@ -13,46 +13,50 @@ domains. The program can be used to crea
    1.13  domains. It can also be used to list current domains, enable or pin
    1.14  VCPUs, and attach or detach virtual block devices.
    1.15  
    1.16 -The basic structure of every xm command is almost always:
    1.17 -
    1.18 -  xm <subcommand> <domain-id> [OPTIONS]
    1.19 +The basic structure of every B<xm> command is almost always:
    1.20  
    1.21 -Where I<subcommand> is one of the sub commands listed below, I<domain-id>
    1.22 +=over 2
    1.23 +
    1.24 +B<xm> I<subcommand> I<domain-id> [I<OPTIONS>]
    1.25 +
    1.26 +=back
    1.27 +
    1.28 +Where I<subcommand> is one of the subcommands listed below, I<domain-id>
    1.29  is the numeric domain id, or the domain name (which will be internally
    1.30 -translated to domain id), and I<OPTIONS> are sub command specific
    1.31 +translated to domain id), and I<OPTIONS> are subcommand specific
    1.32  options.  There are a few exceptions to this rule in the cases where
    1.33 -the sub command in question acts on all domains, the entire machine,
    1.34 -or directly on the xen hypervisor.  Those exceptions will be clear for
    1.35 -each of those sub commands.
    1.36 +the subcommand in question acts on all domains, the entire machine,
    1.37 +or directly on the Xen hypervisor.  Those exceptions will be clear for
    1.38 +each of those subcommands.
    1.39  
    1.40  =head1 NOTES
    1.41  
    1.42  All B<xm> operations rely upon the Xen control daemon, aka B<xend>.
    1.43 -For any xm commands to run xend must also be running.  For this reason
    1.44 -you should start xend as a service when your system first boots using
    1.45 -xen.
    1.46 +For any B<xm> commands to run, xend must also be running.  For this
    1.47 +reason you should start xend as a service when your system first boots
    1.48 +using Xen.
    1.49  
    1.50  Most B<xm> commands require root privileges to run due to the
    1.51  communications channels used to talk to the hypervisor.  Running as
    1.52  non root will return an error.
    1.53  
    1.54  Most B<xm> commands act asynchronously, so just because the B<xm>
    1.55 -command returned, doesn't mean the action is complete.  This is
    1.56 +command returned doesn't mean the action is complete.  This is
    1.57  important, as many operations on domains, like create and shutdown,
    1.58  can take considerable time (30 seconds or more) to bring the machine
    1.59  into a fully compliant state.  If you want to know when one of these
    1.60 -actions has finished you must poll through xm list periodically.
    1.61 +actions has finished you must poll through B<xm list> periodically.
    1.62  
    1.63  =head1 DOMAIN SUBCOMMANDS
    1.64  
    1.65 -The following sub commands manipulate domains directly, as stated
    1.66 -previously most commands take domain-id as the first parameter.
    1.67 +The following subcommands manipulate domains directly.  As stated
    1.68 +previously, most commands take I<domain-id> as the first parameter.
    1.69  
    1.70  =over 4
    1.71  
    1.72  =item B<console> I<domain-id>
    1.73  
    1.74 -Attach to domain domain-id's console.  If you've set up your Domains to
    1.75 +Attach to domain I<domain-id>'s console.  If you've set up your domains to
    1.76  have a traditional log in console this will look much like a normal
    1.77  text log in screen.
    1.78  
    1.79 @@ -63,15 +67,15 @@ The attached console will perform much l
    1.80  so running curses based interfaces over the console B<is not
    1.81  advised>.  Vi tends to get very odd when using it over this interface.
    1.82  
    1.83 -=item B<create> I<[-c]> I<configfile> I<[name=value]>..
    1.84 +=item B<create> [B<-c>] I<configfile> [I<name>=I<value>]..
    1.85  
    1.86 -The create sub command requires a configfile and can optional take a
    1.87 +The create sub command requires a config file and can optionally take a
    1.88  series of name value pairs that add to or override variables defined
    1.89  in the config file.  See L<xmdomain.cfg> for full details of that file
    1.90  format, and possible options used in either the configfile or
    1.91 -Name=Value combinations.
    1.92 +I<name>=I<value> combinations.
    1.93  
    1.94 -Configfile can either be an absolute path to a file, or a relative
    1.95 +I<configfile> can either be an absolute path to a file, or a relative
    1.96  path to a file located in /etc/xen.
    1.97  
    1.98  Create will return B<as soon> as the domain is started.  This B<does
    1.99 @@ -116,10 +120,10 @@ virtual networking.  (This example comes
   1.100  
   1.101  =item B<destroy> I<domain-id>
   1.102  
   1.103 -Immediately terminate the domain domain-id.  This doesn't give the domain
   1.104 -OS any chance to react, and it the equivalent of ripping the power
   1.105 -cord out on a physical machine.  In most cases you will want to use
   1.106 -the B<shutdown> command instead.
   1.107 +Immediately terminate the domain I<domain-id>.  This doesn't give the
   1.108 +domain OS any chance to react, and is the equivalent of ripping the
   1.109 +power cord out on a physical machine.  In most cases you will want to
   1.110 +use the B<shutdown> command instead.
   1.111  
   1.112  =item B<domid> I<domain-name>
   1.113  
   1.114 @@ -129,14 +133,14 @@ Converts a domain name to a domain id us
   1.115  
   1.116  Converts a domain id to a domain name using xend's internal mapping.
   1.117  
   1.118 -=item B<help> I<[--long]>
   1.119 +=item B<help> [B<--long>]
   1.120  
   1.121  Displays the short help message (i.e. common commands).
   1.122  
   1.123 -The I<--long> option prints out the complete set of B<xm> subcommands,
   1.124 +The B<--long> option prints out the complete set of B<xm> subcommands,
   1.125  grouped by function.
   1.126  
   1.127 -=item B<list> I<[--long | --label]> I<[domain-id, ...]>
   1.128 +=item B<list> [B<--long> | B<--label>] [I<domain-id> ...]
   1.129  
   1.130  Prints information about one or more domains.  If no domains are
   1.131  specified it prints out information about all domains.
   1.132 @@ -151,21 +155,23 @@ An example format for the list is as fol
   1.133      Mandrake10.2                167      128     1 ------     2.5
   1.134      Suse9.2                     168      100     1 ------     1.8
   1.135  
   1.136 -Name is the name of the domain.  ID the domain numeric id.  Mem is the
   1.137 -size of the memory allocated to the domain.  VCPUS is the number of
   1.138 -VCPUS allocated to domain.  State is the run state (see below).  Time
   1.139 -is the total run time of the domain as accounted for by Xen.
   1.140 +Name is the name of the domain.  ID the numeric domain id.  Mem is the
   1.141 +desired amount of memory to allocate to the domain (although it may
   1.142 +not be the currently allocated amount).  VCPUs is the number of
   1.143 +virtual CPUs allocated to the domain.  State is the run state (see
   1.144 +below).  Time is the total run time of the domain as accounted for by
   1.145 +Xen.
   1.146  
   1.147  B<STATES>
   1.148  
   1.149  =over 4
   1.150  
   1.151 -The State field lists 6 states for a Xen Domain, and which ones the
   1.152 -current Domain is in.
   1.153 +The State field lists 6 states for a Xen domain, and which ones the
   1.154 +current domain is in.
   1.155  
   1.156  =item B<r - running>
   1.157  
   1.158 -The domain is currently running on a CPU
   1.159 +The domain is currently running on a CPU.
   1.160  
   1.161  =item B<b - blocked>
   1.162  
   1.163 @@ -203,12 +209,12 @@ B<LONG OUTPUT>
   1.164  
   1.165  =over 4
   1.166  
   1.167 -If I<--long> is specified, the output for xm list is not the table
   1.168 +If B<--long> is specified, the output for B<xm list> is not the table
   1.169  view shown above, but instead is an S-Expression representing all
   1.170  information known about all domains asked for.  This is mostly only
   1.171  useful for external programs to parse the data.
   1.172  
   1.173 -B<Note:> there is no stable guarantees on the format of this data.
   1.174 +B<Note:> There is no stable guarantees on the format of this data.
   1.175  Use at your own risk.
   1.176  
   1.177  =back
   1.178 @@ -217,10 +223,10 @@ B<LABEL OUTPUT>
   1.179  
   1.180  =over 4
   1.181  
   1.182 -If I<--label> is specified, the security labels are added to the
   1.183 -output of xm list and the lines are sorted by the labels (ignoring
   1.184 -case). The I<--long> option prints the labels by default and cannot be
   1.185 -combined with I<--label>. See the ACCESS CONTROL SUBCOMMAND section of
   1.186 +If B<--label> is specified, the security labels are added to the
   1.187 +output of B<xm list> and the lines are sorted by the labels (ignoring
   1.188 +case). The B<--long> option prints the labels by default and cannot be
   1.189 +combined with B<--label>. See the ACCESS CONTROL SUBCOMMAND section of
   1.190  this man page for more information about labels.
   1.191  
   1.192  ==back
   1.193 @@ -230,7 +236,7 @@ B<NOTES>
   1.194  =over 4
   1.195  
   1.196  The Time column is deceptive.  Virtual IO (network and block devices)
   1.197 -used by Domains requires coordination by Domain0, which means that
   1.198 +used by domains requires coordination by Domain0, which means that
   1.199  Domain0 is actually charged for much of the time that a DomainU is
   1.200  doing IO.  Use of this time value to determine relative utilizations
   1.201  by domains is thus very suspect, as a high IO workload may show as
   1.202 @@ -240,11 +246,11 @@ less utilized than a high CPU workload. 
   1.203  
   1.204  =item B<mem-max> I<domain-id> I<mem>
   1.205  
   1.206 -Specify the maximum amount of memory the Domain is able to use.  Mem
   1.207 +Specify the maximum amount of memory the domain is able to use.  I<mem>
   1.208  is specified in megabytes. 
   1.209  
   1.210  The mem-max value may not correspond to the actual memory used in the
   1.211 -Domain, as it may balloon down it's memory to give more back to the OS.
   1.212 +domain, as it may balloon down its memory to give more back to the OS.
   1.213  
   1.214  =item B<mem-set> I<domain-id> I<mem>
   1.215  
   1.216 @@ -252,20 +258,20 @@ Set the domain's used memory using the b
   1.217  operation requires cooperation from the domain operating system, there
   1.218  is no guarantee that it will succeed.
   1.219  
   1.220 -B<Warning:> there is no good way to know in advance how small of a
   1.221 +B<Warning:> There is no good way to know in advance how small of a
   1.222  mem-set will make a domain unstable and cause it to crash.  Be very
   1.223  careful when using this command on running domains.
   1.224  
   1.225 -=item B<migrate> I<domain-id> I<host> I<[options]>
   1.226 +=item B<migrate> I<domain-id> I<host> [I<OPTIONS>]
   1.227  
   1.228 -Migrate a domain to another Host machine. B<Xend> must be running on
   1.229 -other host machine, it must be running the same version of xen, it
   1.230 +Migrate a domain to another host machine. Xend must be running on
   1.231 +other host machine, it must be running the same version of Xen, it
   1.232  must have the migration TCP port open and accepting connections from
   1.233  the source host, and there must be sufficient resources for the domain
   1.234  to run (memory, disk, etc).
   1.235  
   1.236 -Migration is pretty complicated, and has many security implications,
   1.237 -please read the Xen Users Guide to ensure you understand the
   1.238 +Migration is pretty complicated, and has many security implications.
   1.239 +Please read the Xen User's Guide to ensure you understand the
   1.240  ramifications and limitations on migration before attempting it in
   1.241  production.
   1.242  
   1.243 @@ -273,13 +279,13 @@ B<OPTIONS>
   1.244  
   1.245  =over 4
   1.246  
   1.247 -=item B<-l, --live>
   1.248 +=item B<-l>, B<--live>
   1.249  
   1.250  Use live migration.  This will migrate the domain between hosts
   1.251 -without shutting down the domain.  See the Xen Users Guide for more
   1.252 +without shutting down the domain.  See the Xen User's Guide for more
   1.253  information.
   1.254  
   1.255 -=item B<-r, --resource> I<Mbs>
   1.256 +=item B<-r>, B<--resource> I<Mbs>
   1.257  
   1.258  Set maximum Mbs allowed for migrating the domain.  This ensures that
   1.259  the network link is not saturated with migration traffic while
   1.260 @@ -293,7 +299,7 @@ Pause a domain.  When in a paused state 
   1.261  allocated resources such as memory, but will not be eligible for
   1.262  scheduling by the Xen hypervisor.
   1.263  
   1.264 -=item B<reboot> I<[options]> I<domain-id>
   1.265 +=item B<reboot> [I<OPTIONS>] I<domain-id>
   1.266  
   1.267  Reboot a domain.  This acts just as if the domain had the B<reboot>
   1.268  command run from the console.  The command returns as soon as it has
   1.269 @@ -301,18 +307,18 @@ executed the reboot action, which may be
   1.270  domain actually reboots.
   1.271  
   1.272  The behavior of what happens to a domain when it reboots is set by the
   1.273 -I<on_reboot> parameter of the xmdomain.cfg file when the domain was
   1.274 +B<on_reboot> parameter of the xmdomain.cfg file when the domain was
   1.275  created.
   1.276  
   1.277  B<OPTIONS>
   1.278  
   1.279  =over 4
   1.280  
   1.281 -=item B<-a, --all>
   1.282 +=item B<-a>, B<--all>
   1.283  
   1.284 -Reboot all domains
   1.285 +Reboot all domains.
   1.286  
   1.287 -=item B<-w, --wait>
   1.288 +=item B<-w>, B<--wait>
   1.289  
   1.290  Wait for reboot to complete before returning.  This may take a while,
   1.291  as all services in the domain will have to be shut down cleanly.
   1.292 @@ -321,7 +327,7 @@ as all services in the domain will have 
   1.293  
   1.294  =item B<restore> I<state-file>
   1.295  
   1.296 -Build a domain from an B<xm save> state file.  See I<save> for more info.
   1.297 +Build a domain from an B<xm save> state file.  See B<save> for more info.
   1.298  
   1.299  =item B<save> I<domain-id> I<state-file>
   1.300  
   1.301 @@ -334,16 +340,16 @@ This is roughly equivalent to doing a hi
   1.302  with all the same limitations.  Open network connections may be
   1.303  severed upon restore, as TCP timeouts may have expired.
   1.304  
   1.305 -=item B<shutdown> I<[options]> I<domain-id>
   1.306 +=item B<shutdown> [I<OPTIONS>] I<domain-id>
   1.307  
   1.308  Gracefully shuts down a domain.  This coordinates with the domain OS
   1.309  to perform graceful shutdown, so there is no guarantee that it will
   1.310  succeed, and may take a variable length of time depending on what
   1.311  services must be shutdown in the domain.  The command returns
   1.312 -immediately after signally the domain unless that I<-w> flag is used.
   1.313 +immediately after signally the domain unless that B<-w> flag is used.
   1.314  
   1.315  The behavior of what happens to a domain when it reboots is set by the
   1.316 -I<on_shutdown> parameter of the xmdomain.cfg file when the domain was
   1.317 +B<on_shutdown> parameter of the xmdomain.cfg file when the domain was
   1.318  created.
   1.319  
   1.320  B<OPTIONS>
   1.321 @@ -386,7 +392,7 @@ Attempting to set the VCPUs to a number 
   1.322  configured VCPU count is an error.  Trying to set VCPUs to < 1 will be
   1.323  quietly ignored.
   1.324  
   1.325 -=item B<vcpu-list> I<[domain-id]>
   1.326 +=item B<vcpu-list> [I<domain-id>]
   1.327  
   1.328  Lists VCPU information for a specific domain.  If no domain is
   1.329  specified, VCPU information for all domains will be provided.
   1.330 @@ -394,7 +400,7 @@ specified, VCPU information for all doma
   1.331  =item B<vcpu-pin> I<domain-id> I<vcpu> I<cpus>
   1.332  
   1.333  Pins the the VCPU to only run on the specific CPUs.  The keyword
   1.334 -I<all> can be used to apply the I<cpus> list to all VCPUs in the
   1.335 +B<all> can be used to apply the I<cpus> list to all VCPUs in the
   1.336  domain.
   1.337  
   1.338  Normally VCPUs can float between available CPUs whenever Xen deems a
   1.339 @@ -408,7 +414,7 @@ CPUs.
   1.340  
   1.341  =over 4
   1.342  
   1.343 -=item B<dmesg> I<[-c]>
   1.344 +=item B<dmesg> [B<-c>]
   1.345  
   1.346  Reads the Xen message buffer, similar to dmesg on a Linux system.  The
   1.347  buffer contains informational, warning, and error messages created
   1.348 @@ -419,7 +425,7 @@ B<OPTIONS>
   1.349  
   1.350  =over 4
   1.351  
   1.352 -=item B<-c, --clear>
   1.353 +=item B<-c>, B<--clear>
   1.354  
   1.355  Clears Xen's message buffer.
   1.356  
   1.357 @@ -431,8 +437,8 @@ Print information about the Xen host in 
   1.358  reporting a Xen bug, please provide this information as part of the
   1.359  bug report.
   1.360  
   1.361 -Sample xen domain info looks as follows (lines wrapped manually to
   1.362 -make the man page more readable):
   1.363 +Sample output looks as follows (lines wrapped manually to make the man
   1.364 +page more readable):
   1.365  
   1.366   host                   : talon
   1.367   release                : 2.6.12.6-xen0
   1.368 @@ -470,36 +476,36 @@ B<FIELDS>
   1.369  Not all fields will be explained here, but some of the less obvious
   1.370  ones deserve explanation:
   1.371  
   1.372 -=item I<hw_caps>
   1.373 +=item B<hw_caps>
   1.374  
   1.375  A vector showing what hardware capabilities are supported by your
   1.376  processor.  This is equivalent to, though more cryptic, the flags
   1.377  field in /proc/cpuinfo on a normal Linux machine.
   1.378  
   1.379 -=item I<free_memory>
   1.380 +=item B<free_memory>
   1.381  
   1.382 -Available memory (in MB) not allocated to Xen, or any other Domains.
   1.383 +Available memory (in MB) not allocated to Xen, or any other domains.
   1.384  
   1.385 -=item I<xen_caps>
   1.386 +=item B<xen_caps>
   1.387  
   1.388 -The xen version, architecture.  Architecture values can be one of:
   1.389 +The Xen version and architecture.  Architecture values can be one of:
   1.390  x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
   1.391  
   1.392 -=item I<xen_changeset>
   1.393 +=item B<xen_changeset>
   1.394  
   1.395 -The xen mercurial changeset id.  Very useful for determining exactly
   1.396 +The Xen mercurial changeset id.  Very useful for determining exactly
   1.397  what version of code your Xen system was built from.
   1.398  
   1.399  =back
   1.400  
   1.401  =item B<log>
   1.402  
   1.403 -Print out the B<xend> log.  This log file can be found in
   1.404 +Print out the xend log.  This log file can be found in
   1.405  /var/log/xend.log.
   1.406  
   1.407  =item B<top>
   1.408  
   1.409 -Executes the xentop command, which provides real time monitoring of
   1.410 +Executes the B<xentop> command, which provides real time monitoring of
   1.411  domains.  Xentop is a curses interface, and reasonably self
   1.412  explanatory.
   1.413  
   1.414 @@ -508,13 +514,41 @@ explanatory.
   1.415  =head1 SCHEDULER SUBCOMMANDS
   1.416  
   1.417  Xen ships with a number of domain schedulers, which can be set at boot
   1.418 -time with the I<sched=> parameter on the Xen command line.  By
   1.419 -default I<sedf> is used for scheduling.
   1.420 +time with the B<sched=> parameter on the Xen command line.  By
   1.421 +default B<credit> is used for scheduling.
   1.422  
   1.423  FIXME: we really need a scheduler expert to write up this section.
   1.424  
   1.425  =over 4
   1.426  
   1.427 +=item B<sched-credit> [ B<-d> I<domain-id> [ B<-w>[B<=>I<WEIGHT>] | B<-c>[B<=>I<CAP>] ] ]
   1.428 +
   1.429 +Set credit scheduler parameters.  The credit scheduler is a
   1.430 +proportional fair share CPU scheduler built from the ground up to be
   1.431 +work conserving on SMP hosts.
   1.432 +
   1.433 +Each domain (including Domain0) is assigned a weight and a cap.
   1.434 +
   1.435 +B<PARAMETERS>
   1.436 +
   1.437 +=over 4
   1.438 +
   1.439 +=item I<WEIGHT>
   1.440 +
   1.441 +A domain with a weight of 512 will get twice as much CPU as a domain
   1.442 +with a weight of 256 on a contended host. Legal weights range from 1
   1.443 +to 65535 and the default is 256.
   1.444 +
   1.445 +=item I<CAP>
   1.446 +
   1.447 +The cap optionally fixes the maximum amount of CPU a domain will be
   1.448 +able to consume, even if the host system has idle CPU cycles. The cap
   1.449 +is expressed in percentage of one physical CPU: 100 is 1 physical CPU,
   1.450 +50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is
   1.451 +no upper cap.
   1.452 +
   1.453 +=back
   1.454 +
   1.455  =item B<sched-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
   1.456  
   1.457  Set Simple EDF (Earliest Deadline First) scheduler parameters.  This
   1.458 @@ -546,7 +580,7 @@ Flag for allowing domain to run in extra
   1.459  
   1.460  =item I<weight>
   1.461  
   1.462 -Another way of setting cpu slice.
   1.463 +Another way of setting CPU slice.
   1.464  
   1.465  =back
   1.466  
   1.467 @@ -591,7 +625,7 @@ event.
   1.468  
   1.469  =over 4
   1.470  
   1.471 -=item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> I<[bedomain-id]>
   1.472 +=item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> [I<bedomain-id>]
   1.473  
   1.474  Create a new virtual block device.  This will trigger a hotplug event
   1.475  for the guest.
   1.476 @@ -619,7 +653,7 @@ devices, or by device id, such as 0x1400
   1.477  =item I<mode>
   1.478  
   1.479  The access mode for the device from the guest domain.  Supported modes
   1.480 -are I<w> (read/write) or I<r> (read-only).
   1.481 +are B<w> (read/write) or B<r> (read-only).
   1.482  
   1.483  =item I<bedomain-id>
   1.484  
   1.485 @@ -635,62 +669,65 @@ B<EXAMPLES>
   1.486  
   1.487  xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso /dev/hdc ro
   1.488  
   1.489 -This will mount the dsl iso as /dev/hdc in the guestdomain as a read
   1.490 -only device.  This will probably not be detected as a cdrom by the
   1.491 +This will mount the dsl ISO as /dev/hdc in the guestdomain as a read
   1.492 +only device.  This will probably not be detected as a CD-ROM by the
   1.493  guest, but mounting /dev/hdc manually will work.
   1.494  
   1.495  =back
   1.496  
   1.497 -=item B<block-detach> I<domain-id> I<devid>
   1.498 +=item B<block-detach> I<domain-id> I<devid> [B<--force>]
   1.499  
   1.500 -Destroy a domain's virtual block device. devid B<must> be the device
   1.501 -id given to the device by domain 0.  You will need to run I<xm
   1.502 -block-list> to determine that number.
   1.503 +Detach a domain's virtual block device. I<devid> may be the symbolic
   1.504 +name or the numeric device id given to the device by domain 0.  You
   1.505 +will need to run B<xm block-list> to determine that number.
   1.506  
   1.507 -FIXME: this is currently B<broken>.  Even though a block device is
   1.508 -removed from domU, it appears to still be allocated in the domain 0.
   1.509 +Detaching the device requires the cooperation of the domain.  If the
   1.510 +domain fails to release the device (perhaps because the domain is hung
   1.511 +or is still using the device), the detach will fail.  The B<--force>
   1.512 +parameter will forcefully detach the device, but may cause IO errors
   1.513 +in the domain.
   1.514  
   1.515 -=item B<block-list> I<[-l|--long]> I<domain-id>
   1.516 +=item B<block-list> [B<-l>|B<--long>] I<domain-id>
   1.517  
   1.518  List virtual block devices for a domain.  The returned output is
   1.519 -formatted as a list or as an S-Expression if the '--long' option was given.
   1.520 +formatted as a list or as an S-Expression if the B<--long> option was given.
   1.521  
   1.522  =head2 NETWORK DEVICES
   1.523  
   1.524 -=item B<network-attach> I<domain-id> I<[script=scriptname]> I<[ip=ipaddr]>
   1.525 -I<[mac=macaddr]> I<[bridge=bridge-name]> I<[backend=bedomain-id]>
   1.526 +=item B<network-attach> I<domain-id> [B<script=>I<scriptname>] [B<ip=>I<ipaddr>]
   1.527 +[B<mac=>I<macaddr>] [B<bridge=>I<bridge-name>] [B<backend=>I<bedomain-id>]
   1.528  
   1.529 -Creates a new network device in the domain specified by domain-id.  It
   1.530 +Creates a new network device in the domain specified by I<domain-id>.  It
   1.531  takes the following optional options:
   1.532  
   1.533  B<OPTIONS>
   1.534  
   1.535  =over 4
   1.536  
   1.537 -=item I<script=scriptname>
   1.538 +=item B<script=>I<scriptname>
   1.539  
   1.540  Use the specified script name to bring up the network.  Defaults to
   1.541 -the default setting in xend-config.sxp for I<vif-script>.
   1.542 +the default setting in xend-config.sxp for B<vif-script>.
   1.543  
   1.544 -=item I<ip=ipaddr>
   1.545 +=item B<ip=>I<ipaddr>
   1.546  
   1.547  Passes the specified IP Address to the adapter on creation.  
   1.548  
   1.549  FIXME: this currently appears to be B<broken>.  I'm not sure under what
   1.550  circumstances this should actually work.
   1.551  
   1.552 -=item I<mac=macaddr>
   1.553 +=item B<mac=>I<macaddr>
   1.554  
   1.555  The MAC address that the domain will see on its Ethernet device.  If
   1.556  the device is not specified it will be randomly generated with the
   1.557  00:16:3e vendor id prefix.
   1.558  
   1.559 -=item I<bridge=bridge-name>
   1.560 +=item B<bridge=>I<bridge-name>
   1.561  
   1.562  The name of the bridge to attach the vif to, in case you have more
   1.563 -than one.  This defaults to 
   1.564 +than one.  This defaults to xenbr0.
   1.565  
   1.566 -=item I<backend=bedomain-id>
   1.567 +=item B<backend=>I<bedomain-id>
   1.568  
   1.569  The backend domain id.  By default this is domain 0.
   1.570  
   1.571 @@ -705,17 +742,17 @@ I<devid> is the virtual interface device
   1.572  FIXME: this is currently B<broken>.  Network devices aren't completely
   1.573  removed from domain 0.
   1.574  
   1.575 -=item B<network-list> I<[-l|--long]> I<domain-id>
   1.576 +=item B<network-list> [B<-l>|B<--long>]> I<domain-id>
   1.577  
   1.578  List virtual network interfaces for a domain.  The returned output is
   1.579 -formatted as a list or as an S-Expression if the '--long' option was given.
   1.580 +formatted as a list or as an S-Expression if the B<--long> option was given.
   1.581  
   1.582  =head2 VIRTUAL TPM DEVICES
   1.583  
   1.584 -=item B<vtpm-list> I<[-l|--long]> I<domain-id>
   1.585 +=item B<vtpm-list> [B<-l>|B<--long>] I<domain-id>
   1.586  
   1.587  Show the virtual TPM device for a domain.  The returned output is
   1.588 -formatted as a list or as an S-Expression if the '--long' option was given.
   1.589 +formatted as a list or as an S-Expression if the B<--long> option was given.
   1.590  
   1.591  =back
   1.592  
   1.593 @@ -728,7 +765,7 @@ out entirely.
   1.594  
   1.595  =over 4
   1.596  
   1.597 -=item B<vnet-list> I<[-l|--long]>
   1.598 +=item B<vnet-list> [B<-l>|B<--long>]
   1.599  
   1.600  List vnets.
   1.601  
   1.602 @@ -762,7 +799,7 @@ subcommands described below. Currently, 
   1.603  interpret labels:
   1.604  
   1.605  (1) Simple Type Enforcement: Labels are interpreted to decide access
   1.606 -of domains to comunication means and virtual or physical
   1.607 +of domains to communication means and virtual or physical
   1.608  resources. Communication between domains as well as access to
   1.609  resources are forbidden by default and can only take place if they are
   1.610  explicitly allowed by the security policy. The proper assignment of
   1.611 @@ -796,8 +833,8 @@ time with the B<cfgbootpolicy> subcomman
   1.612  =over 4
   1.613  
   1.614  I<policy> is a dot-separated list of names. The last part is the file
   1.615 -name pre-fix for the policy xml file. The preceding name parts are
   1.616 -translated into the local path pointing to the policy xml file
   1.617 +name pre-fix for the policy XML file. The preceding name parts are
   1.618 +translated into the local path pointing to the policy XML file
   1.619  relative to the global policy root directory
   1.620  (/etc/xen/acm-security/policies). For example,
   1.621  example.chwall_ste.client_v1 denotes the policy file
   1.622 @@ -823,16 +860,16 @@ I<boot title> parameter to specify a uni
   1.623  
   1.624  Prints the current security policy state information of Xen.
   1.625  
   1.626 -=item B<labels> [I<policy>] [I<type>=dom|res|any]
   1.627 +=item B<labels> [I<policy>] [B<type=dom>|B<res>|B<any>]
   1.628  
   1.629  Lists all labels of a I<type> (domain, resource, or both) that are
   1.630  defined in the I<policy>. Unless specified, the default I<policy> is
   1.631  the currently enforced access control policy. The default for I<type>
   1.632  is 'dom'. The labels are arranged in alphabetical order.
   1.633  
   1.634 -=item B<addlabel> I<label> dom I<configfile> [I<policy>]
   1.635 +=item B<addlabel> I<label> B<dom> I<configfile> [I<policy>]
   1.636  
   1.637 -=item B<addlabel> I<label> res I<resource> [I<policy>]
   1.638 +=item B<addlabel> I<label> B<res> I<resource> [I<policy>]
   1.639  
   1.640  Adds the security label with name I<label> to a domain
   1.641  I<configfile> (dom) or to the global resource label file for the
   1.642 @@ -841,17 +878,17 @@ currently enforced access control policy
   1.643  verifies that the I<policy> definition supports the specified I<label>
   1.644  name.
   1.645  
   1.646 -=item B<rmlabel> dom I<configfile>
   1.647 +=item B<rmlabel> B<dom> I<configfile>
   1.648  
   1.649 -=item B<rmlabel> res I<resource>
   1.650 +=item B<rmlabel> B<res> I<resource>
   1.651  
   1.652 -Works the same as the I<addlabel> command (above), except that this
   1.653 +Works the same as the B<addlabel> command (above), except that this
   1.654  command will remove the label from the domain I<configfile> (dom) or
   1.655  the global resource label file (res).
   1.656  
   1.657 -=item B<getlabel> dom I<configfile>
   1.658 +=item B<getlabel> B<dom> I<configfile>
   1.659  
   1.660 -=item B<getlabel> res I<resource>
   1.661 +=item B<getlabel> B<res> I<resource>
   1.662  
   1.663  Shows the label for the given I<configfile> or I<resource>
   1.664  
   1.665 @@ -881,7 +918,7 @@ Then recompile and install xen and the s
   1.666  
   1.667      cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
   1.668      cd xen_source_dir/tools/security; make install;
   1.669 -    reboot into xen
   1.670 +    reboot into Xen
   1.671  
   1.672  =back
   1.673  
   1.674 @@ -944,10 +981,10 @@ B<ATTACHING A SECURITY LABEL TO A DOMAIN
   1.675  
   1.676  =over 4
   1.677  
   1.678 -The I<addlabel> subcommand can attach a security label to a domain
   1.679 +The B<addlabel> subcommand can attach a security label to a domain
   1.680  configuration file, here a HomeBanking label. The example policy
   1.681  ensures that this domain does not share information with other
   1.682 -non-hombanking user domains (i.e., domains labeled as dom_Fun or
   1.683 +non-homebanking user domains (i.e., domains labeled as dom_Fun or
   1.684  dom_Boinc) and that it will not run simultaneously with domains
   1.685  labeled as dom_Fun.
   1.686  
   1.687 @@ -958,7 +995,7 @@ probably just a browser environment for 
   1.688      xm addlabel dom_HomeBanking dom myconfig.xm
   1.689  
   1.690  The very simple configuration file might now look as printed
   1.691 -below. The I<addlabel> subcommand added the B<access_control> entry at
   1.692 +below. The B<addlabel> subcommand added the B<access_control> entry at
   1.693  the end of the file, consisting of a label name and the policy that
   1.694  specifies this label name:
   1.695  
   1.696 @@ -986,7 +1023,7 @@ B<ATTACHING A SECURITY LABEL TO A RESOUR
   1.697  
   1.698  =over 4
   1.699  
   1.700 -The I<addlabel> subcommand can also be used to attach a security
   1.701 +The B<addlabel> subcommand can also be used to attach a security
   1.702  label to a resource. Following the home banking example from above,
   1.703  we can label a disk resource (e.g., a physical partition or a file)
   1.704  to make it accessible to the home banking domain. The example policy
   1.705 @@ -1002,7 +1039,7 @@ attaches this disk to the domain at boot
   1.706      disk = [ 'phy:hda6,sda2,w' ]
   1.707  
   1.708  Alternatively, the resource can be attached after booting the domain
   1.709 -by using the I<block-attach> subcommand.
   1.710 +by using the B<block-attach> subcommand.
   1.711  
   1.712      xm block-attach homebanking phy:hda6 sda2 w
   1.713  
   1.714 @@ -1010,7 +1047,7 @@ Note that labeled resources cannot be us
   1.715  off.  Any attempt to use labeled resources with security turned off
   1.716  will result in a failure with a corresponding error message.  The
   1.717  solution is to enable security or, if security is no longer desired,
   1.718 -to remove the resource label using the I<rmlabel> subcommand.
   1.719 +to remove the resource label using the B<rmlabel> subcommand.
   1.720  
   1.721  =back
   1.722  
   1.723 @@ -1048,7 +1085,7 @@ B<POLICY REPRESENTATIONS>
   1.724  =over 4
   1.725  
   1.726  We distinguish three representations of the Xen access control policy:
   1.727 -the I<source XML> version, its I<binary> counterpart, and a I<mapping>
   1.728 +the source XML version, its binary counterpart, and a mapping
   1.729  representation that enables the tools to deterministically translate
   1.730  back and forth between label names of the XML policy and label
   1.731  identifiers of the binary policy. All three versions must be kept
   1.732 @@ -1075,8 +1112,6 @@ their binary identifiers (ssidrefs) used
   1.733  
   1.734  =back
   1.735  
   1.736 -=head1 EXAMPLES
   1.737 -
   1.738  =head1 SEE ALSO
   1.739  
   1.740  B<xmdomain.cfg>(5), B<xentop>(1)