1=head1 NAME
2
3@XEN_CONFIG_DIR@/xl.conf - XL Global/Host Configuration
4
5=head1 DESCRIPTION
6
7The F<xl.conf> file allows configuration of hostwide C<xl> toolstack
8options.
9
10For details of per-domain configuration options please see
11L<xl.cfg(5)>.
12
13=head1 SYNTAX
14
15The config file consists of a series of C<KEY=VALUE> pairs.
16
17A value C<VALUE> is one of:
18
19=over 4
20
21=item B<"STRING">
22
23A string, surrounded by either single or double quotes.
24
25=item B<NUMBER>
26
27A number, in either decimal, octal (using a C<0> prefix) or
28hexadecimal (using an C<0x> prefix).
29
30=item B<BOOLEAN>
31
32A C<NUMBER> interpreted as C<False> (C<0>) or C<True> (any other
33value).
34
35=item B<[ VALUE, VALUE, ... ]>
36
37A list of C<VALUES> of the above types. Lists are homogeneous and are
38not nested.
39
40=back
41
42The semantics of each C<KEY> defines which form of C<VALUE> is required.
43
44=head1 OPTIONS
45
46=over 4
47
48=item B<domid_policy="xen"|"random">
49
50Determines how domain-id is set when creating a new domain.
51
52If set to "xen" then the hypervisor will allocate new domain-id values on a sequential basis.
53
54If set to "random" then a random domain-id value will be chosen.
55
56Default: "xen"
57
58=item B<autoballoon="off"|"on"|"auto">
59
60If set to "on" then C<xl> will automatically reduce the amount of
61memory assigned to domain 0 in order to free memory for new domains.
62
63If set to "off" then C<xl> will not automatically reduce the amount of
64domain 0 memory.
65
66If set to "auto" then auto-ballooning will be disabled if the
67C<dom0_mem> option was provided on the Xen command line.
68
69You are strongly recommended to set this to C<"off"> (or C<"auto">) if
70you use the C<dom0_mem> hypervisor command line to reduce the amount
71of memory given to domain 0 by default.
72
73Default: C<"auto">
74
75=item B<run_hotplug_scripts=BOOLEAN>
76
77If disabled hotplug scripts will be called from udev, as it used to
78be in the previous releases. With the default option, hotplug scripts
79will be launched by xl directly.
80
81Default: C<1>
82
83=item B<lockfile="PATH">
84
85Sets the path to the lock file used by xl to serialise certain
86operations (primarily domain creation).
87
88Default: C</var/lock/xl>
89
90=item B<max_grant_frames=NUMBER>
91
92Sets the default value for the C<max_grant_frames> domain config value.
93
94Default: value of Xen command line B<gnttab_max_frames> parameter (or its
95default value if unspecified).
96
97=item B<max_maptrack_frames=NUMBER>
98
99Sets the default value for the C<max_maptrack_frames> domain config value.
100
101Default: value of Xen command line B<gnttab_max_maptrack_frames>
102parameter (or its default value if unspecified).
103
104=item B<max_grant_version=NUMBER>
105
106Sets the default value for the C<max_grant_version> domain config value.
107
108Default: maximum grant version supported by the hypervisor.
109
110=item B<vif.default.script="PATH">
111
112Configures the default hotplug script used by virtual network devices.
113
114The old B<vifscript> option is deprecated and should not be used.
115
116Default: C<@XEN_SCRIPT_DIR@/vif-bridge>
117
118=item B<vif.default.bridge="NAME">
119
120Configures the default bridge to set for virtual network devices.
121
122The old B<defaultbridge> option is deprecated and should not be used.
123
124Default: C<xenbr0>
125
126=item B<vif.default.backend="NAME">
127
128Configures the default backend to set for virtual network devices.
129
130Default: C<0>
131
132=item B<vif.default.gatewaydev="NAME">
133
134Configures the default gateway device to set for virtual network devices.
135
136Default: C<None>
137
138=item B<remus.default.netbufscript="PATH">
139
140Configures the default script used by Remus to setup network buffering.
141
142Default: C<@XEN_SCRIPT_DIR@/remus-netbuf-setup>
143
144=item B<colo.default.proxyscript="PATH">
145
146Configures the default script used by COLO to setup colo-proxy.
147
148Default: C<@XEN_SCRIPT_DIR@/colo-proxy-setup>
149
150=item B<output_format="json|sxp">
151
152Configures the default output format used by xl when printing "machine
153readable" information. The default is to use the C<JSON>
154L<https://www.json.org/> syntax. However for compatibility with the
155previous C<xm> toolstack this can be configured to use the old C<SXP>
156(S-Expression-like) syntax instead.
157
158Default: C<json>
159
160=item B<blkdev_start="NAME">
161
162Configures the name of the first block device to be used for temporary
163block device allocations by the toolstack.
164The default choice is "xvda".
165
166=item B<claim_mode=BOOLEAN>
167
168If this option is enabled then when a guest is created there will be an
169guarantee that there is memory available for the guest.
170The self-balloon mechanism can deflate/inflate the balloon
171quickly and the amount of free memory (which C<xl info> can show) is
172stale the moment it is printed. When claim is enabled a reservation for
173the amount of memory (see 'memory' in xl.conf(5)) is set, which is then
174reduced as the domain's memory is populated and eventually reaches zero.
175The free memory in C<xl info> is the combination of the hypervisor's
176free heap memory minus the outstanding claims value.
177
178If the reservation cannot be meet the guest creation fails immediately
179instead of taking seconds/minutes (depending on the size of the guest)
180while the guest is populated.
181
182Default: C<1>
183
184=over 4
185
186=item C<0>
187
188No claim is made. Memory population during guest creation will be
189attempted as normal and may fail due to memory exhaustion.
190
191=item C<1>
192
193Free memory as reported by the hypervisor is used for
194calculating whether there is enough memory free to launch a guest.
195This guarantees immediate feedback whether the guest can be launched due
196to memory exhaustion (which can take a long time to find out if launching
197massively huge guests).
198
199=back
200
201=item B<vm.cpumask>="CPULIST"
202
203=item B<vm.hvm.cpumask>="CPULIST"
204
205=item B<vm.pv.cpumask>="CPULIST"
206
207Global masks that are applied when creating guests and pinning vcpus
208to indicate which cpus they are allowed to run on.  Specifically,
209C<vm.cpumask> applies to all guest types, C<vm.hvm.cpumask> applies to
210both HVM and PVH guests and C<vm.pv.cpumask> applies to PV guests.
211
212The hard affinity of guest's vcpus are logical-AND'ed with respective
213masks. If the resulting affinity mask is empty, operation will fail.
214
215Use --ignore-global-affinity-masks to skip applying global masks.
216
217The default value for these masks are all 1's, i.e. all cpus are allowed.
218
219Due to bug(s), these options may not interact well with other options
220concerning CPU affinity. One example is CPU pools. Users should always double
221check that the required affinity has taken effect.
222
223=item B<bootloader_restrict=BOOLEAN>
224
225System wide default for whether the bootloader should be run in a restricted
226environment.  See L<xl.cfg(5)> B<bootloader_restrict> for more information on
227how to setup and use the option.
228
229=back
230
231=head1 SEE ALSO
232
233=over 4
234
235=item L<xl(1)>
236
237=item L<xl.cfg(5)>
238
239=item https://www.json.org/
240
241=back
242