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
25 subcommand in question acts on all domains, the entire machine, or
26 directly on the Xen hypervisor. Those exceptions will be clear for
27 each of 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
35 communications channels used to talk to the hypervisor. Running as non
36 root 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
41 considerable time (30 seconds or more) to bring the machine into a
42 fully compliant state. If you want to know when one of these actions
43 has finished you must poll through xm list periodically.
44
46 The following subcommands manipulate domains directly. As stated
47 previously, 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
58 console, so running curses based interfaces over the console is not
59 advised. Vi tends to get very odd when using it over this
60 interface.
61 Use the key combination Ctrl+] to detach the domain console.
63 create configfile [OPTIONS] [vars]..
65 The create subcommand requires a config file and can optionally
66 take a series of vars that add to or override variables defined in
67 the config file. See xmdomain.cfg for full details of that file
68 format, and possible options used in either the configfile or for
69 vars.
70 configfile can either be an absolute path to a file, or a relative
72 path to a file located in /etc/xen.
73 Create will return as soon as the domain is started. This does not
75 mean the guest OS in the domain has actually booted, or is
76 available for input.
77 OPTIONS
79 --help_config
81 Print the available configuration variables vars. These
82 variables may be used on the command line or in the
83 configuration file configfile.
84 -q, --quiet
86 No console output.
87 --path
89 Search path for configuration scripts. The value of PATH is a
90 colon-separated directory list.
91 -f=FILE, --defconfig=FILE
93 Use the given Python configuration script. The configuration
94 script is loaded after arguments have been processed. Each
95 command-line option sets a configuration variable named after
96 its long option name, and these variables are placed in the
97 environment of the script before it is loaded. Variables for
98 options that may be repeated have list values. Other variables
99 can be set using name=value on the command line. After the
100 script is loaded, option values that were not set on the
101 command line are replaced by the values set in the script.
102 -F=FILE, --config=FILE
104 Use the given SXP formated configuration script. SXP is the
105 underlying configuration format used by Xen. SXP configuration
106 scripts can be hand-written or generated from Python
107 configuration scripts, using the -n (dryrun) option to print
108 the configuration. An SXP formatted configuration file may
109 also be generated for a given domain-id by redirecting the
110 output from the the xm list --long domain-id to a file.
111 -n, --dryrun
113 Dry run - prints the resulting configuration in SXP but does
114 not create the domain.
115 -x, --xmldryrun
117 XML dry run - prints the resulting configuration in XML but
118 does not create the domain.
119 -s, --skipdtd
121 Skip DTD checking - skips checks on XML before creating.
122 Experimental. Can decrease create time.
123 -p, --paused
125 Leave the domain paused after it is created.
126 -c, --console_autoconnect
128 Attach console to the domain as soon as it has started. This
129 is useful for determining issues with crashing domains.
130 EXAMPLES
132 with config file
134 xm create Fedora4
135 This creates a domain with the file /etc/xen/Fedora4, and
137 returns as soon as it is run.
138 without config file
140 xm create /dev/null ramdisk=initrd.img \
141 kernel=/boot/vmlinuz-2.6.12.6-xenU \
142 name=ramdisk vif='' vcpus=1 \
143 memory=64 root=/dev/ram0
144 This creates the domain without using a config file (more
146 specifically using /dev/null as an empty config file), kernel
147 and ramdisk as specified, setting the name of the domain to
148 "ramdisk", also disabling virtual networking. (This example
149 comes from the xm-test test suite.)
150 delete
152 Remove a domain from Xend domain management. The xm list command
153 shows the domain names.
154 destroy domain-id
156 Immediately terminate the domain domain-id. This doesn't give the
157 domain OS any chance to react, and is the equivalent of ripping the
158 power cord out on a physical machine. In most cases you will want
159 to use the shutdown command instead.
160 domid domain-name
162 Converts a domain name to a domain id using xend's internal
163 mapping.
164 domname domain-id
166 Converts a domain id to a domain name using xend's internal
167 mapping.
168 dump-core [OPTIONS] domain-id [filename]
170 Dumps the virtual machine's memory for the specified domain to the
171 filename specified. The dump file will be written to a
172 distribution specific directory for dump files. Such as:
173 /var/lib/xen/dump or /var/xen/dump Defaults to dumping the core
174 without pausing the domain if no OPTIONS are specified.
175 OPTIONS
177 -L, --live
179 Dump core without pausing the domain.
180 -C, --crash
182 Crash domain after dumping core.
183 help [--long]
185 Displays the short help message (i.e. common commands).
186 The --long option prints out the complete set of xm subcommands,
188 grouped by function.
189 list [OPTIONS] [domain-id ...]
191 Prints information about one or more domains. If no domains are
192 specified it prints out information about all domains.
193 OPTIONS
195 -l, --long
197 The output for xm list is not the table view shown below, but
198 instead presents the data in SXP format.
199 --label
201 Security labels are added to the output of xm list and the
202 lines are sorted by the labels (ignoring case). See the ACCESS
203 CONTROL SUBCOMMAND section of this man page for more
204 information about labels.
205 --state=<state>
207 Output information for VMs in the specified state.
208 EXAMPLE
210 An example format for the list is as follows:
212 Name ID Mem(MiB) VCPUs State Time(s)
214 Domain-0 0 98 1 r----- 5068.6
215 Fedora3 164 128 1 r----- 7.6
216 Fedora4 165 128 1 ------ 0.6
217 Mandrake2006 166 128 1 -b---- 3.6
218 Mandrake10.2 167 128 1 ------ 2.5
219 Suse9.2 168 100 1 ------ 1.8
220 Name is the name of the domain. ID the numeric domain id. Mem is
222 the desired amount of memory to allocate to the domain (although it
223 may not be the currently allocated amount). VCPUs is the number of
224 virtual CPUs allocated to the domain. State is the run state (see
225 below). Time is the total run time of the domain as accounted for
226 by Xen.
227 STATES
229 The State field lists 6 states for a Xen domain, and which ones the
231 current domain is in.
232 r - running
234 The domain is currently running on a CPU.
235 b - blocked
237 The domain is blocked, and not running or runnable. This can
238 be caused because the domain is waiting on IO (a traditional
239 wait state) or has gone to sleep because there was nothing else
240 for it to do.
241 p - paused
243 The domain has been paused, usually occurring through the
244 administrator running xm pause. When in a paused state the
245 domain will still consume allocated resources like memory, but
246 will not be eligible for scheduling by the Xen hypervisor.
247 s - shutdown
249 FIXME: Why would you ever see this state?
250 c - crashed
252 The domain has crashed, which is always a violent ending.
253 Usually this state can only occur if the domain has been
254 configured not to restart on crash. See xmdomain.cfg for more
255 info.
256 d - dying
258 The domain is in process of dying, but hasn't completely
259 shutdown or crashed.
260 FIXME: Is this right?
262 NOTES
264 The Time column is deceptive. Virtual IO (network and block
266 devices) used by domains requires coordination by Domain0,
267 which means that Domain0 is actually charged for much of the
268 time that a DomainU is doing IO. Use of this time value to
269 determine relative utilizations by domains is thus very
270 suspect, as a high IO workload may show as less utilized than a
271 high CPU workload. Consider yourself warned.
272 mem-max domain-id mem
274 Specify the maximum amount of memory the domain is able to use.
275 mem is specified in megabytes.
276 The mem-max value may not correspond to the actual memory used in
278 the domain, as it may balloon down its memory to give more back to
279 the OS.
280 mem-set domain-id mem
282 Set the domain's used memory using the balloon driver.
283 Because this operation requires cooperation from the domain
285 operating system, there is no guarantee that it will succeed. This
286 command will definitely not work unless the domain has the required
287 paravirt driver.
288 Warning: There is no good way to know in advance how small of a
290 mem-set will make a domain unstable and cause it to crash. Be very
291 careful when using this command on running domains.
292 migrate domain-id host [OPTIONS]
294 Migrate a domain to another host machine. Xend must be running on
295 other host machine, it must be running the same version of Xen, it
296 must have the migration TCP port open and accepting connections
297 from the source host, and there must be sufficient resources for
298 the domain to run (memory, disk, etc).
299 Migration is pretty complicated, and has many security
301 implications. Please read the Xen User's Guide to ensure you
302 understand the ramifications and limitations on migration before
303 attempting it in production.
304 OPTIONS
306 -l, --live
308 Use live migration. This will migrate the domain between hosts
309 without shutting down the domain. See the Xen User's Guide for
310 more information.
311 -r, --resource Mbs
313 Set maximum Mbs allowed for migrating the domain. This ensures
314 that the network link is not saturated with migration traffic
315 while attempting to do other useful work.
316 new configfile [OPTIONS] [vars]...
318 Adds a domain to Xend domain management.
319 The new subcommand requires a config file and can optionally take a
321 series of vars that add to or override variables defined in the
322 config file. See xmdomain.cfg for full details of that file
323 format, and possible options used in either the configfile or for
324 vars.
325 configfile can either be an absolute path to a file, or a relative
327 path to a file located in /etc/xen.
328 The new subcommand will return without starting the domain. The
330 domain needs to be started using the xm start command.
331 OPTIONS
333 --help_config
335 Print the available configuration variables vars. These
336 variables may be used on the command line or in the
337 configuration file configfile.
338 -q, --quiet
340 No console output.
341 --path
343 Search path for configuration scripts. The value of PATH is a
344 colon-separated directory list.
345 -f=FILE, --defconfig=FILE
347 Use the given Python configuration script. The configuration
348 script is loaded after arguments have been processed. Each
349 command-line option sets a configuration variable named after
350 its long option name, and these variables are placed in the
351 environment of the script before it is loaded. Variables for
352 options that may be repeated have list values. Other variables
353 can be set using name=value on the command line. After the
354 script is loaded, option values that were not set on the
355 command line are replaced by the values set in the script.
356 -F=FILE, --config=FILE
358 Use the given SXP formated configuration script. SXP is the
359 underlying configuration format used by Xen. SXP configuration
360 scripts can be hand-written or generated from Python
361 configuration scripts, using the -n (dryrun) option to print
362 the configuration. An SXP formatted configuration file may
363 also be generated for a given domain-id by redirecting the
364 output from the the xm list --long domain-id to a file.
365 -n, --dryrun
367 Dry run - prints the resulting configuration in SXP but does
368 not create the domain.
369 -x, --xmldryrun
371 XML dry run - prints the resulting configuration in XML but
372 does not create the domain.
373 -s, --skipdtd
375 Skip DTD checking - skips checks on XML before creating.
376 Experimental. Can decrease create time.
377 -p, --paused
379 Leave the domain paused after it is created.
380 -c, --console_autoconnect
382 Attach console to the domain as soon as it has started. This
383 is useful for determining issues with crashing domains.
384 pause domain-id
386 Pause a domain. When in a paused state the domain will still
387 consume allocated resources such as memory, but will not be
388 eligible for scheduling by the Xen hypervisor.
389 reboot [OPTIONS] domain-id
391 Reboot a domain. This acts just as if the domain had the reboot
392 command run from the console. The command returns as soon as it
393 has executed the reboot action, which may be significantly before
394 the domain actually reboots.
395 The behavior of what happens to a domain when it reboots is set by
397 the on_reboot parameter of the xmdomain.cfg file when the domain
398 was created.
399 OPTIONS
401 -a, --all
403 Reboot all domains.
404 -w, --wait
406 Wait for reboot to complete before returning. This may take a
407 while, as all services in the domain will have to be shut down
408 cleanly.
409 restore state-file
411 Build a domain from an xm save state file. See save for more info.
412 resume domain-name [OPTIONS]
414 Moves a domain out of the suspended state and back into memory.
415 OPTIONS
417 -p, <--paused>
419 Moves a domain back into memory but leaves the domain in a
420 paused state. The xm unpause subcommand may then be used to
421 bring it out of the paused state.
422 save domain-id state-file
424 Saves a running domain to a state file so that it can be restored
425 later. Once saved, the domain will no longer be running on the
426 system, thus the memory allocated for the domain will be free for
427 other domains to use. xm restore restores from this state file.
428 This is roughly equivalent to doing a hibernate on a running
430 computer, with all the same limitations. Open network connections
431 may be severed upon restore, as TCP timeouts may have expired.
432 shutdown [OPTIONS] domain-id
434 Gracefully shuts down a domain. This coordinates with the domain
435 OS to perform graceful shutdown, so there is no guarantee that it
436 will succeed, and may take a variable length of time depending on
437 what services must be shutdown in the domain. The command returns
438 immediately after signally the domain unless that -w flag is used.
439 The behavior of what happens to a domain when it reboots is set by
441 the on_shutdown parameter of the xmdomain.cfg file when the domain
442 was created.
443 OPTIONS
445 -a Shutdown all domains. Often used when doing a complete
447 shutdown of a Xen system.
448 -w Wait for the domain to complete shutdown before returning.
450 start domain-name [OPTIONS]
452 Start a Xend managed domain that was added using the xm new
453 command.
454 OPTIONS
456 -p, --paused
458 Do not unpause domain after starting it.
459 -c, --console_autoconnect
461 Connect to the console after the domain is created.
462 suspend domain-name
464 Suspend a domain to a state file so that it can be later resumed
465 using the xm resume subcommand. Similar to the xm save subcommand
466 although the state file may not be specified.
467 sysrq domain-id letter
469 Send a Magic System Request signal to the domain. For more
470 information on available magic sys req operations, see sysrq.txt in
471 your Linux Kernel sources.
472 unpause domain-id
474 Moves a domain out of the paused state. This will allow a
475 previously paused domain to now be eligible for scheduling by the
476 Xen hypervisor.
477 vcpu-set domain-id vcpu-count
479 Enables the vcpu-count virtual CPUs for the domain in question.
480 Like mem-set, this command can only allocate up to the maximum
481 virtual CPU count configured at boot for the domain.
482 If the vcpu-count is smaller than the current number of active
484 VCPUs, the highest number VCPUs will be hotplug removed. This may
485 be important for pinning purposes.
486 Attempting to set the VCPUs to a number larger than the initially
488 configured VCPU count is an error. Trying to set VCPUs to < 1 will
489 be quietly ignored.
490 Because this operation requires cooperation from the domain
492 operating system, there is no guarantee that it will succeed. This
493 command will not work with a full virt domain.
494 vcpu-list [domain-id]
496 Lists VCPU information for a specific domain. If no domain is
497 specified, VCPU information for all domains will be provided.
498 vcpu-pin domain-id vcpu cpus
500 Pins the the VCPU to only run on the specific CPUs. The keyword
501 all can be used to apply the cpus list to all VCPUs in the domain.
502 Normally VCPUs can float between available CPUs whenever Xen deems
504 a different run state is appropriate. Pinning can be used to
505 restrict this, by ensuring certain VCPUs can only run on certain
506 physical CPUs.
507
509 dmesg [-c]
510 Reads the Xen message buffer, similar to dmesg on a Linux system.
511 The buffer contains informational, warning, and error messages
512 created during Xen's boot process. If you are having problems with
513 Xen, this is one of the first places to look as part of problem
514 determination.
515 OPTIONS
517 -c, --clear
519 Clears Xen's message buffer.
520 info
522 Print information about the Xen host in name : value format. When
523 reporting a Xen bug, please provide this information as part of the
524 bug report.
525 Sample output looks as follows (lines wrapped manually to make the
527 man page more readable):
528 host : talon
530 release : 2.6.12.6-xen0
531 version : #1 Mon Nov 14 14:26:26 EST 2005
532 machine : i686
533 nr_cpus : 2
534 nr_nodes : 1
535 cores_per_socket : 1
536 threads_per_core : 1
537 cpu_mhz : 696
538 hw_caps : 0383fbff:00000000:00000000:00000040
539 total_memory : 767
540 free_memory : 37
541 xen_major : 3
542 xen_minor : 0
543 xen_extra : -devel
544 xen_caps : xen-3.0-x86_32
545 xen_scheduler : credit
546 xen_pagesize : 4096
547 platform_params : virt_start=0xfc000000
548 xen_changeset : Mon Nov 14 18:13:38 2005 +0100
549 7793:090e44133d40
550 cc_compiler : gcc version 3.4.3 (Mandrakelinux
551 10.2 3.4.3-7mdk)
552 cc_compile_by : sdague
553 cc_compile_domain : (none)
554 cc_compile_date : Mon Nov 14 14:16:48 EST 2005
555 xend_config_format : 3
556 FIELDS
558 Not all fields will be explained here, but some of the less obvious
560 ones deserve explanation:
561 hw_caps
563 A vector showing what hardware capabilities are supported by
564 your processor. This is equivalent to, though more cryptic,
565 the flags field in /proc/cpuinfo on a normal Linux machine.
566 free_memory
568 Available memory (in MB) not allocated to Xen, or any other
569 domains.
570 xen_caps
572 The Xen version and architecture. Architecture values can be
573 one of: x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
574 xen_changeset
576 The Xen mercurial changeset id. Very useful for determining
577 exactly what version of code your Xen system was built from.
578 log Print out the xend log. This log file can be found in
580 /var/log/xend.log.
581 top Executes the xentop command, which provides real time monitoring of
583 domains. Xentop is a curses interface, and reasonably self
584 explanatory.
585 uptime
587 Prints the current uptime of the domains running.
588
590 Xen ships with a number of domain schedulers, which can be set at boot
591 time with the sched= parameter on the Xen command line. By default
592 credit is used for scheduling.
593 FIXME: we really need a scheduler expert to write up this section.
595 sched-credit [ -d domain-id [ -w[=WEIGHT] | -c[=CAP] ] ]
597 Set credit scheduler parameters. The credit scheduler is a
598 proportional fair share CPU scheduler built from the ground up to
599 be work conserving on SMP hosts.
600 Each domain (including Domain0) is assigned a weight and a cap.
602 PARAMETERS
604 WEIGHT
606 A domain with a weight of 512 will get twice as much CPU as a
607 domain with a weight of 256 on a contended host. Legal weights
608 range from 1 to 65535 and the default is 256.
609 CAP The cap optionally fixes the maximum amount of CPU a domain
611 will be able to consume, even if the host system has idle CPU
612 cycles. The cap is expressed in percentage of one physical CPU:
613 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
614 The default, 0, means there is no upper cap.
615 sched-sedf period slice latency-hint extratime weight
617 Set Simple EDF (Earliest Deadline First) scheduler parameters.
618 This scheduler provides weighted CPU sharing in an intuitive way
619 and uses realtime-algorithms to ensure time guarantees. For more
620 information see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen
621 distribution.
622 PARAMETERS
624 period
626 The normal EDF scheduling usage in nanoseconds
627 slice
629 The normal EDF scheduling usage in nanoseconds
630 FIXME: these are lame, should explain more.
632 latency-hint
634 Scaled period if domain is doing heavy I/O.
635 extratime
637 Flag for allowing domain to run in extra time.
638 weight
640 Another way of setting CPU slice.
641 EXAMPLES
643 normal EDF (20ms/5ms):
645 xm sched-sedf <dom-id> 20000000 5000000 0 0 0
647 best-effort domains (i.e. non-realtime):
649 xm sched-sedf <dom-id> 20000000 0 0 1 0
651 normal EDF (20ms/5ms) + share of extra-time:
653 xm sched-sedf <dom-id> 20000000 5000000 0 1 0
655 4 domains with weights 2:3:4:2
657 xm sched-sedf <d1> 0 0 0 0 2
659 xm sched-sedf <d2> 0 0 0 0 3
660 xm sched-sedf <d3> 0 0 0 0 4
661 xm sched-sedf <d4> 0 0 0 0 2
662 1 fully-specified (10ms/3ms) domain, 3 other domains share
664 available rest in 2:7:3 ratio:
665 xm sched-sedf <d1> 10000000 3000000 0 0 0
667 xm sched-sedf <d2> 0 0 0 0 2
668 xm sched-sedf <d3> 0 0 0 0 7
669 xm sched-sedf <d4> 0 0 0 0 3
670
672 Most virtual devices can be added and removed while guests are running.
673 The effect to the guest OS is much the same as any hotplug event.
674 BLOCK DEVICES
676 block-attach domain-id be-dev fe-dev mode [bedomain-id]
677 Create a new virtual block device. This will trigger a hotplug
678 event for the guest.
679 OPTIONS
681 domain-id
683 The domain id of the guest domain that the device will be
684 attached to.
685 be-dev
687 The device in the backend domain (usually domain 0) to be
688 exported. This can be specified as a physical partition
689 (phy:sda7) or as a file mounted as loopback
690 (file://path/to/loop.iso).
691 fe-dev
693 How the device should be presented to the guest domain. It can
694 be specified as either a symbolic name, such as /dev/hdc, for
695 common devices, or by device id, such as 0x1400 (/dev/hdc
696 device id in hex).
697 mode
699 The access mode for the device from the guest domain.
700 Supported modes are w (read/write) or r (read-only).
701 bedomain-id
703 The back end domain hosting the device. This defaults to
704 domain 0.
705 EXAMPLES
707 Mount an ISO as a Disk
709 xm block-attach guestdomain file://path/to/dsl-2.0RC2.iso
710 /dev/hdc ro
711 This will mount the dsl ISO as /dev/hdc in the guestdomain as a
713 read only device. This will probably not be detected as a CD-
714 ROM by the guest, but mounting /dev/hdc manually will work.
715 block-detach domain-id devid [--force]
717 Detach a domain's virtual block device. devid may be the symbolic
718 name or the numeric device id given to the device by domain 0. You
719 will need to run xm block-list to determine that number.
720 Detaching the device requires the cooperation of the domain. If
722 the domain fails to release the device (perhaps because the domain
723 is hung or is still using the device), the detach will fail. The
724 --force parameter will forcefully detach the device, but may cause
725 IO errors in the domain.
726 block-list [-l|--long] domain-id
728 List virtual block devices for a domain. The returned output is
729 formatted as a list or as an S-Expression if the --long option was
730 given.
731 NETWORK DEVICES
733 network-attach domain-id [script=scriptname] [ip=ipaddr] [mac=macaddr]
734 [bridge=bridge-name] [backend=bedomain-id]
735 Creates a new network device in the domain specified by domain-id.
736 It takes the following optional options:
737 OPTIONS
739 script=scriptname
741 Use the specified script name to bring up the network. Defaults to
742 the default setting in xend-config.sxp for vif-script.
743 ip=ipaddr
745 Passes the specified IP Address to the adapter on creation.
746 FIXME: this currently appears to be broken. I'm not sure under
748 what circumstances this should actually work.
749 mac=macaddr
751 The MAC address that the domain will see on its Ethernet device.
752 If the device is not specified it will be randomly generated with
753 the 00:16:3e vendor id prefix.
754 bridge=bridge-name
756 The name of the bridge to attach the vif to, in case you have more
757 than one. This defaults to xenbr0.
758 backend=bedomain-id
760 The backend domain id. By default this is domain 0.
761 network-detach domain-id devid
763 Removes the network device from the domain specified by domain-id.
764 devid is the virtual interface device number within the domain
765 (i.e. the 3 in vif22.3).
766 FIXME: this is currently broken. Network devices aren't completely
768 removed from domain 0.
769 network-list [-l|--long]> domain-id
771 List virtual network interfaces for a domain. The returned output
772 is formatted as a list or as an S-Expression if the --long option
773 was given.
774 VIRTUAL TPM DEVICES
776 vtpm-list [-l|--long] domain-id
777 Show the virtual TPM device for a domain. The returned output is
778 formatted as a list or as an S-Expression if the --long option was
779 given.
780
782 The Virtual Network interfaces for Xen.
783 FIXME: This needs a lot more explanation, or it needs to be ripped out
785 entirely.
786 vnet-list [-l|--long]
788 List vnets.
789 vnet-create config
791 Create a vnet from a config file.
792 vnet-delete vnetid
794 Delete a vnet.
795
797 Access Control in Xen consists of two components: (i) The Access
798 Control Policy (ACP) defines security labels and access rules based on
799 these labels. (ii) The Access Control Module (ACM) makes access control
800 decisions by interpreting the policy when domains require to
801 communicate or to access resources. The Xen access control has
802 sufficient mechanisms in place to enforce the access decisions even
803 against maliciously acting user domains (mandatory access control).
804 Access rights for domains in Xen are determined by the domain security
806 label only and not based on the domain Name or ID. The ACP specifies
807 security labels that can then be assigned to domains and resources.
808 Every domain must be assigned exactly one security label, otherwise
809 access control decisions could become indeterministic. ACPs are
810 distinguished by their name, which is a parameter to most of the
811 subcommands described below. Currently, the ACP specifies two ways to
812 interpret labels:
813 (1) Simple Type Enforcement: Labels are interpreted to decide access of
815 domains to communication means and virtual or physical resources.
816 Communication between domains as well as access to resources are
817 forbidden by default and can only take place if they are explicitly
818 allowed by the security policy. The proper assignment of labels to
819 domains controls the sharing of information (directly through
820 communication or indirectly through shared resources) between domains.
821 This interpretation allows to control the overt (intended)
822 communication channels in Xen.
823 (2) Chinese Wall: Labels are interpreted to decide which domains can
825 co-exist (be run simultaneously) on the same system. This
826 interpretation allows to prevent direct covert (unintended) channels
827 and mitigates risks caused by imperfect core domain isolation (trade-
828 off between security and other system requirements). For a short
829 introduction to covert channels, please refer to
830 http://www.multicians.org/timing-chn.html.
831 The following subcommands help you to manage security policies in Xen
833 and to assign security labels to domains. To enable access control
834 security in Xen, you must compile Xen with ACM support enabled as
835 described under "Configuring Security" below. There, you will find also
836 examples of each subcommand described here.
837 setpolicy ACM policy
839 Makes the given ACM policy available to xend as a xend-managed
840 policy. The policy is compiled and a mapping (.map) as well as a
841 binary (.bin) version of the policy is created. The policy is
842 loaded and the system's bootloader is prepared to boot the system
843 with this policy the next time it is started.
844 policy is a dot-separated list of names. The last part is the file
846 name pre-fix for the policy XML file. The preceding name parts are
847 translated into the local path pointing to the policy XML file
848 relative to the global policy root directory
849 (/etc/xen/acm-security/policies). For example,
850 example.chwall_ste.client_v1 denotes the policy file
851 example/chwall_ste/client_v1-security_policy.xml relative to the
852 global policy root directory.
853 resetpolicy
855 Reset the system's policy to the default state where the DEFAULT
856 policy is loaded and enforced. This operation may fail if for
857 example guest VMs are running and and one of them uses a different
858 label than what Domain-0 does. It is best to make sure that no
859 guests are running before issuing this command.
860 getpolicy [--dumpxml]
862 Displays information about the current xend-managed policy, such as
863 name and type of the policy, the uuid xend has assigned to it on
864 the local system, the version of the XML representation and the
865 status of the policy, such as whether it is currently loaded into
866 Xen or whether the policy is automatically loaded during system
867 boot. With the --dumpxml option, the XML representation of the
868 policy is displayed.
869 dumppolicy
871 Prints the current security policy state information of Xen.
872 labels [policy] [type=dom|res|any]
874 Lists all labels of a type (domain, resource, or both) that are
875 defined in the policy. Unless specified, the default policy is the
876 currently enforced access control policy. The default for type is
877 'dom'. The labels are arranged in alphabetical order.
878 addlabel label dom configfile [policy]
880 addlabel label mgt domain name [policy type:policy]
881 addlabel label res resource [policy]
882 addlabel label vif-idx domain name [policy type:policy]
883 Adds the security label with name label to a domain configfile
884 (dom), a Xend-managed domain (mgt), to the global resource label
885 file for the given resource (res), or to a managed domain's virtual
886 network interface (vif) that is specified by its index. Unless
887 specified, the default policy is the currently enforced access
888 control policy. This subcommand also verifies that the policy
889 definition supports the specified label name.
890 The only policy type that is currently supported is ACM.
892 rmlabel dom configfile
894 rmlabel mgt domain name
895 rmlabel res resource
896 rmlabel vif-idx domain name
897 Works the same as the addlabel command (above), except that this
898 command will remove the label from the domain configfile (dom), a
899 Xend-managed domain (mgt), the global resource label file (res), or
900 a managed domain's network interface (vif).
901 getlabel dom configfile
903 getlabel mgt domain name
904 getlabel res resource
905 getlabel vif-idx domain name
906 Shows the label for a domain's configuration in the given
907 configfile, a xend-managed domain (mgt), a resource, or a managed
908 domain's network interface (vif).
909 resources
911 Lists all resources in the global resource label file. Each
912 resource is listed with its associated label and policy name.
913 dry-run configfile
915 Determines if the specified configfile describes a domain with a
916 valid security configuration for type enforcement. The test shows
917 the policy decision made for each resource label against the domain
918 label as well as the overall decision.
919 CONFIGURING SECURITY
921 In xen_source_dir/Config.mk set the following parameter:
923 XSM_ENABLE ?= y
925 ACM_SECURITY ?= y
926 Then recompile and install xen and the security tools and then
928 reboot:
929 cd xen_source_dir; make clean; make install
931 reboot into Xen
932 RESETTING THE SYSTEM'S SECURITY
934 To set the system's security policy enforcement into its
936 default state, the follow command can be issued. Make sure that
937 no guests are running while doing this.
938 xm resetpolicy
940 After this command has successfully completed, the system's
942 DEFAULT policy is enforced.
943 SETTING A SECURITY POLICY
945 This step sets the system's policy and automatically loads it
947 into Xen for enforcement.
948 xm setpolicy ACM example.client_v1
950 LISTING SECURITY LABELS
952 This subcommand shows all labels that are defined and which can
954 be attached to domains.
955 xm labels example.client_v1 type=dom
957 will print for our example policy:
959 dom_BoincClient
961 dom_Fun
962 dom_HomeBanking
963 dom_NetworkDomain
964 dom_StorageDomain
965 dom_SystemManagement
966 ATTACHING A SECURITY LABEL TO A DOMAIN
968 The addlabel subcommand can attach a security label to a domain
970 configuration file, here a HomeBanking label. The example
971 policy ensures that this domain does not share information with
972 other non-homebanking user domains (i.e., domains labeled as
973 dom_Fun or dom_Boinc) and that it will not run simultaneously
974 with domains labeled as dom_Fun.
975 We assume that the specified myconfig.xm configuration file
977 actually instantiates a domain that runs workloads related to
978 home-banking, probably just a browser environment for online-
979 banking.
980 xm addlabel dom_HomeBanking dom myconfig.xm
982 The very simple configuration file might now look as printed
984 below. The addlabel subcommand added the access_control entry
985 at the end of the file, consisting of a label name and the
986 policy that specifies this label name:
987 kernel = "/boot/vmlinuz-2.6.16-xen"
989 ramdisk="/boot/U1_home_banking_ramdisk.img"
990 memory = 164
991 name = "homebanking"
992 vif = [ '' ]
993 dhcp = "dhcp"
994 access_control = ['policy=example.chwall_ste.client_v1,
995 label=dom_HomeBanking']
996 Security labels must be assigned to domain configurations
998 because these labels are essential for making access control
999 decisions as early as during the configuration phase of a newly
1000 instantiated domain. Consequently, a security-enabled Xen
1001 hypervisor will only start domains that have a security label
1002 configured and whose security label is consistent with the
1003 currently enforced policy. Otherwise, starting the domain will
1004 fail with the error condition "operation not permitted".
1005 ATTACHING A SECURITY LABEL TO A XEND-MANAGED DOMAIN
1007 The addlabel subcommand supports labeling of domains that are
1009 managed by xend. This includes domains that are currently
1010 running, such as for example Domain-0, or those that are in a
1011 dormant state. Depending on the state of the system, it is
1012 possible that the new label is rejected. An example for a
1013 reason for the rejection of the relabeling of a domain would be
1014 if a domain is currently allowed to access its labeled
1015 resources but due to the new label would be prevented from
1016 accessing one or more of them.
1017 xm addlabel dom_Fun mgt Domain-0
1019 This changes the label of Domain-0 to dom_Fun under the
1021 condition that this new label of Domain-0 would not prevent any
1022 other domain from accessing its resources that are provided
1023 through Domain-0, such as for example network or block device
1024 access.
1025 ATTACHING A SECURITY LABEL TO A RESOURCE
1027 The addlabel subcommand can also be used to attach a security
1029 label to a resource. Following the home banking example from
1030 above, we can label a disk resource (e.g., a physical partition
1031 or a file) to make it accessible to the home banking domain.
1032 The example policy provides a resource label,
1033 res_LogicalDiskPartition1(hda1), that is compatible with the
1034 HomeBanking domain label.
1035 xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6
1037 After labeling this disk resource, it can be attached to the
1039 domain by adding a line to the domain configuration file. The
1040 line below attaches this disk to the domain at boot time.
1041 disk = [ 'phy:hda6,sda2,w' ]
1043 Alternatively, the resource can be attached after booting the
1045 domain by using the block-attach subcommand.
1046 xm block-attach homebanking phy:hda6 sda2 w
1048 Note that labeled resources cannot be used when security is
1050 turned off. Any attempt to use labeled resources with security
1051 turned off will result in a failure with a corresponding error
1052 message. The solution is to enable security or, if security is
1053 no longer desired, to remove the resource label using the
1054 rmlabel subcommand.
1055 STARTING AND LISTING LABELED DOMAINS
1057 xm create myconfig.xm
1059 xm list --label
1061 Name ID ... Time(s) Label
1063 homebanking 23 ... 4.4 dom_HomeBanking
1064 Domain-0 0 ... 2658.8 dom_SystemManagement
1065 LISTING LABELED RESOURCES
1067 xm resources
1069 phy:hda6
1071 type: ACM
1072 policy: example.chwall_ste.client_v1
1073 label: res_LogicalDiskPartition1(hda1)
1074 file:/xen/disk_image/disk.img
1075 type: ACM
1076 policy: example.chwall_ste.client_v1
1077 label: res_LogicalDiskPartition2(hda2)
1078 POLICY REPRESENTATIONS
1080 We distinguish three representations of the Xen access control
1082 policy: the source XML version, its binary counterpart, and a
1083 mapping representation that enables the tools to
1084 deterministically translate back and forth between label names
1085 of the XML policy and label identifiers of the binary policy.
1086 All three versions must be kept consistent to achieve
1087 predictable security guarantees.
1088 The XML version is the version that users are supposed to
1090 create or change, either by manually editing the XML file or by
1091 using the Xen policy generation tool (xensec_gen). After
1092 changing the XML file, run the setpolicy subcommand to ensure
1093 that the new policy is available to xend. Use, for example, the
1094 subcommand activatepolicy to activate the changes during the
1095 next system reboot.
1096 The binary version of the policy is derived from the XML policy
1098 by tokenizing the specified labels and is used inside Xen only.
1099 It is created with the setpolicy subcommand. Essentially, the
1100 binary version is much more compact than the XML version and is
1101 easier to evaluate during access control decisions.
1102 The mapping version of the policy is created during the XML-to-
1104 binary policy translation (setpolicy) and is used by xend and
1105 the management tools to translate between label names used as
1106 input to the tools and their binary identifiers (ssidrefs) used
1107 inside Xen.
1108
1110 xmdomain.cfg(5), xentop(1)
1111
1113 Sean Dague <sean at dague dot net>
1114 Daniel Stekloff <dsteklof at us dot ibm dot com>
1115 Reiner Sailer <sailer at us dot ibm dot com>
1116 Stefan Berger <stefanb at us dot ibm dot com>
1117
1119xen-unstable 2011-10-20 xm(1)