view docs/man/xm.pod.1 @ 11430:0419253c81de

Fix inverted sense of getRequiredAvailableMemory and
getRequiredInitialReservation on x86 HVM.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author Ewan Mellor <ewan@xensource.com>
date Tue Sep 05 16:23:11 2006 +0100 (2006-09-05)
parents 26b673aeff8b
children e76c6d838a44
line source
1 =head1 NAME
3 xm - Xen management user interface
5 =head1 SYNOPSIS
7 xm <subcommand> [args]
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.
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.
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
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- \
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.
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
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
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.
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.
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.
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
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.
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 :
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
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
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-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
516 Set Simple EDF (Earliest Deadline First) scheduler parameters. This
517 scheduler provides weighted CPU sharing in an intuitive way and uses
518 realtime-algorithms to ensure time guarantees. For more information
519 see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
523 =over 4
525 =item I<period>
527 The normal EDF scheduling usage in nanoseconds
529 =item I<slice>
531 The normal EDF scheduling usage in nanoseconds
533 FIXME: these are lame, should explain more.
535 =item I<latency-hint>
537 Scaled period if domain is doing heavy I/O.
539 =item I<extratime>
541 Flag for allowing domain to run in extra time.
543 =item I<weight>
545 Another way of setting cpu slice.
547 =back
551 I<normal EDF (20ms/5ms):>
553 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
555 I<best-effort domains (i.e. non-realtime):>
557 xm sched-sedf <dom-id> 20000000 0 0 1 0
559 I<normal EDF (20ms/5ms) + share of extra-time:>
561 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
563 I<4 domains with weights 2:3:4:2>
565 xm sched-sedf <d1> 0 0 0 0 2
566   xm sched-sedf <d2> 0 0 0 0 3
567   xm sched-sedf <d3> 0 0 0 0 4
568   xm sched-sedf <d4> 0 0 0 0 2
570 I<1 fully-specified (10ms/3ms) domain, 3 other domains share available
571 rest in 2:7:3 ratio:>
573 xm sched-sedf <d1> 10000000 3000000 0 0 0  
574 xm sched-sedf <d2> 0 0 0 0 2  
575 xm sched-sedf <d3> 0 0 0 0 7
576   xm sched-sedf <d4> 0 0 0 0 3
578 =back
582 Most virtual devices can be added and removed while guests are
583 running. The effect to the guest OS is much the same as any hotplug
584 event.
586 =head2 BLOCK DEVICES
588 =over 4
590 =item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> I<[bedomain-id]>
592 Create a new virtual block device. This will trigger a hotplug event
593 for the guest.
597 =over 4
599 =item I<domain-id>
601 The domain id of the guest domain that the device will be attached to.
603 =item I<be-dev>
605 The device in the backend domain (usually domain 0) to be exported.
606 This can be specified as a physical partition (phy:sda7) or as a file
607 mounted as loopback (file://path/to/loop.iso).
609 =item I<fe-dev>
611 How the device should be presented to the guest domain. It can be
612 specified as either a symbolic name, such as /dev/hdc, for common
613 devices, or by device id, such as 0x1400 (/dev/hdc device id in hex).
615 =item I<mode>
617 The access mode for the device from the guest domain. Supported modes
618 are I<rw> (read/write) or I<ro> (read-only).
620 =item I<bedomain-id>
622 The back end domain hosting the device. This defaults to domain 0.
624 =back
628 =over 4
630 =item I<Mount an ISO as a Disk>
632 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso /dev/hdc ro
634 This will mount the dsl iso as /dev/hdc in the guestdomain as a read
635 only device. This will probably not be detected as a cdrom by the
636 guest, but mounting /dev/hdc manually will work.
638 =back
640 =item B<block-detach> I<domain-id> I<devid>
642 Destroy a domain's virtual block device. devid B<must> be the device
643 id given to the device by domain 0. You will need to run I<xm
644 block-list> to determine that number.
646 FIXME: this is currently B<broken>. Even though a block device is
647 removed from domU, it appears to still be allocated in the domain 0.
649 =item B<block-list> I<[-l|--long]> I<domain-id>
651 List virtual block devices for a domain. The returned output is
652 formatted as a list or as an S-Expression if the '--long' option was given.
656 =item B<network-attach> I<domain-id> I<[script=scriptname]> I<[ip=ipaddr]>
657 I<[mac=macaddr]> I<[bridge=bridge-name]> I<[backend=bedomain-id]>
659 Creates a new network device in the domain specified by domain-id. It
660 takes the following optional options:
664 =over 4
666 =item I<script=scriptname>
668 Use the specified script name to bring up the network. Defaults to
669 the default setting in xend-config.sxp for I<vif-script>.
671 =item I<ip=ipaddr>
673 Passes the specified IP Address to the adapter on creation.
675 FIXME: this currently appears to be B<broken>. I'm not sure under what
676 circumstances this should actually work.
678 =item I<mac=macaddr>
680 The MAC address that the domain will see on its Ethernet device. If
681 the device is not specified it will be randomly generated with the
682 00:16:3e vendor id prefix.
684 =item I<bridge=bridge-name>
686 The name of the bridge to attach the vif to, in case you have more
687 than one. This defaults to
689 =item I<backend=bedomain-id>
691 The backend domain id. By default this is domain 0.
693 =back
695 =item B<network-detach> I<domain-id> I<devid>
697 Removes the network device from the domain specified by I<domain-id>.
698 I<devid> is the virtual interface device number within the domain
699 (i.e. the 3 in vif22.3).
701 FIXME: this is currently B<broken>. Network devices aren't completely
702 removed from domain 0.
704 =item B<network-list> I<[-l|--long]> I<domain-id>
706 List virtual network interfaces for a domain. The returned output is
707 formatted as a list or as an S-Expression if the '--long' option was given.
711 =item B<vtpm-list> I<[-l|--long]> I<domain-id>
713 Show the virtual TPM device for a domain. The returned output is
714 formatted as a list or as an S-Expression if the '--long' option was given.
716 =back
718 =head1 VNET COMMANDS
720 The Virtual Network interfaces for Xen.
722 FIXME: This needs a lot more explanation, or it needs to be ripped
723 out entirely.
725 =over 4
727 =item B<vnet-list> I<[-l|--long]>
729 List vnets.
731 =item B<vnet-create> I<config>
733 Create a vnet from a config file.
735 =item B<vnet-delete> I<vnetid>
737 Delete a vnet.
739 =back
743 Access Control in Xen consists of two components: (i) The Access
744 Control Policy (ACP) defines security labels and access rules based on
745 these labels. (ii) The Access Control Module (ACM) makes access control
746 decisions by interpreting the policy when domains require to
747 communicate or to access resources. The Xen access control has
748 sufficient mechanisms in place to enforce the access decisions even
749 against maliciously acting user domains (mandatory access control).
751 Access rights for domains in Xen are determined by the domain security
752 label only and not based on the domain Name or ID. The ACP specifies
753 security labels that can then be assigned to domains and
754 resources. Every domain must be assigned exactly one security label,
755 otherwise access control decisions could become indeterministic. ACPs
756 are distinguished by their name, which is a parameter to most of the
757 subcommands described below. Currently, the ACP specifies two ways to
758 interpret labels:
760 (1) Simple Type Enforcement: Labels are interpreted to decide access
761 of domains to comunication means and virtual or physical
762 resources. Communication between domains as well as access to
763 resources are forbidden by default and can only take place if they are
764 explicitly allowed by the security policy. The proper assignment of
765 labels to domains controls the sharing of information (directly
766 through communication or indirectly through shared resources) between
767 domains. This interpretation allows to control the overt (intended)
768 communication channels in Xen.
770 (2) Chinese Wall: Labels are interpreted to decide which domains can
771 co-exist (be run simultaneously) on the same system. This
772 interpretation allows to prevent direct covert (unintended) channels
773 and mitigates risks caused by imperfect core domain isolation
774 (trade-off between security and other system requirements). For a
775 short introduction to covert channels, please refer to
776 http://www.multicians.org/timing-chn.html.
778 The following subcommands help you to manage security policies in Xen
779 and to assign security labels to domains. To enable access control
780 security in Xen, you must compile Xen with ACM support enabled as
781 described under "Configuring Security" below. There, you will find
782 also examples of each subcommand described here.
784 =item B<makepolicy> I<policy>
786 Compiles the XML source representation of the security I<policy>. It
787 creates a mapping (.map) as well as a binary (.bin) version of the
788 policy. The compiled policy can be loaded into Xen with the
789 B<loadpolicy> subcommand or can be configured to be loaded at boot
790 time with the B<cfgbootpolicy> subcommand.
792 =over 4
794 I<policy> is a dot-separated list of names. The last part is the file
795 name pre-fix for the policy xml file. The preceding name parts are
796 translated into the local path pointing to the policy xml file
797 relative to the global policy root directory
798 (/etc/xen/acm-security/policies). For example,
799 example.chwall_ste.client_v1 denotes the policy file
800 example/chwall_ste/client_v1-security_policy.xml relative to the
801 global policy root directory.
803 =back
805 =item B<loadpolicy> I<policy>
807 Loads the binary representation of the I<policy> into Xen. The binary
808 representation can be created with the B<makepolicy> subcommand.
810 =item B<cfgbootpolicy> I<policy> [I<kernelversion>]
812 Configures I<policy> as the boot policy for Xen. It copies the binary
813 policy representation into the /boot directory and adds a module line
814 specifying the binary policy to the /boot/grub/menu.lst file. If your
815 boot configuration includes multiple Xen boot titles, then use the
816 I<kernelversion> parameter to select the proper title.
818 =item B<dumppolicy>
820 Prints the current security policy state information of Xen.
822 =item B<labels> [I<policy>] [I<type>=dom|res|any]
824 Lists all labels of a I<type> (domain, resource, or both) that are
825 defined in the I<policy>. Unless specified, the default I<policy> is
826 the currently enforced access control policy. The default for I<type>
827 is 'dom'. The labels are arranged in alphabetical order.
829 =item B<addlabel> I<label> dom I<configfile> [I<policy>]
831 =item B<addlabel> I<label> res I<resource> [I<policy>]
833 Adds the security label with name I<label> to a domain
834 I<configfile> (dom) or to the global resource label file for the
835 given I<resource> (res). Unless specified, the default I<policy> is the
836 currently enforced access control policy. This subcommand also
837 verifies that the I<policy> definition supports the specified I<label>
838 name.
840 =item B<rmlabel> dom I<configfile>
842 =item B<rmlabel> res I<resource>
844 Works the same as the I<addlabel> command (above), except that this
845 command will remove the label from the domain I<configfile> (dom) or
846 the global resource label file (res).
848 =item B<getlabel> dom I<configfile>
850 =item B<getlabel> res I<resource>
852 Shows the label for the given I<configfile> or I<resource>
854 =item B<resources>
856 Lists all resources in the global resource label file. Each resource
857 is listed with its associated label and policy name.
859 =item B<dry-run> I<configfile>
861 Determines if the specified I<configfile> describes a domain with a valid
862 security configuration for type enforcement. The test shows the policy
863 decision made for each resource label against the domain label as well as
864 the overall decision.
868 =over 4
870 In xen_source_dir/Config.mk set the following parameters:
876 Then recompile and install xen and the security tools and then reboot:
878 cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
879 cd xen_source_dir/tools/security; make install;
880 reboot into xen
882 =back
886 =over 4
888 This step creates client_v1.map and client_v1.bin files in
889 /etc/xen/acm-security/policies/example/chwall_ste.
891 xm makepolicy example.chwall_ste.client_v1
893 =back
897 =over 4
899 This step activates client_v1.bin as new security policy in Xen. You
900 can use the dumppolicy subcommand before and afterwards to see the
901 change in the Xen policy state.
903 xm loadpolicy example.chwall_ste.client_v1
905 =back
909 =over 4
911 This configures the boot loader to load client_v1.bin at boot
912 time. During system start, the ACM configures Xen with this policy and
913 Xen enforces this policy from then on.
915 xm cfgbootpolicy example.chwall_ste.client_v1
917 =back
921 =over 4
923 This subcommand shows all labels that are defined and which can be
924 attached to domains.
926 xm labels example.chwall_ste.client_v1 type=dom
928 will print for our example policy:
930 dom_BoincClient
931 dom_Fun
932 dom_HomeBanking
933 dom_NetworkDomain
934 dom_StorageDomain
935 dom_SystemManagement
937 =back
941 =over 4
943 The I<addlabel> subcommand can attach a security label to a domain
944 configuration file, here a HomeBanking label. The example policy
945 ensures that this domain does not share information with other
946 non-hombanking user domains (i.e., domains labeled as dom_Fun or
947 dom_Boinc) and that it will not run simultaneously with domains
948 labeled as dom_Fun.
950 We assume that the specified myconfig.xm configuration file actually
951 instantiates a domain that runs workloads related to home-banking,
952 probably just a browser environment for online-banking.
954 xm addlabel dom_HomeBanking dom myconfig.xm
956 The very simple configuration file might now look as printed
957 below. The I<addlabel> subcommand added the B<access_control> entry at
958 the end of the file, consisting of a label name and the policy that
959 specifies this label name:
961 kernel = "/boot/vmlinuz-2.6.16-xen"
962 ramdisk="/boot/U1_home_banking_ramdisk.img"
963 memory = 164
964 name = "homebanking"
965 vif = [ '' ]
966 dhcp = "dhcp"
967 access_control = ['policy=example.chwall_ste.client_v1,
968 label=dom_HomeBanking']
970 Security labels must be assigned to domain configurations because
971 these labels are essential for making access control decisions as
972 early as during the configuration phase of a newly instantiated
973 domain. Consequently, a security-enabled Xen hypervisor will only
974 start domains that have a security label configured and whose security
975 label is consistent with the currently enforced policy. Otherwise,
976 starting the domain will fail with the error condition "operation not
977 permitted".
979 =back
983 =over 4
985 The I<addlabel> subcommand can also be used to attach a security
986 label to a resource. Following the home banking example from above,
987 we can label a disk resource (e.g., a physical partition or a file)
988 to make it accessible to the home banking domain. The example policy
989 provides a resource label, res_LogicalDiskPartition1(hda1), that is
990 compatible with the HomeBanking domain label.
992 xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6
994 After labeling this disk resource, it can be attached to the domain
995 by adding a line to the domain configuration file. The line below
996 attaches this disk to the domain at boot time.
998 disk = [ 'phy:hda6,sda2,w' ]
1000 Alternatively, the resource can be attached after booting the domain
1001 by using the I<block-attach> subcommand.
1003 xm block-attach homebanking phy:hda6 sda2 w
1005 Note that labeled resources cannot be used when security is turned
1006 off. Any attempt to use labeled resources with security turned off
1007 will result in a failure with a corresponding error message. The
1008 solution is to enable security or, if security is no longer desired,
1009 to remove the resource label using the I<rmlabel> subcommand.
1011 =back
1015 =over 4
1017 xm create myconfig.xm
1019 xm list --label
1021 Name ID ... Time(s) Label
1022 homebanking 23 ... 4.4 dom_HomeBanking
1023 Domain-0 0 ... 2658.8 dom_SystemManagement
1025 =back
1029 =over 4
1031 xm resources
1033 phy:hda6
1034 policy: example.chwall_ste.client_v1
1035 label: res_LogicalDiskPartition1(hda1)
1036 file:/xen/disk_image/disk.img
1037 policy: example.chwall_ste.client_v1
1038 label: res_LogicalDiskPartition2(hda2)
1040 =back
1044 =over 4
1046 We distinguish three representations of the Xen access control policy:
1047 the I<source XML> version, its I<binary> counterpart, and a I<mapping>
1048 representation that enables the tools to deterministically translate
1049 back and forth between label names of the XML policy and label
1050 identifiers of the binary policy. All three versions must be kept
1051 consistent to achieve predictable security guarantees.
1053 The XML version is the version that users are supposed to create or
1054 change, either by manually editing the XML file or by using the Xen
1055 policy generation tool (B<xensec_gen>). After changing the XML file,
1056 run the B<makepolicy> subcommand to ensure that these changes are
1057 reflected in the other versions. Use, for example, the subcommand
1058 B<cfgbootpolicy> to activate the changes during the next system
1059 reboot.
1061 The binary version of the policy is derived from the XML policy by
1062 tokenizing the specified labels and is used inside Xen only. It is
1063 created with the B<makepolicy> subcommand. Essentially, the binary
1064 version is much more compact than the XML version and is easier to
1065 evaluate during access control decisions.
1067 The mapping version of the policy is created during the XML-to-binary
1068 policy translation (B<makepolicy>) and is used by the Xen management
1069 tools to translate between label names used as input to the tools and
1070 their binary identifiers (ssidrefs) used inside Xen.
1072 =back
1074 =head1 EXAMPLES
1076 =head1 SEE ALSO
1078 B<xmdomain.cfg>(5), B<xentop>(1)
1080 =head1 AUTHOR
1082 Sean Dague <sean at dague dot net>
1083 Daniel Stekloff <dsteklof at us dot ibm dot com>
1084 Reiner Sailer <sailer at us dot ibm dot com>
1086 =head1 BUGS