view docs/man/xm.pod.1 @ 11431:e76c6d838a44

This patch intends for updating "man xm" about xm info description.
For example item:system is removed from xm info.

Signed-off-by: shaocyou <shaocyou@jp.fujitsu.com>
author Ewan Mellor <ewan@xensource.com>
date Tue Sep 05 16:48:21 2006 +0100 (2006-09-05)
parents 26b673aeff8b
children 184884cfaa0b
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 host : talon
436 release :
437 version : #1 Mon Nov 14 14:26:26 EST 2005
438 machine : i686
439 nr_cpus : 2
440 nr_nodes : 1
441 sockets_per_node : 2
442 cores_per_socket : 1
443 threads_per_core : 1
444 cpu_mhz : 696
445 hw_caps : 0383fbff:00000000:00000000:00000040
446 total_memory : 767
447 free_memory : 37
448 xen_major : 3
449 xen_minor : 0
450 xen_extra : -devel
451 xen_caps : xen-3.0-x86_32
452 xen_pagesize : 4096
453 platform_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
461 xend_config_format : 2
465 =over 4
467 Not all fields will be explained here, but some of the less obvious
468 ones deserve explanation:
470 =item I<hw_caps>
472 A vector showing what hardware capabilities are supported by your
473 processor. This is equivalent to, though more cryptic, the flags
474 field in /proc/cpuinfo on a normal Linux machine.
476 =item I<free_memory>
478 Available memory (in MB) not allocated to Xen, or any other Domains.
480 =item I<xen_caps>
482 The xen version, architecture. Architecture values can be one of:
483 x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
485 =item I<xen_changeset>
487 The xen mercurial changeset id. Very useful for determining exactly
488 what version of code your Xen system was built from.
490 =back
492 =item B<log>
494 Print out the B<xend> log. This log file can be found in
495 /var/log/xend.log.
497 =item B<top>
499 Executes the xentop command, which provides real time monitoring of
500 domains. Xentop is a curses interface, and reasonably self
501 explanatory.
503 =back
507 Xen ships with a number of domain schedulers, which can be set at boot
508 time with the I<sched=> parameter on the Xen command line. By
509 default I<sedf> is used for scheduling.
511 FIXME: we really need a scheduler expert to write up this section.
513 =over 4
515 =item B<sched-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
517 Set Simple EDF (Earliest Deadline First) scheduler parameters. This
518 scheduler provides weighted CPU sharing in an intuitive way and uses
519 realtime-algorithms to ensure time guarantees. For more information
520 see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
524 =over 4
526 =item I<period>
528 The normal EDF scheduling usage in nanoseconds
530 =item I<slice>
532 The normal EDF scheduling usage in nanoseconds
534 FIXME: these are lame, should explain more.
536 =item I<latency-hint>
538 Scaled period if domain is doing heavy I/O.
540 =item I<extratime>
542 Flag for allowing domain to run in extra time.
544 =item I<weight>
546 Another way of setting cpu slice.
548 =back
552 I<normal EDF (20ms/5ms):>
554 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
556 I<best-effort domains (i.e. non-realtime):>
558 xm sched-sedf <dom-id> 20000000 0 0 1 0
560 I<normal EDF (20ms/5ms) + share of extra-time:>
562 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
564 I<4 domains with weights 2:3:4:2>
566 xm sched-sedf <d1> 0 0 0 0 2
567   xm sched-sedf <d2> 0 0 0 0 3
568   xm sched-sedf <d3> 0 0 0 0 4
569   xm sched-sedf <d4> 0 0 0 0 2
571 I<1 fully-specified (10ms/3ms) domain, 3 other domains share available
572 rest in 2:7:3 ratio:>
574 xm sched-sedf <d1> 10000000 3000000 0 0 0  
575 xm sched-sedf <d2> 0 0 0 0 2  
576 xm sched-sedf <d3> 0 0 0 0 7
577   xm sched-sedf <d4> 0 0 0 0 3
579 =back
583 Most virtual devices can be added and removed while guests are
584 running. The effect to the guest OS is much the same as any hotplug
585 event.
587 =head2 BLOCK DEVICES
589 =over 4
591 =item B<block-attach> I<domain-id> I<be-dev> I<fe-dev> I<mode> I<[bedomain-id]>
593 Create a new virtual block device. This will trigger a hotplug event
594 for the guest.
598 =over 4
600 =item I<domain-id>
602 The domain id of the guest domain that the device will be attached to.
604 =item I<be-dev>
606 The device in the backend domain (usually domain 0) to be exported.
607 This can be specified as a physical partition (phy:sda7) or as a file
608 mounted as loopback (file://path/to/loop.iso).
610 =item I<fe-dev>
612 How the device should be presented to the guest domain. It can be
613 specified as either a symbolic name, such as /dev/hdc, for common
614 devices, or by device id, such as 0x1400 (/dev/hdc device id in hex).
616 =item I<mode>
618 The access mode for the device from the guest domain. Supported modes
619 are I<rw> (read/write) or I<ro> (read-only).
621 =item I<bedomain-id>
623 The back end domain hosting the device. This defaults to domain 0.
625 =back
629 =over 4
631 =item I<Mount an ISO as a Disk>
633 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso /dev/hdc ro
635 This will mount the dsl iso as /dev/hdc in the guestdomain as a read
636 only device. This will probably not be detected as a cdrom by the
637 guest, but mounting /dev/hdc manually will work.
639 =back
641 =item B<block-detach> I<domain-id> I<devid>
643 Destroy a domain's virtual block device. devid B<must> be the device
644 id given to the device by domain 0. You will need to run I<xm
645 block-list> to determine that number.
647 FIXME: this is currently B<broken>. Even though a block device is
648 removed from domU, it appears to still be allocated in the domain 0.
650 =item B<block-list> I<[-l|--long]> I<domain-id>
652 List virtual block devices for a domain. The returned output is
653 formatted as a list or as an S-Expression if the '--long' option was given.
657 =item B<network-attach> I<domain-id> I<[script=scriptname]> I<[ip=ipaddr]>
658 I<[mac=macaddr]> I<[bridge=bridge-name]> I<[backend=bedomain-id]>
660 Creates a new network device in the domain specified by domain-id. It
661 takes the following optional options:
665 =over 4
667 =item I<script=scriptname>
669 Use the specified script name to bring up the network. Defaults to
670 the default setting in xend-config.sxp for I<vif-script>.
672 =item I<ip=ipaddr>
674 Passes the specified IP Address to the adapter on creation.
676 FIXME: this currently appears to be B<broken>. I'm not sure under what
677 circumstances this should actually work.
679 =item I<mac=macaddr>
681 The MAC address that the domain will see on its Ethernet device. If
682 the device is not specified it will be randomly generated with the
683 00:16:3e vendor id prefix.
685 =item I<bridge=bridge-name>
687 The name of the bridge to attach the vif to, in case you have more
688 than one. This defaults to
690 =item I<backend=bedomain-id>
692 The backend domain id. By default this is domain 0.
694 =back
696 =item B<network-detach> I<domain-id> I<devid>
698 Removes the network device from the domain specified by I<domain-id>.
699 I<devid> is the virtual interface device number within the domain
700 (i.e. the 3 in vif22.3).
702 FIXME: this is currently B<broken>. Network devices aren't completely
703 removed from domain 0.
705 =item B<network-list> I<[-l|--long]> I<domain-id>
707 List virtual network interfaces for a domain. The returned output is
708 formatted as a list or as an S-Expression if the '--long' option was given.
712 =item B<vtpm-list> I<[-l|--long]> I<domain-id>
714 Show the virtual TPM device for a domain. The returned output is
715 formatted as a list or as an S-Expression if the '--long' option was given.
717 =back
719 =head1 VNET COMMANDS
721 The Virtual Network interfaces for Xen.
723 FIXME: This needs a lot more explanation, or it needs to be ripped
724 out entirely.
726 =over 4
728 =item B<vnet-list> I<[-l|--long]>
730 List vnets.
732 =item B<vnet-create> I<config>
734 Create a vnet from a config file.
736 =item B<vnet-delete> I<vnetid>
738 Delete a vnet.
740 =back
744 Access Control in Xen consists of two components: (i) The Access
745 Control Policy (ACP) defines security labels and access rules based on
746 these labels. (ii) The Access Control Module (ACM) makes access control
747 decisions by interpreting the policy when domains require to
748 communicate or to access resources. The Xen access control has
749 sufficient mechanisms in place to enforce the access decisions even
750 against maliciously acting user domains (mandatory access control).
752 Access rights for domains in Xen are determined by the domain security
753 label only and not based on the domain Name or ID. The ACP specifies
754 security labels that can then be assigned to domains and
755 resources. Every domain must be assigned exactly one security label,
756 otherwise access control decisions could become indeterministic. ACPs
757 are distinguished by their name, which is a parameter to most of the
758 subcommands described below. Currently, the ACP specifies two ways to
759 interpret labels:
761 (1) Simple Type Enforcement: Labels are interpreted to decide access
762 of domains to comunication means and virtual or physical
763 resources. Communication between domains as well as access to
764 resources are forbidden by default and can only take place if they are
765 explicitly allowed by the security policy. The proper assignment of
766 labels to domains controls the sharing of information (directly
767 through communication or indirectly through shared resources) between
768 domains. This interpretation allows to control the overt (intended)
769 communication channels in Xen.
771 (2) Chinese Wall: Labels are interpreted to decide which domains can
772 co-exist (be run simultaneously) on the same system. This
773 interpretation allows to prevent direct covert (unintended) channels
774 and mitigates risks caused by imperfect core domain isolation
775 (trade-off between security and other system requirements). For a
776 short introduction to covert channels, please refer to
777 http://www.multicians.org/timing-chn.html.
779 The following subcommands help you to manage security policies in Xen
780 and to assign security labels to domains. To enable access control
781 security in Xen, you must compile Xen with ACM support enabled as
782 described under "Configuring Security" below. There, you will find
783 also examples of each subcommand described here.
785 =item B<makepolicy> I<policy>
787 Compiles the XML source representation of the security I<policy>. It
788 creates a mapping (.map) as well as a binary (.bin) version of the
789 policy. The compiled policy can be loaded into Xen with the
790 B<loadpolicy> subcommand or can be configured to be loaded at boot
791 time with the B<cfgbootpolicy> subcommand.
793 =over 4
795 I<policy> is a dot-separated list of names. The last part is the file
796 name pre-fix for the policy xml file. The preceding name parts are
797 translated into the local path pointing to the policy xml file
798 relative to the global policy root directory
799 (/etc/xen/acm-security/policies). For example,
800 example.chwall_ste.client_v1 denotes the policy file
801 example/chwall_ste/client_v1-security_policy.xml relative to the
802 global policy root directory.
804 =back
806 =item B<loadpolicy> I<policy>
808 Loads the binary representation of the I<policy> into Xen. The binary
809 representation can be created with the B<makepolicy> subcommand.
811 =item B<cfgbootpolicy> I<policy> [I<kernelversion>]
813 Configures I<policy> as the boot policy for Xen. It copies the binary
814 policy representation into the /boot directory and adds a module line
815 specifying the binary policy to the /boot/grub/menu.lst file. If your
816 boot configuration includes multiple Xen boot titles, then use the
817 I<kernelversion> parameter to select the proper title.
819 =item B<dumppolicy>
821 Prints the current security policy state information of Xen.
823 =item B<labels> [I<policy>] [I<type>=dom|res|any]
825 Lists all labels of a I<type> (domain, resource, or both) that are
826 defined in the I<policy>. Unless specified, the default I<policy> is
827 the currently enforced access control policy. The default for I<type>
828 is 'dom'. The labels are arranged in alphabetical order.
830 =item B<addlabel> I<label> dom I<configfile> [I<policy>]
832 =item B<addlabel> I<label> res I<resource> [I<policy>]
834 Adds the security label with name I<label> to a domain
835 I<configfile> (dom) or to the global resource label file for the
836 given I<resource> (res). Unless specified, the default I<policy> is the
837 currently enforced access control policy. This subcommand also
838 verifies that the I<policy> definition supports the specified I<label>
839 name.
841 =item B<rmlabel> dom I<configfile>
843 =item B<rmlabel> res I<resource>
845 Works the same as the I<addlabel> command (above), except that this
846 command will remove the label from the domain I<configfile> (dom) or
847 the global resource label file (res).
849 =item B<getlabel> dom I<configfile>
851 =item B<getlabel> res I<resource>
853 Shows the label for the given I<configfile> or I<resource>
855 =item B<resources>
857 Lists all resources in the global resource label file. Each resource
858 is listed with its associated label and policy name.
860 =item B<dry-run> I<configfile>
862 Determines if the specified I<configfile> describes a domain with a valid
863 security configuration for type enforcement. The test shows the policy
864 decision made for each resource label against the domain label as well as
865 the overall decision.
869 =over 4
871 In xen_source_dir/Config.mk set the following parameters:
877 Then recompile and install xen and the security tools and then reboot:
879 cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
880 cd xen_source_dir/tools/security; make install;
881 reboot into xen
883 =back
887 =over 4
889 This step creates client_v1.map and client_v1.bin files in
890 /etc/xen/acm-security/policies/example/chwall_ste.
892 xm makepolicy example.chwall_ste.client_v1
894 =back
898 =over 4
900 This step activates client_v1.bin as new security policy in Xen. You
901 can use the dumppolicy subcommand before and afterwards to see the
902 change in the Xen policy state.
904 xm loadpolicy example.chwall_ste.client_v1
906 =back
910 =over 4
912 This configures the boot loader to load client_v1.bin at boot
913 time. During system start, the ACM configures Xen with this policy and
914 Xen enforces this policy from then on.
916 xm cfgbootpolicy example.chwall_ste.client_v1
918 =back
922 =over 4
924 This subcommand shows all labels that are defined and which can be
925 attached to domains.
927 xm labels example.chwall_ste.client_v1 type=dom
929 will print for our example policy:
931 dom_BoincClient
932 dom_Fun
933 dom_HomeBanking
934 dom_NetworkDomain
935 dom_StorageDomain
936 dom_SystemManagement
938 =back
942 =over 4
944 The I<addlabel> subcommand can attach a security label to a domain
945 configuration file, here a HomeBanking label. The example policy
946 ensures that this domain does not share information with other
947 non-hombanking user domains (i.e., domains labeled as dom_Fun or
948 dom_Boinc) and that it will not run simultaneously with domains
949 labeled as dom_Fun.
951 We assume that the specified myconfig.xm configuration file actually
952 instantiates a domain that runs workloads related to home-banking,
953 probably just a browser environment for online-banking.
955 xm addlabel dom_HomeBanking dom myconfig.xm
957 The very simple configuration file might now look as printed
958 below. The I<addlabel> subcommand added the B<access_control> entry at
959 the end of the file, consisting of a label name and the policy that
960 specifies this label name:
962 kernel = "/boot/vmlinuz-2.6.16-xen"
963 ramdisk="/boot/U1_home_banking_ramdisk.img"
964 memory = 164
965 name = "homebanking"
966 vif = [ '' ]
967 dhcp = "dhcp"
968 access_control = ['policy=example.chwall_ste.client_v1,
969 label=dom_HomeBanking']
971 Security labels must be assigned to domain configurations because
972 these labels are essential for making access control decisions as
973 early as during the configuration phase of a newly instantiated
974 domain. Consequently, a security-enabled Xen hypervisor will only
975 start domains that have a security label configured and whose security
976 label is consistent with the currently enforced policy. Otherwise,
977 starting the domain will fail with the error condition "operation not
978 permitted".
980 =back
984 =over 4
986 The I<addlabel> subcommand can also be used to attach a security
987 label to a resource. Following the home banking example from above,
988 we can label a disk resource (e.g., a physical partition or a file)
989 to make it accessible to the home banking domain. The example policy
990 provides a resource label, res_LogicalDiskPartition1(hda1), that is
991 compatible with the HomeBanking domain label.
993 xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6
995 After labeling this disk resource, it can be attached to the domain
996 by adding a line to the domain configuration file. The line below
997 attaches this disk to the domain at boot time.
999 disk = [ 'phy:hda6,sda2,w' ]
1001 Alternatively, the resource can be attached after booting the domain
1002 by using the I<block-attach> subcommand.
1004 xm block-attach homebanking phy:hda6 sda2 w
1006 Note that labeled resources cannot be used when security is turned
1007 off. Any attempt to use labeled resources with security turned off
1008 will result in a failure with a corresponding error message. The
1009 solution is to enable security or, if security is no longer desired,
1010 to remove the resource label using the I<rmlabel> subcommand.
1012 =back
1016 =over 4
1018 xm create myconfig.xm
1020 xm list --label
1022 Name ID ... Time(s) Label
1023 homebanking 23 ... 4.4 dom_HomeBanking
1024 Domain-0 0 ... 2658.8 dom_SystemManagement
1026 =back
1030 =over 4
1032 xm resources
1034 phy:hda6
1035 policy: example.chwall_ste.client_v1
1036 label: res_LogicalDiskPartition1(hda1)
1037 file:/xen/disk_image/disk.img
1038 policy: example.chwall_ste.client_v1
1039 label: res_LogicalDiskPartition2(hda2)
1041 =back
1045 =over 4
1047 We distinguish three representations of the Xen access control policy:
1048 the I<source XML> version, its I<binary> counterpart, and a I<mapping>
1049 representation that enables the tools to deterministically translate
1050 back and forth between label names of the XML policy and label
1051 identifiers of the binary policy. All three versions must be kept
1052 consistent to achieve predictable security guarantees.
1054 The XML version is the version that users are supposed to create or
1055 change, either by manually editing the XML file or by using the Xen
1056 policy generation tool (B<xensec_gen>). After changing the XML file,
1057 run the B<makepolicy> subcommand to ensure that these changes are
1058 reflected in the other versions. Use, for example, the subcommand
1059 B<cfgbootpolicy> to activate the changes during the next system
1060 reboot.
1062 The binary version of the policy is derived from the XML policy by
1063 tokenizing the specified labels and is used inside Xen only. It is
1064 created with the B<makepolicy> subcommand. Essentially, the binary
1065 version is much more compact than the XML version and is easier to
1066 evaluate during access control decisions.
1068 The mapping version of the policy is created during the XML-to-binary
1069 policy translation (B<makepolicy>) and is used by the Xen management
1070 tools to translate between label names used as input to the tools and
1071 their binary identifiers (ssidrefs) used inside Xen.
1073 =back
1075 =head1 EXAMPLES
1077 =head1 SEE ALSO
1079 B<xmdomain.cfg>(5), B<xentop>(1)
1081 =head1 AUTHOR
1083 Sean Dague <sean at dague dot net>
1084 Daniel Stekloff <dsteklof at us dot ibm dot com>
1085 Reiner Sailer <sailer at us dot ibm dot com>
1087 =head1 BUGS