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 twice as much CPU as a domain with a weight of 256 on a contended host. Legal weights range from 1 to 65535 and the default is 256. Honoured by the credit and credit2 schedulers.
The cap optionally fixes the maximum amount of CPU a domain will be able to consume, even if the host system has idle CPU cycles. The cap is expressed as a percentage of one physical CPU: 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is no cap. Honoured by the credit and credit2 schedulers.
NOTE: Many systems have features that will scale down the computing power of a CPU that is not 100% utilized. This can be done in the operating system, but can also sometimes be done below the operating system, in the BIOS. If you set a cap such that individual cores are running at less than 100%, this may have an impact on the performance of your workload over and above the impact of the cap. For example, if your processor runs at 2GHz, and you cap a VM at 50%, the power management system may also reduce the clock speed to 1GHz; the effect will be that your VM gets 25% of the available power (50% of 1GHz) rather than 50% (50% of 2GHz). If you are not getting the performance you expect, look at performance and CPU frequency options in your operating system and your BIOS.
Start the guest with MBYTES megabytes of RAM.
Specifies the maximum amount of memory a guest can ever see. The value of maxmem= must be equal to or greater than that of memory=.
In combination with memory= it will start the guest "pre-ballooned", if the values of memory= and maxmem= differ. A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver it will crash.
NOTE: Because of the way ballo