direct-io.hg

view docs/man/xm.pod.1 @ 14329:9044a50c50ab

Simple fix to the man page for xm block-attach.

It currently says to use "ro" or "rw" for the mode, when it seems,
empirically, to take "r" or "w" for the mode, respectively. Update
the man page to reflect that.

Signed-off-by: Chris Lalancette <clalance@redhat.com>
author kfraser@localhost.localdomain
date Sat Mar 10 16:59:57 2007 +0000 (2007-03-10)
parents 3dcd2664853a
children d26bdda2854e
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_scheduler : credit
455 xen_pagesize : 4096
456 platform_params : virt_start=0xfc000000
457 xen_changeset : Mon Nov 14 18:13:38 2005 +0100
458 7793:090e44133d40
459 cc_compiler : gcc version 3.4.3 (Mandrakelinux
460 10.2 3.4.3-7mdk)
461 cc_compile_by : sdague
462 cc_compile_domain : (none)
463 cc_compile_date : Mon Nov 14 14:16:48 EST 2005
464 xend_config_format : 3
466 B<FIELDS>
468 =over 4
470 Not all fields will be explained here, but some of the less obvious
471 ones deserve explanation:
473 =item I<hw_caps>
475 A vector showing what hardware capabilities are supported by your
476 processor. This is equivalent to, though more cryptic, the flags
477 field in /proc/cpuinfo on a normal Linux machine.
479 =item I<free_memory>
481 Available memory (in MB) not allocated to Xen, or any other Domains.
483 =item I<xen_caps>
485 The xen version, architecture. Architecture values can be one of:
486 x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
488 =item I<xen_changeset>
490 The xen mercurial changeset id. Very useful for determining exactly
491 what version of code your Xen system was built from.
493 =back
495 =item B<log>
497 Print out the B<xend> log. This log file can be found in
498 /var/log/xend.log.
500 =item B<top>
502 Executes the xentop command, which provides real time monitoring of
503 domains. Xentop is a curses interface, and reasonably self
504 explanatory.
506 =back
508 =head1 SCHEDULER SUBCOMMANDS
510 Xen ships with a number of domain schedulers, which can be set at boot
511 time with the I<sched=> parameter on the Xen command line. By
512 default I<sedf> is used for scheduling.
514 FIXME: we really need a scheduler expert to write up this section.
516 =over 4
518 =item B<sched-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
520 Set Simple EDF (Earliest Deadline First) scheduler parameters. This
521 scheduler provides weighted CPU sharing in an intuitive way and uses
522 realtime-algorithms to ensure time guarantees. For more information
523 see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
525 B<PARAMETERS>
527 =over 4
529 =item I<period>
531 The normal EDF scheduling usage in nanoseconds
533 =item I<slice>
535 The normal EDF scheduling usage in nanoseconds
537 FIXME: these are lame, should explain more.
539 =item I<latency-hint>
541 Scaled period if domain is doing heavy I/O.
543 =item I<extratime>
545 Flag for allowing domain to run in extra time.
547 =item I<weight>
549 Another way of setting cpu slice.
551 =back
553 B<EXAMPLES>
555 I<normal EDF (20ms/5ms):>
557 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
559 I<best-effort domains (i.e. non-realtime):>
561 xm sched-sedf <dom-id> 20000000 0 0 1 0
562  
563 I<normal EDF (20ms/5ms) + share of extra-time:>
564  
565 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
567 I<4 domains with weights 2:3:4:2>
569 xm sched-sedf <d1> 0 0 0 0 2
570   xm sched-sedf <d2> 0 0 0 0 3
571   xm sched-sedf <d3> 0 0 0 0 4
572   xm sched-sedf <d4> 0 0 0 0 2
574 I<1 fully-specified (10ms/3ms) domain, 3 other domains share available
575 rest in 2:7:3 ratio:>
577 xm sched-sedf <d1> 10000000 3000000 0 0 0  
578 xm sched-sedf <d2> 0 0 0 0 2  
579 xm sched-sedf <d3> 0 0 0 0 7
580   xm sched-sedf <d4> 0 0 0 0 3
582 =back
584 =head1 VIRTUAL DEVICE COMMANDS
586 Most virtual devices can be added and removed while guests are
587 running. The effect to the guest OS is much the same as any hotplug
588 event.
590 =head2 BLOCK DEVICES
592 =over 4
594 =item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> I<[bedomain-id]>
596 Create a new virtual block device. This will trigger a hotplug event
597 for the guest.
599 B<OPTIONS>
601 =over 4
603 =item I<domain-id>
605 The domain id of the guest domain that the device will be attached to.
607 =item I<be-dev>
609 The device in the backend domain (usually domain 0) to be exported.
610 This can be specified as a physical partition (phy:sda7) or as a file
611 mounted as loopback (file://path/to/loop.iso).
613 =item I<fe-dev>
615 How the device should be presented to the guest domain. It can be
616 specified as either a symbolic name, such as /dev/hdc, for common
617 devices, or by device id, such as 0x1400 (/dev/hdc device id in hex).
619 =item I<mode>
621 The access mode for the device from the guest domain. Supported modes
622 are I<w> (read/write) or I<r> (read-only).
624 =item I<bedomain-id>
626 The back end domain hosting the device. This defaults to domain 0.
628 =back
630 B<EXAMPLES>
632 =over 4
634 =item I<Mount an ISO as a Disk>
636 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso /dev/hdc ro
638 This will mount the dsl iso as /dev/hdc in the guestdomain as a read
639 only device. This will probably not be detected as a cdrom by the
640 guest, but mounting /dev/hdc manually will work.
642 =back
644 =item B<block-detach> I<domain-id> I<devid>
646 Destroy a domain's virtual block device. devid B<must> be the device
647 id given to the device by domain 0. You will need to run I<xm
648 block-list> to determine that number.
650 FIXME: this is currently B<broken>. Even though a block device is
651 removed from domU, it appears to still be allocated in the domain 0.
653 =item B<block-list> I<[-l|--long]> I<domain-id>
655 List virtual block devices for a domain. The returned output is
656 formatted as a list or as an S-Expression if the '--long' option was given.
658 =head2 NETWORK DEVICES
660 =item B<network-attach> I<domain-id> I<[script=scriptname]> I<[ip=ipaddr]>
661 I<[mac=macaddr]> I<[bridge=bridge-name]> I<[backend=bedomain-id]>
663 Creates a new network device in the domain specified by domain-id. It
664 takes the following optional options:
666 B<OPTIONS>
668 =over 4
670 =item I<script=scriptname>
672 Use the specified script name to bring up the network. Defaults to
673 the default setting in xend-config.sxp for I<vif-script>.
675 =item I<ip=ipaddr>
677 Passes the specified IP Address to the adapter on creation.
679 FIXME: this currently appears to be B<broken>. I'm not sure under what
680 circumstances this should actually work.
682 =item I<mac=macaddr>
684 The MAC address that the domain will see on its Ethernet device. If
685 the device is not specified it will be randomly generated with the
686 00:16:3e vendor id prefix.
688 =item I<bridge=bridge-name>
690 The name of the bridge to attach the vif to, in case you have more
691 than one. This defaults to
693 =item I<backend=bedomain-id>
695 The backend domain id. By default this is domain 0.
697 =back
699 =item B<network-detach> I<domain-id> I<devid>
701 Removes the network device from the domain specified by I<domain-id>.
702 I<devid> is the virtual interface device number within the domain
703 (i.e. the 3 in vif22.3).
705 FIXME: this is currently B<broken>. Network devices aren't completely
706 removed from domain 0.
708 =item B<network-list> I<[-l|--long]> I<domain-id>
710 List virtual network interfaces for a domain. The returned output is
711 formatted as a list or as an S-Expression if the '--long' option was given.
713 =head2 VIRTUAL TPM DEVICES
715 =item B<vtpm-list> I<[-l|--long]> I<domain-id>
717 Show the virtual TPM device for a domain. The returned output is
718 formatted as a list or as an S-Expression if the '--long' option was given.
720 =back
722 =head1 VNET COMMANDS
724 The Virtual Network interfaces for Xen.
726 FIXME: This needs a lot more explanation, or it needs to be ripped
727 out entirely.
729 =over 4
731 =item B<vnet-list> I<[-l|--long]>
733 List vnets.
735 =item B<vnet-create> I<config>
737 Create a vnet from a config file.
739 =item B<vnet-delete> I<vnetid>
741 Delete a vnet.
743 =back
745 =head1 ACCESS CONTROL SUBCOMMANDS
747 Access Control in Xen consists of two components: (i) The Access
748 Control Policy (ACP) defines security labels and access rules based on
749 these labels. (ii) The Access Control Module (ACM) makes access control
750 decisions by interpreting the policy when domains require to
751 communicate or to access resources. The Xen access control has
752 sufficient mechanisms in place to enforce the access decisions even
753 against maliciously acting user domains (mandatory access control).
755 Access rights for domains in Xen are determined by the domain security
756 label only and not based on the domain Name or ID. The ACP specifies
757 security labels that can then be assigned to domains and
758 resources. Every domain must be assigned exactly one security label,
759 otherwise access control decisions could become indeterministic. ACPs
760 are distinguished by their name, which is a parameter to most of the
761 subcommands described below. Currently, the ACP specifies two ways to
762 interpret labels:
764 (1) Simple Type Enforcement: Labels are interpreted to decide access
765 of domains to comunication means and virtual or physical
766 resources. Communication between domains as well as access to
767 resources are forbidden by default and can only take place if they are
768 explicitly allowed by the security policy. The proper assignment of
769 labels to domains controls the sharing of information (directly
770 through communication or indirectly through shared resources) between
771 domains. This interpretation allows to control the overt (intended)
772 communication channels in Xen.
774 (2) Chinese Wall: Labels are interpreted to decide which domains can
775 co-exist (be run simultaneously) on the same system. This
776 interpretation allows to prevent direct covert (unintended) channels
777 and mitigates risks caused by imperfect core domain isolation
778 (trade-off between security and other system requirements). For a
779 short introduction to covert channels, please refer to
780 http://www.multicians.org/timing-chn.html.
782 The following subcommands help you to manage security policies in Xen
783 and to assign security labels to domains. To enable access control
784 security in Xen, you must compile Xen with ACM support enabled as
785 described under "Configuring Security" below. There, you will find
786 also examples of each subcommand described here.
788 =item B<makepolicy> I<policy>
790 Compiles the XML source representation of the security I<policy>. It
791 creates a mapping (.map) as well as a binary (.bin) version of the
792 policy. The compiled policy can be loaded into Xen with the
793 B<loadpolicy> subcommand or can be configured to be loaded at boot
794 time with the B<cfgbootpolicy> subcommand.
796 =over 4
798 I<policy> is a dot-separated list of names. The last part is the file
799 name pre-fix for the policy xml file. The preceding name parts are
800 translated into the local path pointing to the policy xml file
801 relative to the global policy root directory
802 (/etc/xen/acm-security/policies). For example,
803 example.chwall_ste.client_v1 denotes the policy file
804 example/chwall_ste/client_v1-security_policy.xml relative to the
805 global policy root directory.
807 =back
809 =item B<loadpolicy> I<policy>
811 Loads the binary representation of the I<policy> into Xen. The binary
812 representation can be created with the B<makepolicy> subcommand.
814 =item B<cfgbootpolicy> I<policy> [I<boot title>]
816 Configures I<policy> as the boot policy for Xen. It copies the binary
817 policy representation into the /boot directory and adds a module line
818 specifying the binary policy to the /boot/grub/menu.lst file. If your
819 boot configuration includes multiple Xen boot titles, then use the
820 I<boot title> parameter to specify a unique part of the proper title.
822 =item B<dumppolicy>
824 Prints the current security policy state information of Xen.
826 =item B<labels> [I<policy>] [I<type>=dom|res|any]
828 Lists all labels of a I<type> (domain, resource, or both) that are
829 defined in the I<policy>. Unless specified, the default I<policy> is
830 the currently enforced access control policy. The default for I<type>
831 is 'dom'. The labels are arranged in alphabetical order.
833 =item B<addlabel> I<label> dom I<configfile> [I<policy>]
835 =item B<addlabel> I<label> res I<resource> [I<policy>]
837 Adds the security label with name I<label> to a domain
838 I<configfile> (dom) or to the global resource label file for the
839 given I<resource> (res). Unless specified, the default I<policy> is the
840 currently enforced access control policy. This subcommand also
841 verifies that the I<policy> definition supports the specified I<label>
842 name.
844 =item B<rmlabel> dom I<configfile>
846 =item B<rmlabel> res I<resource>
848 Works the same as the I<addlabel> command (above), except that this
849 command will remove the label from the domain I<configfile> (dom) or
850 the global resource label file (res).
852 =item B<getlabel> dom I<configfile>
854 =item B<getlabel> res I<resource>
856 Shows the label for the given I<configfile> or I<resource>
858 =item B<resources>
860 Lists all resources in the global resource label file. Each resource
861 is listed with its associated label and policy name.
863 =item B<dry-run> I<configfile>
865 Determines if the specified I<configfile> describes a domain with a valid
866 security configuration for type enforcement. The test shows the policy
867 decision made for each resource label against the domain label as well as
868 the overall decision.
870 B<CONFIGURING SECURITY>
872 =over 4
874 In xen_source_dir/Config.mk set the following parameters:
876 ACM_SECURITY ?= y
877 ACM_DEFAULT_SECURITY_POLICY ?= \
878 ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
880 Then recompile and install xen and the security tools and then reboot:
882 cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
883 cd xen_source_dir/tools/security; make install;
884 reboot into xen
886 =back
888 B<COMPILING A SECURITY POLICY>
890 =over 4
892 This step creates client_v1.map and client_v1.bin files in
893 /etc/xen/acm-security/policies/example/chwall_ste.
895 xm makepolicy example.chwall_ste.client_v1
897 =back
899 B<LOADING A SECURITY POLICY>
901 =over 4
903 This step activates client_v1.bin as new security policy in Xen. You
904 can use the dumppolicy subcommand before and afterwards to see the
905 change in the Xen policy state.
907 xm loadpolicy example.chwall_ste.client_v1
909 =back
911 B<CONFIGURING A BOOT SECURITY POLICY>
913 =over 4
915 This configures the boot loader to load client_v1.bin at boot
916 time. During system start, the ACM configures Xen with this policy and
917 Xen enforces this policy from then on.
919 xm cfgbootpolicy example.chwall_ste.client_v1
921 =back
923 B<LISTING SECURITY LABELS>
925 =over 4
927 This subcommand shows all labels that are defined and which can be
928 attached to domains.
930 xm labels example.chwall_ste.client_v1 type=dom
932 will print for our example policy:
934 dom_BoincClient
935 dom_Fun
936 dom_HomeBanking
937 dom_NetworkDomain
938 dom_StorageDomain
939 dom_SystemManagement
941 =back
943 B<ATTACHING A SECURITY LABEL TO A DOMAIN>
945 =over 4
947 The I<addlabel> subcommand can attach a security label to a domain
948 configuration file, here a HomeBanking label. The example policy
949 ensures that this domain does not share information with other
950 non-hombanking user domains (i.e., domains labeled as dom_Fun or
951 dom_Boinc) and that it will not run simultaneously with domains
952 labeled as dom_Fun.
954 We assume that the specified myconfig.xm configuration file actually
955 instantiates a domain that runs workloads related to home-banking,
956 probably just a browser environment for online-banking.
958 xm addlabel dom_HomeBanking dom myconfig.xm
960 The very simple configuration file might now look as printed
961 below. The I<addlabel> subcommand added the B<access_control> entry at
962 the end of the file, consisting of a label name and the policy that
963 specifies this label name:
965 kernel = "/boot/vmlinuz-2.6.16-xen"
966 ramdisk="/boot/U1_home_banking_ramdisk.img"
967 memory = 164
968 name = "homebanking"
969 vif = [ '' ]
970 dhcp = "dhcp"
971 access_control = ['policy=example.chwall_ste.client_v1,
972 label=dom_HomeBanking']
974 Security labels must be assigned to domain configurations because
975 these labels are essential for making access control decisions as
976 early as during the configuration phase of a newly instantiated
977 domain. Consequently, a security-enabled Xen hypervisor will only
978 start domains that have a security label configured and whose security
979 label is consistent with the currently enforced policy. Otherwise,
980 starting the domain will fail with the error condition "operation not
981 permitted".
983 =back
985 B<ATTACHING A SECURITY LABEL TO A RESOURCE>
987 =over 4
989 The I<addlabel> subcommand can also be used to attach a security
990 label to a resource. Following the home banking example from above,
991 we can label a disk resource (e.g., a physical partition or a file)
992 to make it accessible to the home banking domain. The example policy
993 provides a resource label, res_LogicalDiskPartition1(hda1), that is
994 compatible with the HomeBanking domain label.
996 xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6
998 After labeling this disk resource, it can be attached to the domain
999 by adding a line to the domain configuration file. The line below
1000 attaches this disk to the domain at boot time.
1002 disk = [ 'phy:hda6,sda2,w' ]
1004 Alternatively, the resource can be attached after booting the domain
1005 by using the I<block-attach> subcommand.
1007 xm block-attach homebanking phy:hda6 sda2 w
1009 Note that labeled resources cannot be used when security is turned
1010 off. Any attempt to use labeled resources with security turned off
1011 will result in a failure with a corresponding error message. The
1012 solution is to enable security or, if security is no longer desired,
1013 to remove the resource label using the I<rmlabel> subcommand.
1015 =back
1017 B<STARTING AND LISTING LABELED DOMAINS>
1019 =over 4
1021 xm create myconfig.xm
1023 xm list --label
1025 Name ID ... Time(s) Label
1026 homebanking 23 ... 4.4 dom_HomeBanking
1027 Domain-0 0 ... 2658.8 dom_SystemManagement
1029 =back
1031 B<LISTING LABELED RESOURCES>
1033 =over 4
1035 xm resources
1037 phy:hda6
1038 policy: example.chwall_ste.client_v1
1039 label: res_LogicalDiskPartition1(hda1)
1040 file:/xen/disk_image/disk.img
1041 policy: example.chwall_ste.client_v1
1042 label: res_LogicalDiskPartition2(hda2)
1044 =back
1046 B<POLICY REPRESENTATIONS>
1048 =over 4
1050 We distinguish three representations of the Xen access control policy:
1051 the I<source XML> version, its I<binary> counterpart, and a I<mapping>
1052 representation that enables the tools to deterministically translate
1053 back and forth between label names of the XML policy and label
1054 identifiers of the binary policy. All three versions must be kept
1055 consistent to achieve predictable security guarantees.
1057 The XML version is the version that users are supposed to create or
1058 change, either by manually editing the XML file or by using the Xen
1059 policy generation tool (B<xensec_gen>). After changing the XML file,
1060 run the B<makepolicy> subcommand to ensure that these changes are
1061 reflected in the other versions. Use, for example, the subcommand
1062 B<cfgbootpolicy> to activate the changes during the next system
1063 reboot.
1065 The binary version of the policy is derived from the XML policy by
1066 tokenizing the specified labels and is used inside Xen only. It is
1067 created with the B<makepolicy> subcommand. Essentially, the binary
1068 version is much more compact than the XML version and is easier to
1069 evaluate during access control decisions.
1071 The mapping version of the policy is created during the XML-to-binary
1072 policy translation (B<makepolicy>) and is used by the Xen management
1073 tools to translate between label names used as input to the tools and
1074 their binary identifiers (ssidrefs) used inside Xen.
1076 =back
1078 =head1 EXAMPLES
1080 =head1 SEE ALSO
1082 B<xmdomain.cfg>(5), B<xentop>(1)
1084 =head1 AUTHOR
1086 Sean Dague <sean at dague dot net>
1087 Daniel Stekloff <dsteklof at us dot ibm dot com>
1088 Reiner Sailer <sailer at us dot ibm dot com>
1090 =head1 BUGS