ia64/xen-unstable

view docs/man/xm.pod.1 @ 10060:cb70d4f8d718

Fix spelling errors in man pages.
Signed-off-by: Charles Coffing <ccoffing@novell.com>
author kaf24@firebug.cl.cam.ac.uk
date Mon May 15 07:51:07 2006 +0100 (2006-05-15)
parents c7b9b8a64755
children 25c6ea6d4024
line source
1 =head1 NAME
3 xm - Xen management user interface
5 =head1 SYNOPSIS
7 xm <subcommand> [args]
9 =head1 DESCRIPTION
11 The B<xm> program is the main interface for managing Xen guest
12 domains. The program can be used to create, pause, and shutdown
13 domains. It can also be used to list current domains, enable or pin
14 VCPUs, and attach or detach virtual block devices.
16 The basic structure of every xm command is almost always:
18 xm <subcommand> <domain-id> [OPTIONS]
20 Where I<subcommand> is one of the sub commands listed below, I<domain-id>
21 is the numeric domain id, or the domain name (which will be internally
22 translated to domain id), and I<OPTIONS> are sub command specific
23 options. There are a few exceptions to this rule in the cases where
24 the sub command in question acts on all domains, the entire machine,
25 or directly on the xen hypervisor. Those exceptions will be clear for
26 each of those sub commands.
28 =head1 NOTES
30 All B<xm> operations rely upon the Xen control daemon, aka B<xend>.
31 For any xm commands to run xend must also be running. For this reason
32 you should start xend as a service when your system first boots using
33 xen.
35 Most B<xm> commands require root privileges to run due to the
36 communications channels used to talk to the hypervisor. Running as
37 non root will return an error.
39 Most B<xm> commands act asynchronously, so just because the B<xm>
40 command returned, doesn't mean the action is complete. This is
41 important, as many operations on domains, like create and shutdown,
42 can take considerable time (30 seconds or more) to bring the machine
43 into a fully compliant state. If you want to know when one of these
44 actions has finished you must poll through xm list periodically.
46 =head1 DOMAIN SUBCOMMANDS
48 The following sub commands manipulate domains directly, as stated
49 previously most commands take domain-id as the first parameter.
51 =over 4
53 =item B<console> I<domain-id>
55 Attach to domain domain-id's console. If you've set up your Domains to
56 have a traditional log in console this will look much like a normal
57 text log in screen.
59 This uses the back end xenconsole service which currently only
60 works for para-virtual domains.
62 The attached console will perform much like a standard serial console,
63 so running curses based interfaces over the console B<is not
64 advised>. Vi tends to get very odd when using it over this interface.
66 =item B<create> I<[-c]> I<configfile> I<[name=value]>..
68 The create sub command requires a configfile and can optional take a
69 series of name value pairs that add to or override variables defined
70 in the config file. See L<xmdomain.cfg> for full details of that file
71 format, and possible options used in either the configfile or
72 Name=Value combinations.
74 Configfile can either be an absolute path to a file, or a relative
75 path to a file located in /etc/xen.
77 Create will return B<as soon> as the domain is started. This B<does
78 not> mean the guest OS in the domain has actually booted, or is
79 available for input.
81 B<OPTIONS>
83 =over 4
85 =item B<-c>
87 Attache console to the domain as soon as it has started. This is
88 useful for determining issues with crashing domains.
90 =back
92 B<EXAMPLES>
94 =over 4
96 =item I<with config file>
98 xm create Fedora4
100 This creates a domain with the file /etc/xen/Fedora4, and returns as
101 soon as it is run.
103 =item I<without config file>
105 xm create /dev/null ramdisk=initrd.img \
106 kernel=/boot/vmlinuz-2.6.12.6-xenU \
107 name=ramdisk nics=0 vcpus=1 \
108 memory=64 root=/dev/ram0
110 This creates the domain without using a config file (more specifically
111 using /dev/null as an empty config file), kernel and ramdisk as
112 specified, setting the name of the domain to "ramdisk", also disabling
113 virtual networking. (This example comes from the xm-test test suite.)
115 =back
117 =item B<destroy> I<domain-id>
119 Immediately terminate the domain domain-id. This doesn't give the domain
120 OS any chance to react, and it the equivalent of ripping the power
121 cord out on a physical machine. In most cases you will want to use
122 the B<shutdown> command instead.
124 =item B<domid> I<domain-name>
126 Converts a domain name to a domain id using xend's internal mapping.
128 =item B<domname> I<domain-id>
130 Converts a domain id to a domain name using xend's internal mapping.
132 =item B<help> I<[--long]>
134 Displays the short help message (i.e. common commands).
136 The I<--long> option prints out the complete set of B<xm> subcommands,
137 grouped by function.
139 =item B<list> I<[--long | --label]> I<[domain-id, ...]>
141 Prints information about one or more domains. If no domains are
142 specified it prints out information about all domains.
144 An example format for the list is as follows:
146 Name ID Mem(MiB) VCPUs State Time(s)
147 Domain-0 0 98 1 r----- 5068.6
148 Fedora3 164 128 1 r----- 7.6
149 Fedora4 165 128 1 ------ 0.6
150 Mandrake2006 166 128 1 -b---- 3.6
151 Mandrake10.2 167 128 1 ------ 2.5
152 Suse9.2 168 100 1 ------ 1.8
154 Name is the name of the domain. ID the domain numeric id. Mem is the
155 size of the memory allocated to the domain. VCPUS is the number of
156 VCPUS allocated to domain. State is the run state (see below). Time
157 is the total run time of the domain as accounted for by Xen.
159 B<STATES>
161 =over 4
163 The State field lists 6 states for a Xen Domain, and which ones the
164 current Domain is in.
166 =item B<r - running>
168 The domain is currently running on a CPU
170 =item B<b - blocked>
172 The domain is blocked, and not running or runnable. This can be caused
173 because the domain is waiting on IO (a traditional wait state) or has
174 gone to sleep because there was nothing else for it to do.
176 =item B<p - paused>
178 The domain has been paused, usually occurring through the administrator
179 running B<xm pause>. When in a paused state the domain will still
180 consume allocated resources like memory, but will not be eligible for
181 scheduling by the Xen hypervisor.
183 =item B<s - shutdown>
185 FIXME: Why would you ever see this state?
187 =item B<c - crashed>
189 The domain has crashed, which is always a violent ending. Usually
190 this state can only occur if the domain has been configured not to
191 restart on crash. See L<xmdomain.cfg> for more info.
193 =item B<d - dying>
195 The domain is in process of dying, but hasn't completely shutdown or
196 crashed.
198 FIXME: Is this right?
200 =back
202 B<LONG OUTPUT>
204 =over 4
206 If I<--long> is specified, the output for xm list is not the table
207 view shown above, but instead is an S-Expression representing all
208 information known about all domains asked for. This is mostly only
209 useful for external programs to parse the data.
211 B<Note:> there is no stable guarantees on the format of this data.
212 Use at your own risk.
214 =back
216 B<LABEL OUTPUT>
218 =over 4
220 If I<--label> is specified, the security labels are added to the
221 output of xm list and the lines are sorted by the labels (ignoring
222 case). The I<--long> option prints the labels by default and cannot be
223 combined with I<--label>. See the ACCESS CONTROL SUBCOMMAND section of
224 this man page for more information about labels.
226 ==back
228 B<NOTES>
230 =over 4
232 The Time column is deceptive. Virtual IO (network and block devices)
233 used by Domains requires coordination by Domain0, which means that
234 Domain0 is actually charged for much of the time that a DomainU is
235 doing IO. Use of this time value to determine relative utilizations
236 by domains is thus very suspect, as a high IO workload may show as
237 less utilized than a high CPU workload. Consider yourself warned.
239 =back
241 =item B<mem-max> I<domain-id> I<mem>
243 Specify the maximum amount of memory the Domain is able to use. Mem
244 is specified in megabytes.
246 The mem-max value may not correspond to the actual memory used in the
247 Domain, as it may balloon down it's memory to give more back to the OS.
249 =item B<mem-set> I<domain-id> I<mem>
251 Set the domain's used memory using the balloon driver. Because this
252 operation requires cooperation from the domain operating system, there
253 is no guarantee that it will succeed.
255 B<Warning:> there is no good way to know in advance how small of a
256 mem-set will make a domain unstable and cause it to crash. Be very
257 careful when using this command on running domains.
259 =item B<migrate> I<domain-id> I<host> I<[options]>
261 Migrate a domain to another Host machine. B<Xend> must be running on
262 other host machine, it must be running the same version of xen, it
263 must have the migration TCP port open and accepting connections from
264 the source host, and there must be sufficient resources for the domain
265 to run (memory, disk, etc).
267 Migration is pretty complicated, and has many security implications,
268 please read the Xen Users Guide to ensure you understand the
269 ramifications and limitations on migration before attempting it in
270 production.
272 B<OPTIONS>
274 =over 4
276 =item B<-l, --live>
278 Use live migration. This will migrate the domain between hosts
279 without shutting down the domain. See the Xen Users Guide for more
280 information.
282 =item B<-r, --resource> I<Mbs>
284 Set maximum Mbs allowed for migrating the domain. This ensures that
285 the network link is not saturated with migration traffic while
286 attempting to do other useful work.
288 =back
290 =item B<pause> I<domain-id>
292 Pause a domain. When in a paused state the domain will still consume
293 allocated resources such as memory, but will not be eligible for
294 scheduling by the Xen hypervisor.
296 =item B<reboot> I<[options]> I<domain-id>
298 Reboot a domain. This acts just as if the domain had the B<reboot>
299 command run from the console. The command returns as soon as it has
300 executed the reboot action, which may be significantly before the
301 domain actually reboots.
303 The behavior of what happens to a domain when it reboots is set by the
304 I<on_reboot> parameter of the xmdomain.cfg file when the domain was
305 created.
307 B<OPTIONS>
309 =over 4
311 =item B<-a, --all>
313 Reboot all domains
315 =item B<-w, --wait>
317 Wait for reboot to complete before returning. This may take a while,
318 as all services in the domain will have to be shut down cleanly.
320 =back
322 =item B<restore> I<state-file>
324 Build a domain from an B<xm save> state file. See I<save> for more info.
326 =item B<save> I<domain-id> I<state-file>
328 Saves a running domain to a state file so that it can be restored
329 later. Once saved, the domain will no longer be running on the
330 system, thus the memory allocated for the domain will be free for
331 other domains to use. B<xm restore> restores from this state file.
333 This is roughly equivalent to doing a hibernate on a running computer,
334 with all the same limitations. Open network connections may be
335 severed upon restore, as TCP timeouts may have expired.
337 =item B<shutdown> I<[options]> I<domain-id>
339 Gracefully shuts down a domain. This coordinates with the domain OS
340 to perform graceful shutdown, so there is no guarantee that it will
341 succeed, and may take a variable length of time depending on what
342 services must be shutdown in the domain. The command returns
343 immediately after signally the domain unless that I<-w> flag is used.
345 The behavior of what happens to a domain when it reboots is set by the
346 I<on_shutdown> parameter of the xmdomain.cfg file when the domain was
347 created.
349 B<OPTIONS>
351 =over 4
353 =item B<-a>
355 Shutdown B<all> domains. Often used when doing a complete shutdown of
356 a Xen system.
358 =item B<-w>
360 Wait for the domain to complete shutdown before returning.
362 =back
364 =item B<sysrq> I<domain-id> I<letter>
366 Send a I<Magic System Request> signal to the domain. For more
367 information on available magic sys req operations, see sysrq.txt in
368 your Linux Kernel sources.
370 =item B<unpause> I<domain-id>
372 Moves a domain out of the paused state. This will allow a previously
373 paused domain to now be eligible for scheduling by the Xen hypervisor.
375 =item B<vcpu-set> I<domain-id> I<vcpu-count>
377 Enables the I<vcpu-count> virtual CPUs for the domain in question.
378 Like mem-set, this command can only allocate up to the maximum virtual
379 CPU count configured at boot for the domain.
381 If the I<vcpu-count> is smaller than the current number of active
382 VCPUs, the highest number VCPUs will be hotplug removed. This may be
383 important for pinning purposes.
385 Attempting to set the VCPUs to a number larger than the initially
386 configured VCPU count is an error. Trying to set VCPUs to < 1 will be
387 quietly ignored.
389 =item B<vcpu-list> I<[domain-id]>
391 Lists VCPU information for a specific domain. If no domain is
392 specified, VCPU information for all domains will be provided.
394 =item B<vcpu-pin> I<domain-id> I<vcpu> I<cpus>
396 Pins the the VCPU to only run on the specific CPUs.
398 Normally VCPUs can float between available CPUs whenever Xen deems a
399 different run state is appropriate. Pinning can be used to restrict
400 this, by ensuring certain VCPUs can only run on certain physical
401 CPUs.
403 =back
405 =head1 XEN HOST SUBCOMMANDS
407 =over 4
409 =item B<dmesg> I<[-c]>
411 Reads the Xen message buffer, similar to dmesg on a Linux system. The
412 buffer contains informational, warning, and error messages created
413 during Xen's boot process. If you are having problems with Xen, this
414 is one of the first places to look as part of problem determination.
416 B<OPTIONS>
418 =over 4
420 =item B<-c, --clear>
422 Clears Xen's message buffer.
424 =back
426 =item B<info>
428 Print information about the Xen host in I<name : value> format. When
429 reporting a Xen bug, please provide this information as part of the
430 bug report.
432 Sample xen domain info looks as follows (lines wrapped manually to
433 make the man page more readable):
435 system : Linux
436 host : talon
437 release : 2.6.12.6-xen0
438 version : #1 Mon Nov 14 14:26:26 EST 2005
439 machine : i686
440 nr_cpus : 2
441 nr_nodes : 1
442 sockets_per_node : 2
443 cores_per_socket : 1
444 threads_per_core : 1
445 cpu_mhz : 696
446 hw_caps : 0383fbff:00000000:00000000:00000040
447 memory : 767
448 free_memory : 37
449 xen_major : 3
450 xen_minor : 0
451 xen_extra : -devel
452 xen_caps : xen-3.0-x86_32
453 xen_params : virt_start=0xfc000000
454 xen_changeset : Mon Nov 14 18:13:38 2005 +0100
455 7793:090e44133d40
456 cc_compiler : gcc version 3.4.3 (Mandrakelinux
457 10.2 3.4.3-7mdk)
458 cc_compile_by : sdague
459 cc_compile_domain : (none)
460 cc_compile_date : Mon Nov 14 14:16:48 EST 2005
462 B<FIELDS>
464 =over 4
466 Not all fields will be explained here, but some of the less obvious
467 ones deserve explanation:
469 =item I<hw_caps>
471 A vector showing what hardware capabilities are supported by your
472 processor. This is equivalent to, though more cryptic, the flags
473 field in /proc/cpuinfo on a normal Linux machine.
475 =item I<free_memory>
477 Available memory (in MB) not allocated to Xen, or any other Domains.
479 =item I<xen_caps>
481 The xen version, architecture. Architecture values can be one of:
482 x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
484 =item I<xen_changeset>
486 The xen mercurial changeset id. Very useful for determining exactly
487 what version of code your Xen system was built from.
489 =back
491 =item B<log>
493 Print out the B<xend> log. This log file can be found in
494 /var/log/xend.log.
496 =item B<top>
498 Executes the xentop command, which provides real time monitoring of
499 domains. Xentop is a curses interface, and reasonably self
500 explanatory.
502 =back
504 =head1 SCHEDULER SUBCOMMANDS
506 Xen ships with a number of domain schedulers, which can be set at boot
507 time with the I<sched=> parameter on the Xen command line. By
508 default I<sedf> is used for scheduling.
510 FIXME: we really need a scheduler expert to write up this section.
512 =over 4
514 =item B<sched-bvt> I<mcuadv> I<warpback> I<warpvalue> I<warpl> I<warpu>
516 Performs runtime adjustments to the default parameters for the
517 Borrowed Virtual Time (BVT) scheduler. For full information on the
518 BVT concept, please consult the base paper listed in the B<SEE ALSO>
519 section.
521 Set Borrowed Virtual Time (BVT) scheduler parameters. There are five
522 required parameters, which are given in order below.
524 FIXME: what units are all the BVT params in?
526 B<PARAMETERS>
528 =over 4
530 =item I<mcuadv>
532 The MCU (Minimum Charging Unit) advance determines the proportional
533 share of the CPU that a domain receives. It is set inversely
534 proportionally to a domain's sharing weight.
536 =item I<warpback>
538 The amount of `virtual time' the domain is allowed to warp backwards.
540 =item I<warpvalue>
542 Warp value (FIXME: what does this really mean?)
544 =item I<warpl>
546 The warp limit is the maximum time a domain can run warped for.
548 =item I<warpu>
550 The unwarp requirement is the minimum time a domain must run unwarped
551 for before it can warp again.
553 =back
555 =item B<sched-bvt-ctxallow> I<allow>
557 Sets the BVT scheduler's context switch allowance.
559 The context switch allowance is similar to the ``quantum'' in
560 traditional schedulers. It is the minimum time that a scheduled domain
561 will be allowed to run before being preempted.
563 =item B<sched-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
565 Set Simple EDF (Earliest Deadline First) scheduler parameters. This
566 scheduler provides weighted CPU sharing in an intuitive way and uses
567 realtime-algorithms to ensure time guarantees. For more information
568 see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
570 B<PARAMETERS>
572 =over 4
574 =item I<period>
576 The normal EDF scheduling usage in nanoseconds
578 =item I<slice>
580 The normal EDF scheduling usage in nanoseconds
582 FIXME: these are lame, should explain more.
584 =item I<latency-hint>
586 Scaled period if domain is doing heavy I/O.
588 =item I<extratime>
590 Flag for allowing domain to run in extra time.
592 =item I<weight>
594 Another way of setting cpu slice.
596 =back
598 B<EXAMPLES>
600 I<normal EDF (20ms/5ms):>
602 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
604 I<best-effort domains (i.e. non-realtime):>
606 xm sched-sedf <dom-id> 20000000 0 0 1 0
607  
608 I<normal EDF (20ms/5ms) + share of extra-time:>
609  
610 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
612 I<4 domains with weights 2:3:4:2>
614 xm sched-sedf <d1> 0 0 0 0 2
615   xm sched-sedf <d2> 0 0 0 0 3
616   xm sched-sedf <d3> 0 0 0 0 4
617   xm sched-sedf <d4> 0 0 0 0 2
619 I<1 fully-specified (10ms/3ms) domain, 3 other domains share available
620 rest in 2:7:3 ratio:>
622 xm sched-sedf <d1> 10000000 3000000 0 0 0  
623 xm sched-sedf <d2> 0 0 0 0 2  
624 xm sched-sedf <d3> 0 0 0 0 7
625   xm sched-sedf <d4> 0 0 0 0 3
627 =back
629 =head1 VIRTUAL DEVICE COMMANDS
631 Most virtual devices can be added and removed while guests are
632 running. The effect to the guest OS is much the same as any hotplug
633 event.
635 =head2 BLOCK DEVICES
637 =over 4
639 =item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> I<[bedomain-id]>
641 Create a new virtual block device. This will trigger a hotplug event
642 for the guest.
644 B<OPTIONS>
646 =over 4
648 =item I<domain-id>
650 The domain id of the guest domain that the device will be attached to.
652 =item I<be-dev>
654 The device in the backend domain (usually domain 0) to be exported.
655 This can be specified as a physical partition (phy:sda7) or as a file
656 mounted as loopback (file://path/to/loop.iso).
658 =item I<fe-dev>
660 How the device should be presented to the guest domain. It can be
661 specified as either a symbolic name, such as /dev/hdc, for common
662 devices, or by device id, such as 0x1400 (/dev/hdc device id in hex).
664 =item I<mode>
666 The access mode for the device from the guest domain. Supported modes
667 are I<rw> (read/write) or I<ro> (read-only).
669 =item I<bedomain-id>
671 The back end domain hosting the device. This defaults to domain 0.
673 =back
675 B<EXAMPLES>
677 =over 4
679 =item I<Mount an ISO as a Disk>
681 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso /dev/hdc ro
683 This will mount the dsl iso as /dev/hdc in the guestdomain as a read
684 only device. This will probably not be detected as a cdrom by the
685 guest, but mounting /dev/hdc manually will work.
687 =back
689 =item B<block-detach> I<domain-id> I<devid>
691 Destroy a domain's virtual block device. devid B<must> be the device
692 id given to the device by domain 0. You will need to run I<xm
693 block-list> to determine that number.
695 FIXME: this is currently B<broken>. Even though a block device is
696 removed from domU, it appears to still be allocated in the domain 0.
698 =item B<block-list> I<[-l|--long]> I<domain-id>
700 List virtual block devices for a domain. The returned output is
701 formatted as a list or as an S-Expression if the '--long' option was given.
703 =head2 NETWORK DEVICES
705 =item B<network-attach> I<domain-id> I<[script=scriptname]> I<[ip=ipaddr]>
706 I<[mac=macaddr]> I<[bridge=bridge-name]> I<[backend=bedomain-id]>
708 Creates a new network device in the domain specified by domain-id. It
709 takes the following optional options:
711 B<OPTIONS>
713 =over 4
715 =item I<script=scriptname>
717 Use the specified script name to bring up the network. Defaults to
718 the default setting in xend-config.sxp for I<vif-script>.
720 =item I<ip=ipaddr>
722 Passes the specified IP Address to the adapter on creation.
724 FIXME: this currently appears to be B<broken>. I'm not sure under what
725 circumstances this should actually work.
727 =item I<mac=macaddr>
729 The MAC address that the domain will see on its Ethernet device. If
730 the device is not specified it will be randomly generated with the
731 00:16:3e vendor id prefix.
733 =item I<bridge=bridge-name>
735 The name of the bridge to attach the vif to, in case you have more
736 than one. This defaults to
738 =item I<backend=bedomain-id>
740 The backend domain id. By default this is domain 0.
742 =back
744 =item B<network-detach> I<domain-id> I<devid>
746 Removes the network device from the domain specified by I<domain-id>.
747 I<devid> is the virtual interface device number within the domain
748 (i.e. the 3 in vif22.3).
750 FIXME: this is currently B<broken>. Network devices aren't completely
751 removed from domain 0.
753 =item B<network-list> I<[-l|--long]> I<domain-id>
755 List virtual network interfaces for a domain. The returned output is
756 formatted as a list or as an S-Expression if the '--long' option was given.
758 =head2 VIRTUAL TPM DEVICES
760 =item B<vtpm-list> I<[-l|--long]> I<domain-id>
762 Show the virtual TPM device for a domain. The returned output is
763 formatted as a list or as an S-Expression if the '--long' option was given.
765 =back
767 =head1 VNET COMMANDS
769 The Virtual Network interfaces for Xen.
771 FIXME: This needs a lot more explanation, or it needs to be ripped
772 out entirely.
774 =over 4
776 =item B<vnet-list> I<[-l|--long]>
778 List vnets.
780 =item B<vnet-create> I<config>
782 Create a vnet from a config file.
784 =item B<vnet-delete> I<vnetid>
786 Delete a vnet.
788 =back
790 =head1 ACCESS CONTROL SUBCOMMANDS
792 Access Control in Xen consists of two components: (i) The Access
793 Control Policy (ACP) defines security labels and access rules based on
794 these labels. (ii) The Access Control Module (ACM) makes access control
795 decisions by interpreting the policy when domains require to
796 communicate or to access resources. The Xen access control has
797 sufficient mechanisms in place to enforce the access decisions even
798 against maliciously acting user domains (mandatory access control).
800 Access rights for domains in Xen are determined by the domain security
801 label only and not based on the domain Name or ID. The ACP specifies
802 security labels that can then be assigned to domains and
803 resources. Every domain must be assigned exactly one security label,
804 otherwise access control decisions could become indeterministic. ACPs
805 are distinguished by their name, which is a parameter to most of the
806 subcommands described below. Currently, the ACP specifies two ways to
807 interpret labels:
809 (1) Simple Type Enforcement: Labels are interpreted to decide access
810 of domains to comunication means and virtual or physical
811 resources. Communication between domains as well as access to
812 resources are forbidden by default and can only take place if they are
813 explicitly allowed by the security policy. The proper assignment of
814 labels to domains controls the sharing of information (directly
815 through communication or indirectly through shared resources) between
816 domains. This interpretation allows to control the overt (intended)
817 communication channels in Xen.
819 (2) Chinese Wall: Labels are interpreted to decide which domains can
820 co-exist (be run simultaneously) on the same system. This
821 interpretation allows to prevent direct covert (unintended) channels
822 and mitigates risks caused by imperfect core domain isolation
823 (trade-off between security and other system requirements). For a
824 short introduction to covert channels, please refer to
825 http://www.multicians.org/timing-chn.html.
827 The following subcommands help you to manage security policies in Xen
828 and to assign security labels to domains. To enable access control
829 security in Xen, you must compile Xen with ACM support enabled as
830 described under "Configuring Security" below. There, you will find
831 also examples of each subcommand described here.
833 =item B<makepolicy> I<policy>
835 Compiles the XML source representation of the security I<policy>. It
836 creates a mapping (.map) as well as a binary (.bin) version of the
837 policy. The compiled policy can be loaded into Xen with the
838 B<loadpolicy> subcommand or can be configured to be loaded at boot
839 time with the B<cfgbootpolicy> subcommand.
841 =over 4
843 I<policy> is a dot-separated list of names. The last part is the file
844 name pre-fix for the policy xml file. The preceding name parts are
845 translated into the local path pointing to the policy xml file
846 relative to the global policy root directory
847 (/etc/xen/acm-security/policies). For example,
848 example.chwall_ste.client_v1 denotes the policy file
849 example/chwall_ste/client_v1-security_policy.xml relative to the
850 global policy root directory.
852 =back
854 =item B<loadpolicy> I<policy>
856 Loads the binary representation of the I<policy> into Xen. The binary
857 representation can be created with the B<makepolicy> subcommand.
859 =item B<cfgbootpolicy> I<policy> [I<kernelversion>]
861 Configures I<policy> as the boot policy for Xen. It copies the binary
862 policy representation into the /boot directory and adds a module line
863 specifying the binary policy to the /boot/grub/menu.lst file. If your
864 boot configuration includes multiple Xen boot titles, then use the
865 I<kernelversion> parameter to select the proper title.
867 =item B<dumppolicy>
869 Prints the current security policy state information of Xen.
871 =item B<labels> [I<policy>] [I<type>=dom|res|any]
873 Lists all labels of a I<type> (domain, resource, or both) that are
874 defined in the I<policy>. Unless specified, the default I<policy> is
875 the currently enforced access control policy. The default for I<type>
876 is 'dom'. The labels are arranged in alphabetical order.
878 =item B<addlabel> I<configfile> I<label> [I<policy>]
880 Adds the security label with name I<label> to a domain
881 I<configfile>. Unless specified, the default I<policy> is the
882 currently enforced access control policy. This subcommand also
883 verifies that the I<policy> definition supports the specified I<label>
884 name.
886 B<CONFIGURING SECURITY>
888 =over 4
890 In xen_source_dir/Config.mk set the following parameters:
892 ACM_SECURITY ?= y
893 ACM_DEFAULT_SECURITY_POLICY ?= \
894 ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
896 Then recompile and install xen and the security tools and then reboot:
898 cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
899 cd xen_source_dir/tools/security; make install;
900 reboot into xen
902 =back
904 B<COMPILING A SECURITY POLICY>
906 =over 4
908 This step creates client_v1.map and client_v1.bin files in
909 /etc/xen/acm-security/policies/example/chwall_ste.
911 xm makepolicy example.chwall_ste.client_v1
913 =back
915 B<LOADING A SECURITY POLICY>
917 =over 4
919 This step activates client_v1.bin as new security policy in Xen. You
920 can use the dumppolicy subcommand before and afterwards to see the
921 change in the Xen policy state.
923 xm loadpolicy example.chwall_ste.client_v1
925 =back
927 B<CONFIGURING A BOOT SECURITY POLICY>
929 =over 4
931 This configures the boot loader to load client_v1.bin at boot
932 time. During system start, the ACM configures Xen with this policy and
933 Xen enforces this policy from then on.
935 xm cfgbootpolicy example.chwall_ste.client_v1
937 =back
939 B<LISTING SECURITY LABELS>
941 =over 4
943 This subcommand shows all labels that are defined and which can be
944 attached to domains.
946 xm labels example.chwall_ste.client_v1 type=dom
948 will print for our example policy:
950 dom_BoincClient
951 dom_Fun
952 dom_HomeBanking
953 dom_NetworkDomain
954 dom_StorageDomain
955 dom_SystemManagement
957 =back
959 B<ATTACHING A SECURITY LABEL TO A DOMAIN>
961 =over 4
963 This subcommand attaches a security label to a domain configuration
964 file, here a HomeBanking label. The example policy ensures that this
965 domain does not share information with other non-hombanking user
966 domains (i.e., domains labeled as dom_Fun or dom_Boinc) and that it
967 will not run simultaneously with domains labeled as dom_Fun.
969 We assume that the specified myconfig.xm configuration file actually
970 instantiates a domain that runs workloads related to home-banking,
971 probably just a browser environment for online-banking.
973 xm addlabel myconfig.xm dom_HomeBanking
975 The very simple configuration file might now look as printed
976 below. The I<addlabel> subcommand added the B<access_control> entry at
977 the end of the file, consisting of a label name and the policy that
978 specifies this label name:
980 kernel = "/boot/vmlinuz-2.6.16-xen"
981 ramdisk="/boot/U1_home_banking_ramdisk.img"
982 memory = 164
983 name = "homebanking"
984 vif = [ '' ]
985 dhcp = "dhcp"
986 access_control = ['policy=example.chwall_ste.client_v1,
987 label=dom_HomeBanking']
989 Security labels must be assigned to domain configurations because
990 these labels are essential for making access control decisions as
991 early as during the configuration phase of a newly instantiated
992 domain. Consequently, a security-enabled Xen hypervisor will only
993 start domains that have a security label configured and whose security
994 label is consistent with the currently enforced policy. Otherwise,
995 starting the domain will fail with the error condition "operation not
996 permitted".
998 =back
1000 B<STARTING AND LISTING LABELED DOMAINS>
1002 =over 4
1004 xm create myconfig.xm
1006 xm list --label
1008 Name ID ... Time(s) Label
1009 homebanking 23 ... 4.4 dom_HomeBanking
1010 Domain-0 0 ... 2658.8 dom_SystemManagement
1012 =back
1014 B<POLICY REPRESENTATIONS>
1016 =over 4
1018 We distinguish three representations of the Xen access control policy:
1019 the I<source XML> version, its I<binary> counterpart, and a I<mapping>
1020 representation that enables the tools to deterministically translate
1021 back and forth between label names of the XML policy and label
1022 identifiers of the binary policy. All three versions must be kept
1023 consistent to achieve predictable security guarantees.
1025 The XML version is the version that users are supposed to create or
1026 change, either by manually editing the XML file or by using the Xen
1027 policy generation tool (B<xensec_gen>). After changing the XML file,
1028 run the B<makepolicy> subcommand to ensure that these changes are
1029 reflected in the other versions. Use, for example, the subcommand
1030 B<cfgbootpolicy> to activate the changes during the next system
1031 reboot.
1033 The binary version of the policy is derived from the XML policy by
1034 tokenizing the specified labels and is used inside Xen only. It is
1035 created with the B<makepolicy> subcommand. Essentially, the binary
1036 version is much more compact than the XML version and is easier to
1037 evaluate during access control decisions.
1039 The mapping version of the policy is created during the XML-to-binary
1040 policy translation (B<makepolicy>) and is used by the Xen management
1041 tools to translate between label names used as input to the tools and
1042 their binary identifiers (ssidrefs) used inside Xen.
1044 =back
1046 =head1 EXAMPLES
1048 =head1 SEE ALSO
1050 B<xmdomain.cfg>(5), B<xentop>(1)
1052 BVT scheduling paper: K.J. Duda and D.R. Cheriton. Borrowed Virtual
1053 Time (BVT) scheduling: supporting latency-sensitive threads in a
1054 general purpose scheduler. In proceedings of the 17th ACM SIGOPS
1055 Symposium on Operating Systems principles, volume 33(5) of ACM
1056 Operating Systems Review, pages 261-267
1058 =head1 AUTHOR
1060 Sean Dague <sean at dague dot net>
1061 Daniel Stekloff <dsteklof at us dot ibm dot com>
1062 Reiner Sailer <sailer at us dot ibm dot com>
1064 =head1 BUGS