Appendix A: xm Reference
The xm command is probably the first thing to know about Xen. It’s your primary interface to Xen’s control-plane functionality. Using xm, you can create, query, and destroy domains. You can send certain instructions (e.g., shut down) to guest domains. You can attach and detach storage and network devices and dynamically adjust resource consumption.
In short, knowing xm is important. That’s why we’ve documented xm’s subcommands here, with references to the rest of the book.
NOTE: Some of these commands—the ones introduced with Xen 3.1 or later—may not work
with the Xen version included in RHEL 5.x because Red Hat’s priority is to maintain compatibility within major releases, rather than support new features. These commands
are marked with an asterisk.
All of xm’s commands work by sending instructions to xend, the Xen control daemon. This is a Python program that runs in domain 0. It receives requests and sends replies to client applications, like xm.
If xend isn’t running, xm will return an error and exit. Much of xm’s functionality relies on the XenBus, which is a shared communication channel between all domains on the machine, and the XenStore, which is a centralized configuration database that xend uses to hold domain configuration information and states. For more information on the XenStore and XenBus, take a look at Chapter 14.
That said, let’s look at the general form of an xm command.
- 1 xm’s Syntax
- 2 xm Subcommands
- 2.1 addlabel, cfgbootpolicy, dumppolicy, getlabel, labels, loadpolicy, makepolicy, resources, and rmlabel
- 2.2 block-attach, block-configure, block-detach, and block-list
- 2.3 console
- 2.4 create
- 2.5 debug-keys *
- 2.6 delete *
- 2.7 destroy
- 2.8 dmesg
- 2.9 domid and domname
- 2.10 dry-run
- 2.11 dump-core
- 2.12 info
- 2.13 list
- 2.14 log
- 2.15 mem-max
- 2.16 mem-set
- 2.17 migrate
- 2.18 network-attach, network-detach, and network-list
- 2.19 new *
- 2.20 pause
- 2.21 reboot
- 2.22 rename
- 2.23 restore and save
- 2.24 resume *
- 2.25 sched-credit
- 2.26 sched-sedf
- 2.27 shell *
- 2.28 shutdown
- 2.29 start *
- 2.30 suspend *
- 2.31 sysrq
- 2.32 top
- 2.33 trigger *=
- 2.34 unpause
- 2.35 uptime
- 2.36 vcpu-list, vcpu-pin, and vcpu-set
- 2.37 vnet-create, vnet-delete, and vnet-list
- 2.38 vtpm-list
xm’s syntax is fairly simple and consistent:
xm <subcommand> <domain specifier> [options]
Options can go either before or after the domain specifier, but we usually put them at the end. For example, to order domain 10 to shut down cleanly:
xm shutdown 10
Here we’re not specifying any options, and we’re referring to the domain by numeric ID rather than name. The domain specifier may be either a domain number or domain name—the names will be internally translated to numbers. (Note that this won’t work if the XenStore isn’t up, but in that case, you have bigger problems.)
xm commands are usually asynchronous, which means that the command may return before it’s actually completed. In the case of a command like xm shutdown, it may take the domain several minutes to actually shut down. In that case, we ordinarily poll xm list to make sure that the domain has stopped running.
Here’s a list of the various xm subcommands. We use some of them frequently, and we don’t use some of them at all. New commands with version 3.1 are marked with an asterisk (*) because version 3.1 marks a substantial change in Xen’s approach to domain management. As we mentioned earlier, this means they might also not work with RHEL 5.x. Although RHEL 5.2, for example, uses the 3.1 version of the Xen hypervisor, it uses the 3.0.3 versions of the userspace tools, such as xend.
addlabel, cfgbootpolicy, dumppolicy, getlabel, labels, loadpolicy, makepolicy, resources, and rmlabel
These subcommands interface with Xen’s security policy infrastructure. As we mention in Chapter 14, we haven’t seen any practical use for Xen’s security policies. If you’re interested in more information about the security modules (which are themselves the subject of ongoing work), we suggest looking at the sample policies included with the Xen source distribution.
block-attach, block-configure, block-detach, and block-list
The various block subcommands manage storage devices that are attached to domains. These commands are handled in more detail in Chapter 4.
The console subcommand attaches to the given domain’s console. Note that this is only useful if the domain is set up to use Xen’s virtual console.
Even if everything is set up correctly, you may need to press ENTER to make it give you a login prompt. (This can be puzzling for new users, who type xm console and see a blank screen, because nothing’s been added to the console buffer since the last time they used it.)
The xm create subcommand, in recent versions of Xen, is a synonym for xm new followed by xm start. It’s the subcommand we use throughout the book to make domains go.
Create expects the name of a config file. If you don’t specify a file, it uses the default, /etc/xen/xmdefconfig.
The create subcommand takes these options:
- -h: Prints help.
- -q: Quiet mode.
- --path: Base path for domain configuration files (/etc/xen by default).
- -n: Dry-run mode. Prints the configuration that would be generated. This is used to debug Python code in domain configurations. If you’re autogenerating a domain config, it’s nice to have some way to test it.
- -x: Similar to -n but outputs a domain definition in XML. Note that, as of Xen 3.3, this option still relies on the deprecated xml.dom.ext module and thus does not work with many Python installations.
- -c: Connect automatically to the console. This is necessary to interact with PyGRUB.
- -s: Skip DTD checking for XML domain configurations. If you don’t give xm create a full path, it will default to looking for the config file in /etc/xen. You can change that with the --path option.
The debug-keys subcommand interacts with the GDB stub built into Xen, enabling you to send magic keystrokes to control the stub’s output. It is likely to be useful only if you’re hacking Xen’s internals.
Note that this will only have an effect if you’ve built Xen with the GDB stub.
The xm delete subcommand removes a domain from Xen’s management. If the domain is running, the delete subcommand shuts it down, then removes its definition.
- Before you think UNIX is family oriented, note that all children
- must die.
- —Eric Foster-Johnson, Cross-Platform Perl
The xm destroy command is the equivalent of yanking the power plug on a physical machine. If the domU has locked up completely, it may be necessary to ask xend to terminate it forcefully. All resources are immediately returned to the hypervisor.
Like the dmesg system command, the xm dmesg subcommand prints out diagnostic messages from the kernel boot. We talk more about these messages in Chapter 15.
domid and domname
The domid and domname commands look up a domain’s ID when you have its name, or vice versa. Each subcommand takes a single argument, the domain name or ID respectively, and returns the ID or name as appropriate. They’re handy if you’ve got a lot of domains floating around.
Although the dry-run subcommand, in theory, tests whether Xen can successfully find and use its virtual devices, we’ve had mixed luck because it’s not very good at predicting whether we’ll be successful in starting a domain. One important use for it is to debug Python code that is included in domain configurations, as described in Chapter 14.
This subcommand is also a suboption for xm create, which creates the domain in dry-run mode.
The dump-core subcommand triggers an immediate memory dump.
Ordinarily, it pauses the domain, dumps its memory to the specified file, and then unpauses. You can, however, specify the -L (--live) option to make it dump in a fashion similar to live migration, without pausing and unpausing the domain (or, at least, without pausing it for any noticeable amount of time).
The info subcommand prints a lot of useful information about the Xen host, including the precise version of Xen you’re using, the capabilities of the processor, and the memory that’s available for domUs.
The xm list subcommand, in its simplest form, just lists domains in a table. However, it can also print out general information about domains, including a complete s-expression (if given the --long option).
The short form of the list subcommand will also show the state for each domain.
- 'b' (blocked): The domain is waiting for something, either for I/O or scheduling reasons. Idle domains will show up in a blocked state. This is normal; when they have something to do, they’ll be unblocked. * 'p' (paused): This state means that the domain’s been paused by xm pause.
- 'c' (crashed): The domain has crashed.
- 'd' (dying): The domain is in shutdown and in the process of being destroyed by the hypervisor. If a domain remains in this state, the odds are good that it’s a bug.
- 's' (shutdown): The domain is in the process of shutting down, whether because of a command issued from within the domain (e.g., halt) or from dom0 (e.g., xm shutdown). This state is also used for domains that are known to Xen but are not started. If you use xm new, the imported domain definition will show in xm list as shutdown until you start it with xm start.
- 'r' (running): The domain is presently executing on the physical computer. Note that, on a single-processor machine, xm list will always show dom0 as the only running domain because dom0 is generating and displaying the xm list output.
The xm log command simply prints out /var/log/xend.log. We go into more detail about Xen’s various log files in Chapter 15.
The mem-max</tt. subcommand specifies the maximum amount of memory that the domain can use in megabytes. This is identical to the maxmem directive in the domain config file. Right now, this subcommand has no effect on running domains; changes take effect when the domain reboots.
The xm mem-set subcommand works by sending messages to the balloon driver in the target domU. Altering the domain’s memory allocation in this way requires cooperation from the domU’s operating system and thus is not guaranteed. It also raises the possibility of taking too much memory from the domain, which will make it unstable.
We prefer to avoid using this subcommand. However, for more information about the balloon driver, see the relevant discussion in Chapter 14.
The migrate subcommand, as one might suppose, migrates domains. Migration is fairly complicated. Chapter 9 is devoted entirely to the subject.
network-attach, network-detach, and network-list
As you might guess, these subcommands manage virtual network devices (vifs, in Xen parlance, rather than networks per se). With these subcommands, you can attach, detach, and list vifs. We address these subcommands in Chapter 5.
The new subcommand adds a domain to Xen’s management; that is, it defines the domain but doesn’t actually allocate resources or run it. Having imported the domain into Xen, you can start it with the xm start subcommand.
You’ll probably want to run new with the -f option, specifying a file that describes the domain. This can be XML or the standard Python config format.
This subcommand pauses the domain. While paused, the domain continues to occupy memory and hold a lock on its devices, but it won’t be scheduled to run on the CPU.
The reboot subcommand orders the domain to reboot itself cleanly. Note that, if you’re using PyGRUB, xm reboot will not load a new kernel; for that you’ll need to shut down and re-create the domain. The same applies to, for example, shutdown -r from within the domU.
The xm rename subcommand allows the administrator to change the human-readable name associated with the domain ID.
restore and save
The xm restore and save subcommands complement each other. As we describe in Chapter 9, xm save causes a domain to relinquish its resources and save state to a save file, and xm restore</tt. causes it to restore itself from a previously created save file. This is very much like hibernation.
The resume subcommand instructs a domain to return from a suspended state. Note that this only applies to domains managed by xend lifecycle support, which is essentially the ability to have xend</tt. manage inactive domains.
The credit scheduler is the default scheduler for Xen. The sched-credit subcommand configures the credit scheduler, allowing you to display or adjust a domain’s weight and cap. We describe its use at some length in Chapter 7.
The sedf scheduler, of course, is obsolete. However, if you find yourself using it, you can use the sched-sedf subcommand to adjust the scheduling parameters for a domain.
The shell subcommand is a bit interesting. It starts an interactive shell, nicknamed The Xen Master, from which you can issue the various xm subcommands.
Like xm reboot, the shutdown subcommand orders the domain to shut down, with the difference that it doesn’t immediately restart it. This subcommand requires domU cooperation; if the domain doesn’t shut down, xend won’t forcefully terminate it. If xm shutdown doesn’t work, you may want to try xm destroy.
The start subcommand starts a managed domain. Note that this subcommand, like new and suspend, only exists as of Xen 3.1, which adds xend lifecycle support.
The xm suspend subcommand suspends a managed domain.
The sysrq subcommand sends one of the magic sysrq keys to the domU. Note that this can’t be done via xm console because the dom0 won’t pass a sysrq through to the domU. It’s a useful last resort if the domain seems catatonic. For more information about sysrq, see the kernel documentation (Documentation/sysrq.txt in the Linux kernel source tree).
The xm top subcommand presents status information for the running Xen domains in a format similar to that of the top(1) subcommand.
The trigger subcommand sends a CPU event to a domain. It can trigger a Non-Maskable Interrupt (NMI), reset, or init event (although the latter two fail with a function not implemented message on Xen 3.2/i386). This subcommand is useful mostly for debugging.
The xm unpause subcommand resumes a domain that’s been paused with xm pause.
The xm uptime subcommand will print the uptime for the selected domain or for all VMs if no domain is specified.
vcpu-list, vcpu-pin, and vcpu-set
The vcpu- subcommands control which cpus. a domain will use in an SMP system. For more information, see Chapter 7.
vnet-create, vnet-delete, and vnet-list
These three vnet- subcommands interact with Xen’s VLAN support. We don’t cover the VLAN support because we've never had occasion to use it and we’ve never seen anyone else use it. If you're finding it useful, drop us an email.
The vtpm-list subcommand allows you to list the virtual TPMs (trusted platform modules) that are attached to a domain. Although we don’t go into much detail about the TPM, we do refer to it a bit in Chapter 14.