xl.cfg - xl domain configuration file syntax
/etc/xen/xldomainCreating a VM (a domain in Xen terminology, sometimes called a guest) with xl requires the provision of a domain configuration file. Typically, these live in /etc/xen/DOMAIN.cfg, where DOMAIN is the name of the domain.
A domain configuration file consists of a series of options, specified by using KEY=VALUE pairs.
Some KEYs are mandatory, some are general options which apply to any guest type, while others relate only to specific guest types (e.g. PV or HVM guests).
A VALUE can be one of:
A string, surrounded by either single or double quotes. But if the STRING is part of a SPEC_STRING, the quotes should be omitted.
A number, in either decimal, octal (using a 0 prefix) or hexadecimal (using a 0x prefix) format.
A NUMBER interpreted as False (0) or True (any other value).
A list of VALUEs of the above types. Lists can be heterogeneous and nested.
The semantics of each KEY defines which type of VALUE is required.
Pairs may be separated either by a newline or a semicolon. Both of the following are valid:
name="h0"
type="hvm"
name="h0"; type="hvm"The following key is mandatory for any guest type.
Specifies the name of the domain. Names of domains existing on a single host must be unique.
Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest operating systems. This is the default on x86.
Specifies that this is to be an PVH domain. That is a lightweight HVM-like guest without a device model and without many of the emulated devices available to HVM guests. Note that this mode requires a PVH aware kernel on x86. This is the default on Arm.
Specifies that this is to be an HVM domain. That is, a fully virtualised computer with emulated BIOS, disk and network peripherals, etc.
Note that the builder option is being deprecated in favor of the type option.
Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest operating systems. This is the default.
Specifies that this is to be an HVM domain. That is, a fully virtualised computer with emulated BIOS, disk and network peripherals, etc.
The following options apply to guests of any type.
Put the guest's vCPUs into the named CPU pool.
Start the guest with N vCPUs initially online.
Allow the guest to bring up a maximum of M vCPUs. When starting the guest, if vcpus=N is less than maxvcpus=M then the first N vCPUs will be created online and the remainder will be created offline.
List of host CPUs the guest is allowed to use. Default is no pinning at all (more on this below). A CPULIST may be specified as follows:
To allow all the vCPUs of the guest to run on all the CPUs on the host.
To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It is possible to combine this with "all", meaning "all,^7" results in all the vCPUs of the guest being allowed to run on all the CPUs of the host except CPU 7.
To allow all the vCPUs of the guest to run on the CPUs from NUMA nodes 0,1,3 of the host. So, if CPUs 0-3 belong to node 0, CPUs 4-7 belong to node 1, CPUs 8-11 to node 2 and CPUs 12-15 to node 3, the above would mean all the vCPUs of the guest would be allowed to run on CPUs 0-7,12-15.
Combining this notation with the one above is possible. For instance, "1,node:1,^6", means all the vCPUs of the guest will run on CPU 1 and on all the CPUs of NUMA node 1, but not on CPU 6. Following the same example as above, that would be CPUs 1,4,5,7.
Combining this with "all" is also possible, meaning "all,^node:1" results in all the vCPUs of the guest running on all the CPUs on the host, except for the CPUs belonging to the host NUMA node 1.
To ask for specific vCPU mapping. That means (in this example), vCPU 0 of the guest will run on CPU 2 of the host and vCPU 1 of the guest will run on CPUs 3,4,6,7,8 of the host (excluding CPU 5).
More complex notation can be also used, exactly as described above. So "all,^5-8", or just "all", or "node:0,node:2,^9-11,18-20" are all legal, for each element of the list.
If this option is not specified, no vCPU to CPU pinning is established, and the vCPUs of the guest can run on all the CPUs of the host. If this option is specified, the intersection of the vCPU pinning mask, provided here, and the soft affinity mask, if provided via cpus_soft=, is utilized to compute the domain node-affinity for driving memory allocations.
Exactly as cpus=, but specifies soft affinity, rather than pinning (hard affinity). When using the credit scheduler, this means what CPUs the vCPUs of the domain prefer.
A CPULIST is specified exactly as for cpus=, detailed earlier in the manual.
If this option is not specified, the vCPUs of the guest will not have any preference regarding host CPUs. If this option is specified, the intersection of the soft affinity mask, provided here, and the vCPU pinning, if provided via cpus=, is utilized to compute the domain node-affinity for driving memory allocations.
If this option is not specified (and cpus= is not specified either), libxl automatically tries to place the guest on the least possible number of nodes. A heuristic approach is used for choosing the best node (or set of nodes), with the goal of maximizing performance for the guest and, at the same time, achieving efficient utilization of host CPUs and memory. In that case, the soft affinity of all the vCPUs of the domain will be set to host CPUs belonging to NUMA nodes chosen during placement.
For more details, see xl-numa-placement(7).
A domain with a weight of 512 will get twi