xl - Xen management tool, based on libxenlight
xl subcommand [args]
The xl program is the new tool for managing Xen guest domains. The program can be used to create, pause, and shutdown domains. It can also be used to list current domains, enable or pin VCPUs, and attach or detach virtual block devices.
The basic structure of every xl command is almost always:
xl subcommand [OPTIONS] domain-id
Where subcommand is one of the subcommands listed below, domain-id is the numeric domain id, or the domain name (which will be internally translated to domain id), and OPTIONS are subcommand specific options. There are a few exceptions to this rule in the cases where the subcommand in question acts on all domains, the entire machine, or directly on the Xen hypervisor. Those exceptions will be clear for each of those subcommands.
Most xl operations rely upon xenstored and xenconsoled: make sure you start the script /etc/init.d/xencommons at boot time to initialize all the daemons needed by xl.
In the most common network configuration, you need to setup a bridge in dom0 named xenbr0 in order to have a working network in the guest domains. Please refer to the documentation of your Linux distribution to know how to setup the bridge.
If you specify the amount of memory dom0 has, passing dom0_mem to Xen, it is highly recommended to disable autoballoon. Edit /etc/xen/xl.conf and set it to 0.
Most xl commands require root privileges to run due to the communications channels used to talk to the hypervisor. Running as non root will return an error.
Some global options are always available:
Verbose.
Dry run: do not actually execute the command.
Force execution: xl will refuse to run some commands if it detects that xend is also running, this option will force the execution of those commands, even though it is unsafe.
Always use carriage-return-based overwriting for displaying progress messages without scrolling the screen. Without -t, this is done only if stderr is a tty.
Include timestamps and pid of the xl process in output.
The following subcommands manipulate domains directly. As stated previously, most commands take domain-id as the first parameter.
This command is deprecated. Please use xl trigger instead.
Indicate an ACPI button press to the domain, where button can be 'power' or 'sleep'. This command is only available for HVM domains.
The create subcommand takes a config file as its first argument: see xl.cfg(5) for full details of the file format and possible options. If configfile is missing xl creates the domain assuming the default values for every option.
configfile has to be an absolute path to a file.
Create will return as soon as the domain is started. This does not mean the guest OS in the domain has actually booted, or is available for input.
If the -F option is specified, create will start the domain and not return until its death.
OPTIONS
No console output.
Use the given configuration file.
Leave the domain paused after it is created.
Run in foreground until death of the domain.
Attach to domain's VNC server, forking a vncviewer process.
Pass the VNC password to vncviewer via stdin.
Attach console to the domain as soon as it has started. This is useful for determining issues with crashing domains and just as a general convenience since you often want to watch the domain boot.
It is possible to pass key=value pairs on the command line to provide options as if they were written in the configuration file; these override whatever is in the configfile.
NB: Many config options require characters such as quotes or brackets which are interpreted by the shell (and often discarded) before being passed to xl, resulting in xl being unable to parse the value correctly. A simple work-around is to put all extra options within a single set of quotes, separated by semicolons. (See below for an example.)
EXAMPLES
xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'This creates a domain with the file hvm.cfg, but additionally pins it to cpus 0-3, and passes through two PCI devices.
Update the saved configuration for a running domain. This has no immediate effect but will be applied when the guest is next restarted. This command is useful to ensure that runtime modifications made to the guest will be preserved when the guest is restarted.
Since Xen 4.5 xl has improved capabilities to handle dynamic domain configuration changes and will preserve any changes made at runtime when necessary. Therefore it should not normally be necessary to use this command any more.
configfile has to be an absolute path to a file.
OPTIONS
Use the given configuration file.
It is possible to pass key=value pairs on the command line to provide options as if they were written in the configuration file; these override whatever is in the configfile. Please see the note under create on handling special characters when passing key=value pairs on the command line.
Attach to the console of a domain specified by domain-id. If you've set up your domains to have a traditional login console this will look much like a normal text login screen.
Use the key combination Ctrl+] to detach from the domain console.
OPTIONS
Connect to a PV console or connect to an emulated serial console. PV consoles are the only consoles available for PV domains while HVM domains can have both. If this option is not specified it defaults to emulated serial for HVM guests and PV console for PV guests.
Connect to console number NUM. Console numbers start from 0.
Immediately terminate the domain specified by domain-id. This doesn't give the domain OS any chance to react, and is the equivalent of ripping the power cord out on a physical machine. In most cases you will want to use the shutdown command instead.
OPTIONS
Allow domain 0 to be destroyed. Because a domain cannot destroy itself, this is only possible when using a disaggregated toolstack, and is most useful when using a hardware domain separated from domain 0.
Converts a domain name to a domain id.
Converts a domain id to a domain name.
Change the domain name of a domain specified by domain-id to new-name.
Dumps the virtual machine's memory for the specified domain to the filename specified, without pausing the domain. The dump file will be written to a distribution specific directory for dump files, for example: /var/lib/xen/dump/dump.
Displays the short help message (i.e. common commands) by default.
If the --long option is specified, it displays the complete set of xl subcommands, grouped by function.
Displays information about one or more domains. If no domains are specified it displays information about all domains.
OPTIONS
The output for xl list is not the table view shown below, but instead presents the data as a JSON data structure.
Also displays the security labels.
Also displays the domain UUIDs, the shutdown reason and security labels.
Also displays the cpupool the domain belongs to.
Also displays the domain NUMA node affinity.
EXAMPLE
An example format for the list is as follows:
Name ID Mem VCPUs State Time(s)
Domain-0 0 750 4 r----- 11794.3
win 1 1019 1 r----- 0.3
linux 2 2048 2 r----- 5624.2Name is the name of the domain. ID the numeric domain id. Mem is the desired amount of memory to allocate to the domain (although it may not be the currently allocated amount). VCPUs is the number of virtual CPUs allocated to the domain. State is the run state (see below). Time is the total run time of the domain as accounted for by Xen.
STATES
The State field lists 6 states for a Xen domain, and which ones the current domain is in.
The domain is currently running on a CPU.
The domain is blocked, and not running or runnable. This can be because the domain is waiting on IO (a traditional wait state) or has gone to sleep because there was nothing else for it to do.
The domain has been paused, usually occurring through the administrator running xl pause. When in a paused state the domain will still consume allocated resources (like memory), but will not be eligible for scheduling by the Xen hypervisor.
The guest OS has shut down (SCHEDOP_shutdown has been called) but the domain is not dying yet.
The domain has crashed, which is always a violent ending. Usually this state only occurs if the domain has been configured not to restart on a crash. See xl.cfg(5) for more info.
The domain is in the process of dying, but hasn't completely shut down or crashed.
NOTES
The Time column is deceptive. Virtual IO (network and block devices) used by the domains requires coordination by Domain0, which means that Domain0 is actually charged for much of the time that a DomainU is doing IO. Use of this time value to determine relative utilizations by domains is thus very unreliable, as a high IO workload may show as less utilized than a high CPU workload. Consider yourself warned.
Set the target for the domain's balloon driver.
The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB).
This must be less than the initial maxmem parameter in the domain's configuration.
Note that this operation requests the guest operating system's balloon driver to reach the target amount of memory. The guest may fail to reach that amount of memory for any number of reasons, including:
The guest doesn't have a balloon driver installed
The guest's balloon driver is buggy
The guest's balloon driver cannot create free guest memory due to guest memory pressure
The guest's balloon driver cannot allocate memory from Xen because of hypervisor memory pressure
The guest administrator has disabled the balloon driver
Warning: There is no good way to know in advance how small of a mem-set will make a domain unstable and cause it to crash. Be very careful when using this command on running domains.
Specify the limit Xen will place on the amount of memory a guest may allocate.
The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB).
mem can't be set lower than the current memory target for domain-id. It is allowed to be higher than the configured maximum memory size of the domain (maxmem parameter in the domain's configuration).
Setting the maximum memory size above the configured maximum memory size will require special guest support (memory hotplug) in order to be usable by the guest.
The domain will not receive any signal regarding the changed memory limit.
Migrate a domain to another host machine. By default xl relies on ssh as a transport mechanism between the two hosts.
OPTIONS
Use <sshcommand> instead of ssh. String will be passed to sh. If empty, run <host> instead of ssh <host> xl migrate-receive [-d -e].
On the new <host>, do not wait in the background for the death of the domain. See the corresponding option of the create subcommand.
Send the specified <config> file instead of the file used on creation of the domain.
Display huge (!) amount of debug information during the migration process.
Leave the domain on the receive side paused after migration.
Preserve the domain-id in the domain coniguration that is transferred such that it will be identical on the destination host, unless that configuration is overridden using the -C option. Note that it is not possible to use this option for a 'localhost' migration.
Enable Remus HA or COLO HA for domain. By default xl relies on ssh as a transport mechanism between the two hosts.
NOTES
Remus support in xl is still in experimental (proof-of-concept) phase. Disk replication support is limited to DRBD disks.
COLO support in xl is still in experimental (proof-of-concept) phase. All options are subject to change in the future.
COLO disk configuration looks like:
disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']The supported options are:
COLO network configuration looks like:
vif = [ '...,forwarddev=xxx,...']The supported options are:
OPTIONS
Checkpoint domain memory every MS milliseconds (default 200ms).
Disable memory checkpoint compression.
Use <sshcommand> instead of ssh. String will be passed to sh. If empty, run <host> instead of ssh <host> xl migrate-receive -r [-e].
On the new <host>, do not wait in the background for the death of the domain. See the corresponding option of the create subcommand.
Use <netbufscript> to setup network buffering instead of the default script (/etc/xen/scripts/remus-netbuf-setup).
Run Remus in unsafe mode. Use this option with caution as failover may not work as intended.
Replicate memory checkpoints to /dev/null (blackhole). Generally useful for debugging. Requires enabling unsafe mode.
Disable network output buffering. Requires enabling unsafe mode.
Disable disk replication. Requires enabling unsafe mode.
Enable COLO HA. This conflicts with -i and -b, and memory checkpoint compression must be disabled.
Use userspace COLO Proxy. This option must be used in conjunction with -c.
Pause a domain. When in a paused state the domain will still consume allocated resources (such as memory), but will not be eligible for scheduling by the Xen hypervisor.
Reboot a domain. This acts just as if the domain had the reboot command run from the console. The command returns as soon as it has executed the reboot action, which may be significantly earlier than when the domain actually reboots.
For HVM domains this requires PV drivers to be installed in your guest OS. If PV drivers are not present but you have configured the guest OS to behave appropriately you may be able to use the -F option to trigger a reset button press.
The behavior of what happens to a domain when it reboots is set by the on_reboot parameter of the domain configuration file when the domain was created.
OPTIONS
If the guest does not support PV reboot control then fallback to sending an ACPI power event (equivalent to the reset option to trigger).
You should ensure that the guest is configured to behave as expected in response to this event.
Build a domain from an xl save state file. See save for more info.
OPTIONS
Do not unpause the domain after restoring it.
Do not wait in the background for the death of the domain on the new host. See the corresponding option of the create subcommand.
Enable debug messages.
Attach to the domain's VNC server, forking a vncviewer process.
Pass the VNC password to vncviewer via stdin.
Saves a running domain to a state file so that it can be restored later. Once saved, the domain will no longer be running on the system, unless the -c or -p options are used. xl restore restores from this checkpoint file. Passing a config file argument allows the user to manually select the VM config file used to create the domain.
Leave the domain running after creating the snapshot.
Leave the domain paused after creating the snapshot.
Preserve the domain-id in the domain coniguration that is embedded in the state file such that it will be identical when the domain is restored, unless that configuration is overridden. (See the restore operation above).
Display the number of shared pages for a specified domain. If no domain is specified it displays information about all domains.
Gracefully shuts down a domain. This coordinates with the domain OS to perform graceful shutdown, so there is no guarantee that it will succeed, and may take a variable length of time depending on what services must be shut down in the domain.
For HVM domains this requires PV drivers to be installed in your guest OS. If PV drivers are not present but you have configured the guest OS to behave appropriately you may be able to use the -F option to trigger a power button press.
The command returns immediately after signaling the domain unless the -w flag is used.
The behavior of what happens to a domain when it reboots is set by the on_shutdown parameter of the domain configuration file when the domain was created.
OPTIONS
Shutdown all guest domains. Often used when doing a complete shutdown of a Xen system.
Wait for the domain to complete shutdown before returning. If given once, the wait is for domain shutdown or domain death. If given multiple times, the wait is for domain death only.
If the guest does not support PV shutdown control then fallback to sending an ACPI power event (equivalent to the power option to trigger).
You should ensure that the guest is configured to behave as expected in response to this event.