ia64/xen-unstable

view docs/man/xm.pod.1 @ 13297:ee395551208d

Enable compatibility mode operation for HYPERVISOR_physdev_op and
HYPERVISOR_event_channel_op.

Signed-off-by: Jan Beulich <jbeulich@novell.com>
author Emmanuel Ackaouy <ack@xensource.com>
date Fri Jan 05 17:34:32 2007 +0000 (2007-01-05)
parents 328606e0705f
children 3dcd2664853a
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. The keyword
397 I<all> can be used to apply the I<cpus> list to all VCPUs in the
398 domain.
400 Normally VCPUs can float between available CPUs whenever Xen deems a
401 different run state is appropriate. Pinning can be used to restrict
402 this, by ensuring certain VCPUs can only run on certain physical
403 CPUs.
405 =back
407 =head1 XEN HOST SUBCOMMANDS
409 =over 4
411 =item B<dmesg> I<[-c]>
413 Reads the Xen message buffer, similar to dmesg on a Linux system. The
414 buffer contains informational, warning, and error messages created
415 during Xen's boot process. If you are having problems with Xen, this
416 is one of the first places to look as part of problem determination.
418 B<OPTIONS>
420 =over 4
422 =item B<-c, --clear>
424 Clears Xen's message buffer.
426 =back
428 =item B<info>
430 Print information about the Xen host in I<name : value> format. When
431 reporting a Xen bug, please provide this information as part of the
432 bug report.
434 Sample xen domain info looks as follows (lines wrapped manually to
435 make the man page more readable):
437 host : talon
438 release : 2.6.12.6-xen0
439 version : #1 Mon Nov 14 14:26:26 EST 2005
440 machine : i686
441 nr_cpus : 2
442 nr_nodes : 1
443 sockets_per_node : 2
444 cores_per_socket : 1
445 threads_per_core : 1
446 cpu_mhz : 696
447 hw_caps : 0383fbff:00000000:00000000:00000040
448 total_memory : 767
449 free_memory : 37
450 xen_major : 3
451 xen_minor : 0
452 xen_extra : -devel
453 xen_caps : xen-3.0-x86_32
454 xen_pagesize : 4096
455 platform_params : virt_start=0xfc000000
456 xen_changeset : Mon Nov 14 18:13:38 2005 +0100
457 7793:090e44133d40
458 cc_compiler : gcc version 3.4.3 (Mandrakelinux
459 10.2 3.4.3-7mdk)
460 cc_compile_by : sdague
461 cc_compile_domain : (none)
462 cc_compile_date : Mon Nov 14 14:16:48 EST 2005
463 xend_config_format : 2
465 B<FIELDS>
467 =over 4
469 Not all fields will be explained here, but some of the less obvious
470 ones deserve explanation:
472 =item I<hw_caps>
474 A vector showing what hardware capabilities are supported by your
475 processor. This is equivalent to, though more cryptic, the flags
476 field in /proc/cpuinfo on a normal Linux machine.
478 =item I<free_memory>
480 Available memory (in MB) not allocated to Xen, or any other Domains.
482 =item I<xen_caps>
484 The xen version, architecture. Architecture values can be one of:
485 x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
487 =item I<xen_changeset>
489 The xen mercurial changeset id. Very useful for determining exactly
490 what version of code your Xen system was built from.
492 =back
494 =item B<log>
496 Print out the B<xend> log. This log file can be found in
497 /var/log/xend.log.
499 =item B<top>
501 Executes the xentop command, which provides real time monitoring of
502 domains. Xentop is a curses interface, and reasonably self
503 explanatory.
505 =back
507 =head1 SCHEDULER SUBCOMMANDS
509 Xen ships with a number of domain schedulers, which can be set at boot
510 time with the I<sched=> parameter on the Xen command line. By
511 default I<sedf> is used for scheduling.
513 FIXME: we really need a scheduler expert to write up this section.
515 =over 4
517 =item B<sched-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
519 Set Simple EDF (Earliest Deadline First) scheduler parameters. This
520 scheduler provides weighted CPU sharing in an intuitive way and uses
521 realtime-algorithms to ensure time guarantees. For more information
522 see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
524 B<PARAMETERS>
526 =over 4
528 =item I<period>
530 The normal EDF scheduling usage in nanoseconds
532 =item I<slice>
534 The normal EDF scheduling usage in nanoseconds
536 FIXME: these are lame, should explain more.
538 =item I<latency-hint>
540 Scaled period if domain is doing heavy I/O.
542 =item I<extratime>
544 Flag for allowing domain to run in extra time.
546 =item I<weight>
548 Another way of setting cpu slice.
550 =back
552 B<EXAMPLES>
554 I<normal EDF (20ms/5ms):>
556 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
558 I<best-effort domains (i.e. non-realtime):>
560 xm sched-sedf <dom-id> 20000000 0 0 1 0
561  
562 I<normal EDF (20ms/5ms) + share of extra-time:>
563  
564 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
566 I<4 domains with weights 2:3:4:2>
568 xm sched-sedf <d1> 0 0 0 0 2
569   xm sched-sedf <d2> 0 0 0 0 3
570   xm sched-sedf <d3> 0 0 0 0 4
571   xm sched-sedf <d4> 0 0 0 0 2
573 I<1 fully-specified (10ms/3ms) domain, 3 other domains share available
574 rest in 2:7:3 ratio:>
576 xm sched-sedf <d1> 10000000 3000000 0 0 0  
577 xm sched-sedf <d2> 0 0 0 0 2  
578 xm sched-sedf <d3> 0 0 0 0 7
579   xm sched-sedf <d4> 0 0 0 0 3
581 =back
583 =head1 VIRTUAL DEVICE COMMANDS
585 Most virtual devices can be added and removed while guests are
586 running. The effect to the guest OS is much the same as any hotplug
587 event.
589 =head2 BLOCK DEVICES
591 =over 4
593 =item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> I<[bedomain-id]>
595 Create a new virtual block device. This will trigger a hotplug event
596 for the guest.
598 B<OPTIONS>
600 =over 4
602 =item I<domain-id>
604 The domain id of the guest domain that the device will be attached to.
606 =item I<be-dev>
608 The device in the backend domain (usually domain 0) to be exported.
609 This can be specified as a physical partition (phy:sda7) or as a file
610 mounted as loopback (file://path/to/loop.iso).
612 =item I<fe-dev>
614 How the device should be presented to the guest domain. It can be
615 specified as either a symbolic name, such as /dev/hdc, for common
616 devices, or by device id, such as 0x1400 (/dev/hdc device id in hex).
618 =item I<mode>
620 The access mode for the device from the guest domain. Supported modes
621 are I<rw> (read/write) or I<ro> (read-only).
623 =item I<bedomain-id>
625 The back end domain hosting the device. This defaults to domain 0.
627 =back
629 B<EXAMPLES>
631 =over 4
633 =item I<Mount an ISO as a Disk>
635 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso /dev/hdc ro
637 This will mount the dsl iso as /dev/hdc in the guestdomain as a read
638 only device. This will probably not be detected as a cdrom by the
639 guest, but mounting /dev/hdc manually will work.
641 =back
643 =item B<block-detach> I<domain-id> I<devid>
645 Destroy a domain's virtual block device. devid B<must> be the device
646 id given to the device by domain 0. You will need to run I<xm
647 block-list> to determine that number.
649 FIXME: this is currently B<broken>. Even though a block device is
650 removed from domU, it appears to still be allocated in the domain 0.
652 =item B<block-list> I<[-l|--long]> I<domain-id>
654 List virtual block devices for a domain. The returned output is
655 formatted as a list or as an S-Expression if the '--long' option was given.
657 =head2 NETWORK DEVICES
659 =item B<network-attach> I<domain-id> I<[script=scriptname]> I<[ip=ipaddr]>
660 I<[mac=macaddr]> I<[bridge=bridge-name]> I<[backend=bedomain-id]>
662 Creates a new network device in the domain specified by domain-id. It
663 takes the following optional options:
665 B<OPTIONS>
667 =over 4
669 =item I<script=scriptname>
671 Use the specified script name to bring up the network. Defaults to
672 the default setting in xend-config.sxp for I<vif-script>.
674 =item I<ip=ipaddr>
676 Passes the specified IP Address to the adapter on creation.
678 FIXME: this currently appears to be B<broken>. I'm not sure under what
679 circumstances this should actually work.
681 =item I<mac=macaddr>
683 The MAC address that the domain will see on its Ethernet device. If
684 the device is not specified it will be randomly generated with the
685 00:16:3e vendor id prefix.
687 =item I<bridge=bridge-name>
689 The name of the bridge to attach the vif to, in case you have more
690 than one. This defaults to
692 =item I<backend=bedomain-id>
694 The backend domain id. By default this is domain 0.
696 =back
698 =item B<network-detach> I<domain-id> I<devid>
700 Removes the network device from the domain specified by I<domain-id>.
701 I<devid> is the virtual interface device number within the domain
702 (i.e. the 3 in vif22.3).
704 FIXME: this is currently B<broken>. Network devices aren't completely
705 removed from domain 0.
707 =item B<network-list> I<[-l|--long]> I<domain-id>
709 List virtual network interfaces for a domain. The returned output is
710 formatted as a list or as an S-Expression if the '--long' option was given.
712 =head2 VIRTUAL TPM DEVICES
714 =item B<vtpm-list> I<[-l|--long]> I<domain-id>
716 Show the virtual TPM device for a domain. The returned output is
717 formatted as a list or as an S-Expression if the '--long' option was given.
719 =back
721 =head1 VNET COMMANDS
723 The Virtual Network interfaces for Xen.
725 FIXME: This needs a lot more explanation, or it needs to be ripped
726 out entirely.
728 =over 4
730 =item B<vnet-list> I<[-l|--long]>
732 List vnets.
734 =item B<vnet-create> I<config>
736 Create a vnet from a config file.
738 =item B<vnet-delete> I<vnetid>
740 Delete a vnet.
742 =back
744 =head1 ACCESS CONTROL SUBCOMMANDS
746 Access Control in Xen consists of two components: (i) The Access
747 Control Policy (ACP) defines security labels and access rules based on
748 these labels. (ii) The Access Control Module (ACM) makes access control
749 decisions by interpreting the policy when domains require to
750 communicate or to access resources. The Xen access control has
751 sufficient mechanisms in place to enforce the access decisions even
752 against maliciously acting user domains (mandatory access control).
754 Access rights for domains in Xen are determined by the domain security
755 label only and not based on the domain Name or ID. The ACP specifies
756 security labels that can then be assigned to domains and
757 resources. Every domain must be assigned exactly one security label,
758 otherwise access control decisions could become indeterministic. ACPs
759 are distinguished by their name, which is a parameter to most of the
760 subcommands described below. Currently, the ACP specifies two ways to
761 interpret labels:
763 (1) Simple Type Enforcement: Labels are interpreted to decide access
764 of domains to comunication means and virtual or physical
765 resources. Communication between domains as well as access to
766 resources are forbidden by default and can only take place if they are
767 explicitly allowed by the security policy. The proper assignment of
768 labels to domains controls the sharing of information (directly
769 through communication or indirectly through shared resources) between
770 domains. This interpretation allows to control the overt (intended)
771 communication channels in Xen.
773 (2) Chinese Wall: Labels are interpreted to decide which domains can
774 co-exist (be run simultaneously) on the same system. This
775 interpretation allows to prevent direct covert (unintended) channels
776 and mitigates risks caused by imperfect core domain isolation
777 (trade-off between security and other system requirements). For a
778 short introduction to covert channels, please refer to
779 http://www.multicians.org/timing-chn.html.
781 The following subcommands help you to manage security policies in Xen
782 and to assign security labels to domains. To enable access control
783 security in Xen, you must compile Xen with ACM support enabled as
784 described under "Configuring Security" below. There, you will find
785 also examples of each subcommand described here.
787 =item B<makepolicy> I<policy>
789 Compiles the XML source representation of the security I<policy>. It
790 creates a mapping (.map) as well as a binary (.bin) version of the
791 policy. The compiled policy can be loaded into Xen with the
792 B<loadpolicy> subcommand or can be configured to be loaded at boot
793 time with the B<cfgbootpolicy> subcommand.
795 =over 4
797 I<policy> is a dot-separated list of names. The last part is the file
798 name pre-fix for the policy xml file. The preceding name parts are
799 translated into the local path pointing to the policy xml file
800 relative to the global policy root directory
801 (/etc/xen/acm-security/policies). For example,
802 example.chwall_ste.client_v1 denotes the policy file
803 example/chwall_ste/client_v1-security_policy.xml relative to the
804 global policy root directory.
806 =back
808 =item B<loadpolicy> I<policy>
810 Loads the binary representation of the I<policy> into Xen. The binary
811 representation can be created with the B<makepolicy> subcommand.
813 =item B<cfgbootpolicy> I<policy> [I<boot title>]
815 Configures I<policy> as the boot policy for Xen. It copies the binary
816 policy representation into the /boot directory and adds a module line
817 specifying the binary policy to the /boot/grub/menu.lst file. If your
818 boot configuration includes multiple Xen boot titles, then use the
819 I<boot title> parameter to specify a unique part of the proper title.
821 =item B<dumppolicy>
823 Prints the current security policy state information of Xen.
825 =item B<labels> [I<policy>] [I<type>=dom|res|any]
827 Lists all labels of a I<type> (domain, resource, or both) that are
828 defined in the I<policy>. Unless specified, the default I<policy> is
829 the currently enforced access control policy. The default for I<type>
830 is 'dom'. The labels are arranged in alphabetical order.
832 =item B<addlabel> I<label> dom I<configfile> [I<policy>]
834 =item B<addlabel> I<label> res I<resource> [I<policy>]
836 Adds the security label with name I<label> to a domain
837 I<configfile> (dom) or to the global resource label file for the
838 given I<resource> (res). Unless specified, the default I<policy> is the
839 currently enforced access control policy. This subcommand also
840 verifies that the I<policy> definition supports the specified I<label>
841 name.
843 =item B<rmlabel> dom I<configfile>
845 =item B<rmlabel> res I<resource>
847 Works the same as the I<addlabel> command (above), except that this
848 command will remove the label from the domain I<configfile> (dom) or
849 the global resource label file (res).
851 =item B<getlabel> dom I<configfile>
853 =item B<getlabel> res I<resource>
855 Shows the label for the given I<configfile> or I<resource>
857 =item B<resources>
859 Lists all resources in the global resource label file. Each resource
860 is listed with its associated label and policy name.
862 =item B<dry-run> I<configfile>
864 Determines if the specified I<configfile> describes a domain with a valid
865 security configuration for type enforcement. The test shows the policy
866 decision made for each resource label against the domain label as well as
867 the overall decision.
869 B<CONFIGURING SECURITY>
871 =over 4
873 In xen_source_dir/Config.mk set the following parameters:
875 ACM_SECURITY ?= y
876 ACM_DEFAULT_SECURITY_POLICY ?= \
877 ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
879 Then recompile and install xen and the security tools and then reboot:
881 cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
882 cd xen_source_dir/tools/security; make install;
883 reboot into xen
885 =back
887 B<COMPILING A SECURITY POLICY>
889 =over 4
891 This step creates client_v1.map and client_v1.bin files in
892 /etc/xen/acm-security/policies/example/chwall_ste.
894 xm makepolicy example.chwall_ste.client_v1
896 =back
898 B<LOADING A SECURITY POLICY>
900 =over 4
902 This step activates client_v1.bin as new security policy in Xen. You
903 can use the dumppolicy subcommand before and afterwards to see the
904 change in the Xen policy state.
906 xm loadpolicy example.chwall_ste.client_v1
908 =back
910 B<CONFIGURING A BOOT SECURITY POLICY>
912 =over 4
914 This configures the boot loader to load client_v1.bin at boot
915 time. During system start, the ACM configures Xen with this policy and
916 Xen enforces this policy from then on.
918 xm cfgbootpolicy example.chwall_ste.client_v1
920 =back
922 B<LISTING SECURITY LABELS>
924 =over 4
926 This subcommand shows all labels that are defined and which can be
927 attached to domains.
929 xm labels example.chwall_ste.client_v1 type=dom
931 will print for our example policy:
933 dom_BoincClient
934 dom_Fun
935 dom_HomeBanking
936 dom_NetworkDomain
937 dom_StorageDomain
938 dom_SystemManagement
940 =back
942 B<ATTACHING A SECURITY LABEL TO A DOMAIN>
944 =over 4
946 The I<addlabel> subcommand can attach a security label to a domain
947 configuration file, here a HomeBanking label. The example policy
948 ensures that this domain does not share information with other
949 non-hombanking user domains (i.e., domains labeled as dom_Fun or
950 dom_Boinc) and that it will not run simultaneously with domains
951 labeled as dom_Fun.
953 We assume that the specified myconfig.xm configuration file actually
954 instantiates a domain that runs workloads related to home-banking,
955 probably just a browser environment for online-banking.
957 xm addlabel dom_HomeBanking dom myconfig.xm
959 The very simple configuration file might now look as printed
960 below. The I<addlabel> subcommand added the B<access_control> entry at
961 the end of the file, consisting of a label name and the policy that
962 specifies this label name:
964 kernel = "/boot/vmlinuz-2.6.16-xen"
965 ramdisk="/boot/U1_home_banking_ramdisk.img"
966 memory = 164
967 name = "homebanking"
968 vif = [ '' ]
969 dhcp = "dhcp"
970 access_control = ['policy=example.chwall_ste.client_v1,
971 label=dom_HomeBanking']
973 Security labels must be assigned to domain configurations because
974 these labels are essential for making access control decisions as
975 early as during the configuration phase of a newly instantiated
976 domain. Consequently, a security-enabled Xen hypervisor will only
977 start domains that have a security label configured and whose security
978 label is consistent with the currently enforced policy. Otherwise,
979 starting the domain will fail with the error condition "operation not
980 permitted".
982 =back
984 B<ATTACHING A SECURITY LABEL TO A RESOURCE>
986 =over 4
988 The I<addlabel> subcommand can also be used to attach a security
989 label to a resource. Following the home banking example from above,
990 we can label a disk resource (e.g., a physical partition or a file)
991 to make it accessible to the home banking domain. The example policy
992 provides a resource label, res_LogicalDiskPartition1(hda1), that is
993 compatible with the HomeBanking domain label.
995 xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6
997 After labeling this disk resource, it can be attached to the domain
998 by adding a line to the domain configuration file. The line below
999 attaches this disk to the domain at boot time.
1001 disk = [ 'phy:hda6,sda2,w' ]
1003 Alternatively, the resource can be attached after booting the domain
1004 by using the I<block-attach> subcommand.
1006 xm block-attach homebanking phy:hda6 sda2 w
1008 Note that labeled resources cannot be used when security is turned
1009 off. Any attempt to use labeled resources with security turned off
1010 will result in a failure with a corresponding error message. The
1011 solution is to enable security or, if security is no longer desired,
1012 to remove the resource label using the I<rmlabel> subcommand.
1014 =back
1016 B<STARTING AND LISTING LABELED DOMAINS>
1018 =over 4
1020 xm create myconfig.xm
1022 xm list --label
1024 Name ID ... Time(s) Label
1025 homebanking 23 ... 4.4 dom_HomeBanking
1026 Domain-0 0 ... 2658.8 dom_SystemManagement
1028 =back
1030 B<LISTING LABELED RESOURCES>
1032 =over 4
1034 xm resources
1036 phy:hda6
1037 policy: example.chwall_ste.client_v1
1038 label: res_LogicalDiskPartition1(hda1)
1039 file:/xen/disk_image/disk.img
1040 policy: example.chwall_ste.client_v1
1041 label: res_LogicalDiskPartition2(hda2)
1043 =back
1045 B<POLICY REPRESENTATIONS>
1047 =over 4
1049 We distinguish three representations of the Xen access control policy:
1050 the I<source XML> version, its I<binary> counterpart, and a I<mapping>
1051 representation that enables the tools to deterministically translate
1052 back and forth between label names of the XML policy and label
1053 identifiers of the binary policy. All three versions must be kept
1054 consistent to achieve predictable security guarantees.
1056 The XML version is the version that users are supposed to create or
1057 change, either by manually editing the XML file or by using the Xen
1058 policy generation tool (B<xensec_gen>). After changing the XML file,
1059 run the B<makepolicy> subcommand to ensure that these changes are
1060 reflected in the other versions. Use, for example, the subcommand
1061 B<cfgbootpolicy> to activate the changes during the next system
1062 reboot.
1064 The binary version of the policy is derived from the XML policy by
1065 tokenizing the specified labels and is used inside Xen only. It is
1066 created with the B<makepolicy> subcommand. Essentially, the binary
1067 version is much more compact than the XML version and is easier to
1068 evaluate during access control decisions.
1070 The mapping version of the policy is created during the XML-to-binary
1071 policy translation (B<makepolicy>) and is used by the Xen management
1072 tools to translate between label names used as input to the tools and
1073 their binary identifiers (ssidrefs) used inside Xen.
1075 =back
1077 =head1 EXAMPLES
1079 =head1 SEE ALSO
1081 B<xmdomain.cfg>(5), B<xentop>(1)
1083 =head1 AUTHOR
1085 Sean Dague <sean at dague dot net>
1086 Daniel Stekloff <dsteklof at us dot ibm dot com>
1087 Reiner Sailer <sailer at us dot ibm dot com>
1089 =head1 BUGS