1xm(1) Xen xm(1)
2
6 xm - Xen management user interface
7
9 xm subcommand [args]
10
12 The xm program is the main interface for managing Xen guest domains.
13 The program can be used to create, pause, and shutdown domains. It can
14 also be used to list current domains, enable or pin VCPUs, and attach
15 or detach virtual block devices.
16 The basic structure of every xm command is almost always:
18 xm subcommand domain-id [OPTIONS]
20 Where subcommand is one of the subcommands listed below, domain-id is
22 the numeric domain id, or the domain name (which will be internally
23 translated to domain id), and OPTIONS are subcommand specific options.
24 There are a few exceptions to this rule in the cases where the subcom‐
25 mand in question acts on all domains, the entire machine, or directly
26 on the Xen hypervisor. Those exceptions will be clear for each of
27 those subcommands.
28
30 All xm operations rely upon the Xen control daemon, aka xend. For any
31 xm commands to run, xend must also be running. For this reason you
32 should start xend as a service when your system first boots using Xen.
33 Most xm commands require root privileges to run due to the communica‐
35 tions channels used to talk to the hypervisor. Running as non root
36 will return an error.
37 Most xm commands act asynchronously, so just because the xm command
39 returned doesn't mean the action is complete. This is important, as
40 many operations on domains, like create and shutdown, can take consid‐
41 erable time (30 seconds or more) to bring the machine into a fully com‐
42 pliant state. If you want to know when one of these actions has fin‐
43 ished you must poll through xm list periodically.
44
46 The following subcommands manipulate domains directly. As stated pre‐
47 viously, most commands take domain-id as the first parameter.
48 console domain-id
50 Attach to domain domain-id's console. If you've set up your
51 domains to have a traditional log in console this will look much
52 like a normal text log in screen.
53 This uses the back end xenconsole service which currently only
55 works for para-virtual domains.
56 The attached console will perform much like a standard serial con‐
58 sole, so running curses based interfaces over the console is not
59 advised. Vi tends to get very odd when using it over this inter‐
60 face.
61 create [-c] configfile [name=value]..
63 The create sub command requires a config file and can optionally
64 take a series of name value pairs that add to or override variables
65 defined in the config file. See xmdomain.cfg for full details of
66 that file format, and possible options used in either the config‐
67 file or name=value combinations.
68 configfile can either be an absolute path to a file, or a relative
70 path to a file located in /etc/xen.
71 Create will return as soon as the domain is started. This does not
73 mean the guest OS in the domain has actually booted, or is avail‐
74 able for input.
75 OPTIONS
77 -c Attache console to the domain as soon as it has started. This
79 is useful for determining issues with crashing domains.
80 EXAMPLES
82 with config file
84 xm create Fedora4
85 This creates a domain with the file /etc/xen/Fedora4, and
87 returns as soon as it is run.
88 without config file
90 xm create /dev/null ramdisk=initrd.img \
91 kernel=/boot/vmlinuz-2.6.12.6-xenU \
92 name=ramdisk nics=0 vcpus=1 \
93 memory=64 root=/dev/ram0
94 This creates the domain without using a config file (more
96 specifically using /dev/null as an empty config file), kernel
97 and ramdisk as specified, setting the name of the domain to
98 "ramdisk", also disabling virtual networking. (This example
99 comes from the xm-test test suite.)
100 destroy domain-id
102 Immediately terminate the domain domain-id. This doesn't give the
103 domain OS any chance to react, and is the equivalent of ripping the
104 power cord out on a physical machine. In most cases you will want
105 to use the shutdown command instead.
106 domid domain-name
108 Converts a domain name to a domain id using xend's internal map‐
109 ping.
110 domname domain-id
112 Converts a domain id to a domain name using xend's internal map‐
113 ping.
114 help [--long]
116 Displays the short help message (i.e. common commands).
117 The --long option prints out the complete set of xm subcommands,
119 grouped by function.
120 list [--long ⎪ --label] [domain-id ...]
122 Prints information about one or more domains. If no domains are
123 specified it prints out information about all domains.
124 An example format for the list is as follows:
126 Name ID Mem(MiB) VCPUs State Time(s)
128 Domain-0 0 98 1 r----- 5068.6
129 Fedora3 164 128 1 r----- 7.6
130 Fedora4 165 128 1 ------ 0.6
131 Mandrake2006 166 128 1 -b---- 3.6
132 Mandrake10.2 167 128 1 ------ 2.5
133 Suse9.2 168 100 1 ------ 1.8
134 Name is the name of the domain. ID the numeric domain id. Mem is
136 the desired amount of memory to allocate to the domain (although it
137 may not be the currently allocated amount). VCPUs is the number of
138 virtual CPUs allocated to the domain. State is the run state (see
139 below). Time is the total run time of the domain as accounted for
140 by Xen.
141 STATES
143 The State field lists 6 states for a Xen domain, and which ones
145 the current domain is in.
146 r - running
148 The domain is currently running on a CPU.
149 b - blocked
151 The domain is blocked, and not running or runnable. This can
152 be caused because the domain is waiting on IO (a traditional
153 wait state) or has gone to sleep because there was nothing else
154 for it to do.
155 p - paused
157 The domain has been paused, usually occurring through the
158 administrator running xm pause. When in a paused state the
159 domain will still consume allocated resources like memory, but
160 will not be eligible for scheduling by the Xen hypervisor.
161 s - shutdown
163 FIXME: Why would you ever see this state?
164 c - crashed
166 The domain has crashed, which is always a violent ending. Usu‐
167 ally this state can only occur if the domain has been config‐
168 ured not to restart on crash. See xmdomain.cfg for more info.
169 d - dying
171 The domain is in process of dying, but hasn't completely shut‐
172 down or crashed.
173 FIXME: Is this right?
175 LONG OUTPUT
177 If --long is specified, the output for xm list is not the table
179 view shown above, but instead is an S-Expression representing
180 all information known about all domains asked for. This is
181 mostly only useful for external programs to parse the data.
182 Note: There is no stable guarantees on the format of this data.
184 Use at your own risk.
185 LABEL OUTPUT
187 If --label is specified, the security labels are added to the
189 output of xm list and the lines are sorted by the labels
190 (ignoring case). The --long option prints the labels by default
191 and cannot be combined with --label. See the ACCESS CONTROL
192 SUBCOMMAND section of this man page for more information about
193 labels.
194 NOTES
196 The Time column is deceptive. Virtual IO (network and block
198 devices) used by domains requires coordination by Domain0,
199 which means that Domain0 is actually charged for much of the
200 time that a DomainU is doing IO. Use of this time value to
201 determine relative utilizations by domains is thus very sus‐
202 pect, as a high IO workload may show as less utilized than a
203 high CPU workload. Consider yourself warned.
204 mem-max domain-id mem
206 Specify the maximum amount of memory the domain is able to use.
207 mem is specified in megabytes.
208 The mem-max value may not correspond to the actual memory used in
210 the domain, as it may balloon down its memory to give more back to
211 the OS.
212 mem-set domain-id mem
214 Set the domain's used memory using the balloon driver. Because
215 this operation requires cooperation from the domain operating sys‐
216 tem, there is no guarantee that it will succeed.
217 Warning: There is no good way to know in advance how small of a
219 mem-set will make a domain unstable and cause it to crash. Be very
220 careful when using this command on running domains.
221 migrate domain-id host [OPTIONS]
223 Migrate a domain to another host machine. Xend must be running on
224 other host machine, it must be running the same version of Xen, it
225 must have the migration TCP port open and accepting connections
226 from the source host, and there must be sufficient resources for
227 the domain to run (memory, disk, etc).
228 Migration is pretty complicated, and has many security implica‐
230 tions. Please read the Xen User's Guide to ensure you understand
231 the ramifications and limitations on migration before attempting it
232 in production.
233 OPTIONS
235 -l, --live
237 Use live migration. This will migrate the domain between hosts
238 without shutting down the domain. See the Xen User's Guide for
239 more information.
240 -r, --resource Mbs
242 Set maximum Mbs allowed for migrating the domain. This ensures
243 that the network link is not saturated with migration traffic
244 while attempting to do other useful work.
245 pause domain-id
247 Pause a domain. When in a paused state the domain will still con‐
248 sume allocated resources such as memory, but will not be eligible
249 for scheduling by the Xen hypervisor.
250 reboot [OPTIONS] domain-id
252 Reboot a domain. This acts just as if the domain had the reboot
253 command run from the console. The command returns as soon as it
254 has executed the reboot action, which may be significantly before
255 the domain actually reboots.
256 The behavior of what happens to a domain when it reboots is set by
258 the on_reboot parameter of the xmdomain.cfg file when the domain
259 was created.
260 OPTIONS
262 -a, --all
264 Reboot all domains.
265 -w, --wait
267 Wait for reboot to complete before returning. This may take a
268 while, as all services in the domain will have to be shut down
269 cleanly.
270 restore state-file
272 Build a domain from an xm save state file. See save for more info.
273 save domain-id state-file
275 Saves a running domain to a state file so that it can be restored
276 later. Once saved, the domain will no longer be running on the
277 system, thus the memory allocated for the domain will be free for
278 other domains to use. xm restore restores from this state file.
279 This is roughly equivalent to doing a hibernate on a running com‐
281 puter, with all the same limitations. Open network connections may
282 be severed upon restore, as TCP timeouts may have expired.
283 shutdown [OPTIONS] domain-id
285 Gracefully shuts down a domain. This coordinates with the domain
286 OS to perform graceful shutdown, so there is no guarantee that it
287 will succeed, and may take a variable length of time depending on
288 what services must be shutdown in the domain. The command returns
289 immediately after signally the domain unless that -w flag is used.
290 The behavior of what happens to a domain when it reboots is set by
292 the on_shutdown parameter of the xmdomain.cfg file when the domain
293 was created.
294 OPTIONS
296 -a Shutdown all domains. Often used when doing a complete shut‐
298 down of a Xen system.
299 -w Wait for the domain to complete shutdown before returning.
301 sysrq domain-id letter
303 Send a Magic System Request signal to the domain. For more infor‐
304 mation on available magic sys req operations, see sysrq.txt in your
305 Linux Kernel sources.
306 unpause domain-id
308 Moves a domain out of the paused state. This will allow a previ‐
309 ously paused domain to now be eligible for scheduling by the Xen
310 hypervisor.
311 vcpu-set domain-id vcpu-count
313 Enables the vcpu-count virtual CPUs for the domain in question.
314 Like mem-set, this command can only allocate up to the maximum vir‐
315 tual CPU count configured at boot for the domain.
316 If the vcpu-count is smaller than the current number of active
318 VCPUs, the highest number VCPUs will be hotplug removed. This may
319 be important for pinning purposes.
320 Attempting to set the VCPUs to a number larger than the initially
322 configured VCPU count is an error. Trying to set VCPUs to < 1 will
323 be quietly ignored.
324 vcpu-list [domain-id]
326 Lists VCPU information for a specific domain. If no domain is
327 specified, VCPU information for all domains will be provided.
328 vcpu-pin domain-id vcpu cpus
330 Pins the the VCPU to only run on the specific CPUs. The keyword
331 all can be used to apply the cpus list to all VCPUs in the domain.
332 Normally VCPUs can float between available CPUs whenever Xen deems
334 a different run state is appropriate. Pinning can be used to
335 restrict this, by ensuring certain VCPUs can only run on certain
336 physical CPUs.
337
339 dmesg [-c]
340 Reads the Xen message buffer, similar to dmesg on a Linux system.
341 The buffer contains informational, warning, and error messages cre‐
342 ated during Xen's boot process. If you are having problems with
343 Xen, this is one of the first places to look as part of problem
344 determination.
345 OPTIONS
347 -c, --clear
349 Clears Xen's message buffer.
350 info
352 Print information about the Xen host in name : value format. When
353 reporting a Xen bug, please provide this information as part of the
354 bug report.
355 Sample output looks as follows (lines wrapped manually to make the
357 man page more readable):
358 host : talon
360 release : 2.6.12.6-xen0
361 version : #1 Mon Nov 14 14:26:26 EST 2005
362 machine : i686
363 nr_cpus : 2
364 nr_nodes : 1
365 sockets_per_node : 2
366 cores_per_socket : 1
367 threads_per_core : 1
368 cpu_mhz : 696
369 hw_caps : 0383fbff:00000000:00000000:00000040
370 total_memory : 767
371 free_memory : 37
372 xen_major : 3
373 xen_minor : 0
374 xen_extra : -devel
375 xen_caps : xen-3.0-x86_32
376 xen_scheduler : credit
377 xen_pagesize : 4096
378 platform_params : virt_start=0xfc000000
379 xen_changeset : Mon Nov 14 18:13:38 2005 +0100
380 7793:090e44133d40
381 cc_compiler : gcc version 3.4.3 (Mandrakelinux
382 10.2 3.4.3-7mdk)
383 cc_compile_by : sdague
384 cc_compile_domain : (none)
385 cc_compile_date : Mon Nov 14 14:16:48 EST 2005
386 xend_config_format : 3
387 FIELDS
389 Not all fields will be explained here, but some of the less
391 obvious ones deserve explanation:
392 hw_caps
394 A vector showing what hardware capabilities are supported by
395 your processor. This is equivalent to, though more cryptic,
396 the flags field in /proc/cpuinfo on a normal Linux machine.
397 free_memory
399 Available memory (in MB) not allocated to Xen, or any other
400 domains.
401 xen_caps
403 The Xen version and architecture. Architecture values can be
404 one of: x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
405 xen_changeset
407 The Xen mercurial changeset id. Very useful for determining
408 exactly what version of code your Xen system was built from.
409 log Print out the xend log. This log file can be found in
411 /var/log/xend.log.
412 top Executes the xentop command, which provides real time monitoring of
414 domains. Xentop is a curses interface, and reasonably self
415 explanatory.
416
418 Xen ships with a number of domain schedulers, which can be set at boot
419 time with the sched= parameter on the Xen command line. By default
420 credit is used for scheduling.
421 FIXME: we really need a scheduler expert to write up this section.
423 sched-credit [ -d domain-id [ -w[=WEIGHT] ⎪ -c[=CAP] ] ]
425 Set credit scheduler parameters. The credit scheduler is a propor‐
426 tional fair share CPU scheduler built from the ground up to be work
427 conserving on SMP hosts.
428 Each domain (including Domain0) is assigned a weight and a cap.
430 PARAMETERS
432 WEIGHT
434 A domain with a weight of 512 will get twice as much CPU as a
435 domain with a weight of 256 on a contended host. Legal weights
436 range from 1 to 65535 and the default is 256.
437 CAP The cap optionally fixes the maximum amount of CPU a domain
439 will be able to consume, even if the host system has idle CPU
440 cycles. The cap is expressed in percentage of one physical CPU:
441 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
442 The default, 0, means there is no upper cap.
443 sched-sedf period slice latency-hint extratime weight
445 Set Simple EDF (Earliest Deadline First) scheduler parameters.
446 This scheduler provides weighted CPU sharing in an intuitive way
447 and uses realtime-algorithms to ensure time guarantees. For more
448 information see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen
449 distribution.
450 PARAMETERS
452 period
454 The normal EDF scheduling usage in nanoseconds
455 slice
457 The normal EDF scheduling usage in nanoseconds
458 FIXME: these are lame, should explain more.
460 latency-hint
462 Scaled period if domain is doing heavy I/O.
463 extratime
465 Flag for allowing domain to run in extra time.
466 weight
468 Another way of setting CPU slice.
469 EXAMPLES
471 normal EDF (20ms/5ms):
473 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
475 best-effort domains (i.e. non-realtime):
477 xm sched-sedf <dom-id> 20000000 0 0 1 0
479 normal EDF (20ms/5ms) + share of extra-time:
481 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
483 4 domains with weights 2:3:4:2
485 xm sched-sedf <d1> 0 0 0 0 2
487 xm sched-sedf <d2> 0 0 0 0 3
488 xm sched-sedf <d3> 0 0 0 0 4
489 xm sched-sedf <d4> 0 0 0 0 2
490 1 fully-specified (10ms/3ms) domain, 3 other domains share avail‐
492 able rest in 2:7:3 ratio:
493 xm sched-sedf <d1> 10000000 3000000 0 0 0
495 xm sched-sedf <d2> 0 0 0 0 2
496 xm sched-sedf <d3> 0 0 0 0 7
497 xm sched-sedf <d4> 0 0 0 0 3
498
500 Most virtual devices can be added and removed while guests are running.
501 The effect to the guest OS is much the same as any hotplug event.
502 BLOCK DEVICES
504 block-attach domain-id be-dev fe-dev mode [bedomain-id]
506 Create a new virtual block device. This will trigger a hotplug
507 event for the guest.
508 OPTIONS
510 domain-id
512 The domain id of the guest domain that the device will be
513 attached to.
514 be-dev
516 The device in the backend domain (usually domain 0) to be
517 exported. This can be specified as a physical partition
518 (phy:sda7) or as a file mounted as loopback
519 (file://path/to/loop.iso).
520 fe-dev
522 How the device should be presented to the guest domain. It can
523 be specified as either a symbolic name, such as /dev/hdc, for
524 common devices, or by device id, such as 0x1400 (/dev/hdc
525 device id in hex).
526 mode
528 The access mode for the device from the guest domain. Sup‐
529 ported modes are w (read/write) or r (read-only).
530 bedomain-id
532 The back end domain hosting the device. This defaults to
533 domain 0.
534 EXAMPLES
536 Mount an ISO as a Disk
538 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso
539 /dev/hdc ro
540 This will mount the dsl ISO as /dev/hdc in the guestdomain as a
542 read only device. This will probably not be detected as a CD-
543 ROM by the guest, but mounting /dev/hdc manually will work.
544 block-detach domain-id devid [--force]
546 Detach a domain's virtual block device. devid may be the symbolic
547 name or the numeric device id given to the device by domain 0. You
548 will need to run xm block-list to determine that number.
549 Detaching the device requires the cooperation of the domain. If
551 the domain fails to release the device (perhaps because the domain
552 is hung or is still using the device), the detach will fail. The
553 --force parameter will forcefully detach the device, but may cause
554 IO errors in the domain.
555 block-list [-l⎪--long] domain-id
557 List virtual block devices for a domain. The returned output is
558 formatted as a list or as an S-Expression if the --long option was
559 given.
560 NETWORK DEVICES
562 network-attach domain-id [script=scriptname] [ip=ipaddr] [mac=macaddr]
564 [bridge=bridge-name] [backend=bedomain-id]
565 Creates a new network device in the domain specified by domain-id.
566 It takes the following optional options:
567 OPTIONS
569 script=scriptname
571 Use the specified script name to bring up the network.
572 Defaults to the default setting in xend-config.sxp for vif-
573 script.
574 ip=ipaddr
576 Passes the specified IP Address to the adapter on creation.
577 FIXME: this currently appears to be broken. I'm not sure under
579 what circumstances this should actually work.
580 mac=macaddr
582 The MAC address that the domain will see on its Ethernet
583 device. If the device is not specified it will be randomly
584 generated with the 00:16:3e vendor id prefix.
585 bridge=bridge-name
587 The name of the bridge to attach the vif to, in case you have
588 more than one. This defaults to xenbr0.
589 backend=bedomain-id
591 The backend domain id. By default this is domain 0.
592 network-detach domain-id devid
594 Removes the network device from the domain specified by domain-id.
595 devid is the virtual interface device number within the domain
596 (i.e. the 3 in vif22.3).
597 FIXME: this is currently broken. Network devices aren't completely
599 removed from domain 0.
600 network-list [-l⎪--long]> domain-id
602 List virtual network interfaces for a domain. The returned output
603 is formatted as a list or as an S-Expression if the --long option
604 was given.
605 VIRTUAL TPM DEVICES
607 vtpm-list [-l⎪--long] domain-id
609 Show the virtual TPM device for a domain. The returned output is
610 formatted as a list or as an S-Expression if the --long option was
611 given.
612
614 The Virtual Network interfaces for Xen.
615 FIXME: This needs a lot more explanation, or it needs to be ripped out
617 entirely.
618 vnet-list [-l⎪--long]
620 List vnets.
621 vnet-create config
623 Create a vnet from a config file.
624 vnet-delete vnetid
626 Delete a vnet.
627
629 Access Control in Xen consists of two components: (i) The Access Con‐
630 trol Policy (ACP) defines security labels and access rules based on
631 these labels. (ii) The Access Control Module (ACM) makes access control
632 decisions by interpreting the policy when domains require to communi‐
633 cate or to access resources. The Xen access control has sufficient
634 mechanisms in place to enforce the access decisions even against mali‐
635 ciously acting user domains (mandatory access control).
636 Access rights for domains in Xen are determined by the domain security
638 label only and not based on the domain Name or ID. The ACP specifies
639 security labels that can then be assigned to domains and resources.
640 Every domain must be assigned exactly one security label, otherwise
641 access control decisions could become indeterministic. ACPs are distin‐
642 guished by their name, which is a parameter to most of the subcommands
643 described below. Currently, the ACP specifies two ways to interpret
644 labels:
645 (1) Simple Type Enforcement: Labels are interpreted to decide access of
647 domains to communication means and virtual or physical resources. Com‐
648 munication between domains as well as access to resources are forbidden
649 by default and can only take place if they are explicitly allowed by
650 the security policy. The proper assignment of labels to domains con‐
651 trols the sharing of information (directly through communication or
652 indirectly through shared resources) between domains. This interpreta‐
653 tion allows to control the overt (intended) communication channels in
654 Xen.
655 (2) Chinese Wall: Labels are interpreted to decide which domains can
657 co-exist (be run simultaneously) on the same system. This interpreta‐
658 tion allows to prevent direct covert (unintended) channels and miti‐
659 gates risks caused by imperfect core domain isolation (trade-off
660 between security and other system requirements). For a short introduc‐
661 tion to covert channels, please refer to http://www.multicians.org/tim‐
662 ing-chn.html.
663 The following subcommands help you to manage security policies in Xen
665 and to assign security labels to domains. To enable access control
666 security in Xen, you must compile Xen with ACM support enabled as
667 described under "Configuring Security" below. There, you will find also
668 examples of each subcommand described here.
669 makepolicy policy
671 Compiles the XML source representation of the security policy. It
672 creates a mapping (.map) as well as a binary (.bin) version of the
673 policy. The compiled policy can be loaded into Xen with the load‐
674 policy subcommand or can be configured to be loaded at boot time
675 with the cfgbootpolicy subcommand.
676 policy is a dot-separated list of names. The last part is the file
678 name pre-fix for the policy XML file. The preceding name parts are
679 translated into the local path pointing to the policy XML file rel‐
680 ative to the global policy root directory (/etc/xen/acm-secu‐
681 rity/policies). For example, example.chwall_ste.client_v1 denotes
682 the policy file example/chwall_ste/client_v1-security_policy.xml
683 relative to the global policy root directory.
684 loadpolicy policy
686 Loads the binary representation of the policy into Xen. The binary
687 representation can be created with the makepolicy subcommand.
688 cfgbootpolicy policy [boot title]
690 Configures policy as the boot policy for Xen. It copies the binary
691 policy representation into the /boot directory and adds a module
692 line specifying the binary policy to the /boot/grub/menu.lst file.
693 If your boot configuration includes multiple Xen boot titles, then
694 use the boot title parameter to specify a unique part of the proper
695 title.
696 dumppolicy
698 Prints the current security policy state information of Xen.
699 labels [policy] [type=dom⎪res⎪any]
701 Lists all labels of a type (domain, resource, or both) that are
702 defined in the policy. Unless specified, the default policy is the
703 currently enforced access control policy. The default for type is
704 'dom'. The labels are arranged in alphabetical order.
705 addlabel label dom configfile [policy]
707 addlabel label res resource [policy]
708 Adds the security label with name label to a domain configfile
709 (dom) or to the global resource label file for the given resource
710 (res). Unless specified, the default policy is the currently
711 enforced access control policy. This subcommand also verifies that
712 the policy definition supports the specified label name.
713 rmlabel dom configfile
715 rmlabel res resource
716 Works the same as the addlabel command (above), except that this
717 command will remove the label from the domain configfile (dom) or
718 the global resource label file (res).
719 getlabel dom configfile
721 getlabel res resource
722 Shows the label for the given configfile or resource
723 resources
725 Lists all resources in the global resource label file. Each
726 resource is listed with its associated label and policy name.
727 dry-run configfile
729 Determines if the specified configfile describes a domain with a
730 valid security configuration for type enforcement. The test shows
731 the policy decision made for each resource label against the domain
732 label as well as the overall decision.
733 CONFIGURING SECURITY
735 In xen_source_dir/Config.mk set the following parameters:
737 ACM_SECURITY ?= y
739 ACM_DEFAULT_SECURITY_POLICY ?= \
740 ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
741 Then recompile and install xen and the security tools and then
743 reboot:
744 cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
746 cd xen_source_dir/tools/security; make install;
747 reboot into Xen
748 COMPILING A SECURITY POLICY
750 This step creates client_v1.map and client_v1.bin files in
752 /etc/xen/acm-security/policies/example/chwall_ste.
753 xm makepolicy example.chwall_ste.client_v1
755 LOADING A SECURITY POLICY
757 This step activates client_v1.bin as new security policy in Xen.
759 You can use the dumppolicy subcommand before and afterwards to see
760 the change in the Xen policy state.
761 xm loadpolicy example.chwall_ste.client_v1
763 CONFIGURING A BOOT SECURITY POLICY
765 This configures the boot loader to load client_v1.bin at boot time.
767 During system start, the ACM configures Xen with this policy and
768 Xen enforces this policy from then on.
769 xm cfgbootpolicy example.chwall_ste.client_v1
771 LISTING SECURITY LABELS
773 This subcommand shows all labels that are defined and which can be
775 attached to domains.
776 xm labels example.chwall_ste.client_v1 type=dom
778 will print for our example policy:
780 dom_BoincClient
782 dom_Fun
783 dom_HomeBanking
784 dom_NetworkDomain
785 dom_StorageDomain
786 dom_SystemManagement
787 ATTACHING A SECURITY LABEL TO A DOMAIN
789 The addlabel subcommand can attach a security label to a domain
791 configuration file, here a HomeBanking label. The example policy
792 ensures that this domain does not share information with other non-
793 homebanking user domains (i.e., domains labeled as dom_Fun or
794 dom_Boinc) and that it will not run simultaneously with domains
795 labeled as dom_Fun.
796 We assume that the specified myconfig.xm configuration file actu‐
798 ally instantiates a domain that runs workloads related to
799 home-banking, probably just a browser environment for online-bank‐
800 ing.
801 xm addlabel dom_HomeBanking dom myconfig.xm
803 The very simple configuration file might now look as printed below.
805 The addlabel subcommand added the access_control entry at the end
806 of the file, consisting of a label name and the policy that speci‐
807 fies this label name:
808 kernel = "/boot/vmlinuz-2.6.16-xen"
810 ramdisk="/boot/U1_home_banking_ramdisk.img"
811 memory = 164
812 name = "homebanking"
813 vif = [ '' ]
814 dhcp = "dhcp"
815 access_control = ['policy=example.chwall_ste.client_v1,
816 label=dom_HomeBanking']
817 Security labels must be assigned to domain configurations because
819 these labels are essential for making access control decisions as
820 early as during the configuration phase of a newly instantiated
821 domain. Consequently, a security-enabled Xen hypervisor will only
822 start domains that have a security label configured and whose secu‐
823 rity label is consistent with the currently enforced policy. Other‐
824 wise, starting the domain will fail with the error condition "oper‐
825 ation not permitted".
826 ATTACHING A SECURITY LABEL TO A RESOURCE
828 The addlabel subcommand can also be used to attach a security label
830 to a resource. Following the home banking example from above, we
831 can label a disk resource (e.g., a physical partition or a file) to
832 make it accessible to the home banking domain. The example policy
833 provides a resource label, res_LogicalDiskPartition1(hda1), that is
834 compatible with the HomeBanking domain label.
835 xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6
837 After labeling this disk resource, it can be attached to the domain
839 by adding a line to the domain configuration file. The line below
840 attaches this disk to the domain at boot time.
841 disk = [ 'phy:hda6,sda2,w' ]
843 Alternatively, the resource can be attached after booting the
845 domain by using the block-attach subcommand.
846 xm block-attach homebanking phy:hda6 sda2 w
848 Note that labeled resources cannot be used when security is turned
850 off. Any attempt to use labeled resources with security turned off
851 will result in a failure with a corresponding error message. The
852 solution is to enable security or, if security is no longer
853 desired, to remove the resource label using the rmlabel subcommand.
854 STARTING AND LISTING LABELED DOMAINS
856 xm create myconfig.xm
858 xm list --label
860 Name ID ... Time(s) Label
862 homebanking 23 ... 4.4 dom_HomeBanking
863 Domain-0 0 ... 2658.8 dom_SystemManagement
864 LISTING LABELED RESOURCES
866 xm resources
868 phy:hda6
870 policy: example.chwall_ste.client_v1
871 label: res_LogicalDiskPartition1(hda1)
872 file:/xen/disk_image/disk.img
873 policy: example.chwall_ste.client_v1
874 label: res_LogicalDiskPartition2(hda2)
875 POLICY REPRESENTATIONS
877 We distinguish three representations of the Xen access control pol‐
879 icy: the source XML version, its binary counterpart, and a mapping
880 representation that enables the tools to deterministically trans‐
881 late back and forth between label names of the XML policy and label
882 identifiers of the binary policy. All three versions must be kept
883 consistent to achieve predictable security guarantees.
884 The XML version is the version that users are supposed to create or
886 change, either by manually editing the XML file or by using the Xen
887 policy generation tool (xensec_gen). After changing the XML file,
888 run the makepolicy subcommand to ensure that these changes are
889 reflected in the other versions. Use, for example, the subcommand
890 cfgbootpolicy to activate the changes during the next system
891 reboot.
892 The binary version of the policy is derived from the XML policy by
894 tokenizing the specified labels and is used inside Xen only. It is
895 created with the makepolicy subcommand. Essentially, the binary
896 version is much more compact than the XML version and is easier to
897 evaluate during access control decisions.
898 The mapping version of the policy is created during the XML-to-
900 binary policy translation (makepolicy) and is used by the Xen man‐
901 agement tools to translate between label names used as input to the
902 tools and their binary identifiers (ssidrefs) used inside Xen.
903
905 xmdomain.cfg(5), xentop(1)
906
908 Sean Dague <sean at dague dot net>
909 Daniel Stekloff <dsteklof at us dot ibm dot com>
910 Reiner Sailer <sailer at us dot ibm dot com>
911
913xen-unstable 2007-11-14 xm(1)