1=encoding utf8
2
3=head1 NAME
4
5xl-network-configuration - XL Network Configuration Syntax
6
7
8=head1 SYNTAX
9
10This document specifies the xl config file format vif configuration
11option.  It has the following form:
12
13        vif = [ '<vifspec>', '<vifspec>', ... ]
14
15where each vifspec is in this form:
16
17        [<key>=<value>|<flag>,]
18
19For example:
20
21        'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
22        'mac=00:16:3E:74:34:32'
23        '' # The empty string
24
25These might be specified in the domain config file like this:
26
27        vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]
28
29More formally, the string is a series of comma-separated keyword/value
30pairs. All keywords are optional.
31
32Each device has a C<DEVID> which is its index within the vif list, starting from 0.
33
34
35=head1 Keywords
36
37
38=head2 mac
39
40If specified then this option specifies the MAC address inside the
41guest of this VIF device. The value is a 48-bit number represented as
42six groups of two hexadecimal digits, separated by colons (:).
43
44The default if this keyword is not specified is to be automatically
45generate a MAC address inside the space assigned to Xen's
46L<Organizationally Unique Identifier|https://en.wikipedia.org/wiki/Organizationally_Unique_Identifier> (00:16:3e).
47
48If you are choosing a MAC address then it is strongly recommend to
49follow one of the following strategies:
50
51=over
52
53=item *
54
55Generate a random sequence of 6 byte, set the locally administered
56bit (bit 2 of the first byte) and clear the multicast bit (bit 1
57of the first byte). In other words the first byte should have the
58bit pattern xxxxxx10 (where x is a randomly generated bit) and the
59remaining 5 bytes are randomly generated See
60[https://en.wikipedia.org/wiki/MAC_address] for more details the
61structure of a MAC address.
62
63
64=item *
65
66Allocate an address from within the space defined by your
67organization's OUI (if you have one) following your organization's
68procedures for doing so.
69
70
71=item *
72
73Allocate an address from within the space defined by Xen's OUI
74(00:16:3e). Taking care not to clash with other users of the
75physical network segment where this VIF will reside.
76
77
78=back
79
80If you have an OUI for your own use then that is the preferred
81strategy. Otherwise in general you should prefer to generate a random
82MAC and set the locally administered bit since this allows for more
83bits of randomness than using the Xen OUI.
84
85
86=head2 bridge
87
88Specifies the name of the network bridge which this VIF should be
89added to. The default is C<xenbr0>. The bridge must be configured using
90your distribution's network configuration tools. See the L<wiki|https://wiki.xenproject.org/wiki/Network_Configuration_Examples_(Xen_4.1%2B)>
91for guidance and examples.
92
93
94=head2 gatewaydev
95
96Specifies the name of the network interface which has an IP and which
97is in the network the VIF should communicate with. This is used in the host
98by the vif-route hotplug script. See L<wiki|https://wiki.xenproject.org/wiki/Vif-route> for guidance and
99examples.
100
101NOTE: netdev is a deprecated alias of this option.
102
103
104=head2 type
105
106This keyword is valid for HVM guests only.
107
108Specifies the type of device to valid values are:
109
110=over
111
112=item *
113
114C<ioemu> (default) -- this device will be provided as an emulate
115device to the guest and also as a paravirtualised device which the
116guest may choose to use instead if it has suitable drivers
117available.
118
119
120=item *
121
122C<vif> -- this device will be provided as a paravirtualised device
123only.
124
125
126=back
127
128
129=head2 model
130
131This keyword is valid for HVM guest devices with C<type=ioemu> only.
132
133Specifies the type device to emulated for this guest. Valid values
134are:
135
136=over
137
138=item *
139
140C<rtl8139> (default) -- Realtek RTL8139
141
142
143=item *
144
145C<e1000> -- Intel E1000
146
147
148=item *
149
150in principle any device supported by your device model
151
152
153=back
154
155
156=head2 vifname
157
158Specifies the backend device name for the virtual device.
159
160If the domain is an HVM domain then the associated emulated (tap)
161device will have a "-emu" suffice added.
162
163The default name for the virtual device is C<vifDOMID.DEVID> where
164C<DOMID> is the guest domain ID and C<DEVID> is the device
165number. Likewise the default tap name is C<vifDOMID.DEVID-emu>.
166
167
168=head2 script
169
170Specifies the hotplug script to run to configure this device (e.g. to
171add it to the relevant bridge). Defaults to
172C<@XEN_SCRIPT_DIR@/vif-bridge> but can be set to any script. Some example
173scripts are installed in C<@XEN_SCRIPT_DIR@>.
174
175Note on NetBSD HVM guests will ignore the script option for tap
176(emulated) interfaces and always use
177C<XEN_SCRIPT_DIR/qemu-ifup> to configure the interface in bridged mode.
178
179=head2 ip
180
181Specifies the IP address for the device, the default is not to
182specify an IP address.
183
184What, if any, effect this has depends on the hotplug script which is
185configured. A typically behaviour (exhibited by the example hotplug
186scripts) if set might be to configure firewall rules to allow only the
187specified IP address to be used by the guest (blocking all others).
188
189
190=head2 backend
191
192Specifies the backend domain which this device should attach to. This
193defaults to domain 0.  Specifying another domain requires setting up a
194driver domain which is outside the scope of this document.
195
196
197=head2 rate
198
199Specifies the rate at which the outgoing traffic will be limited to.
200The default if this keyword is not specified is unlimited.
201
202The rate may be specified as "/s" or optionally "/s@".
203
204=over
205
206=item *
207
208C<RATE> is in bytes and can accept suffixes:
209
210=over
211
212=item *
213
214GB, MB, KB, B for bytes.
215
216
217=item *
218
219Gb, Mb, Kb, b for bits.
220
221
222=back
223
224
225
226=item *
227
228C<INTERVAL> is in microseconds and can accept suffixes: ms, us, s.
229It determines the frequency at which the vif transmission credit
230is replenished. The default is 50ms.
231
232
233=back
234
235Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
236available credit will be equivalent of the traffic you would have done
237at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
238replenished every 20,000 us.
239
240For example:
241
242        'rate=10Mb/s' -- meaning up to 10 megabits every second
243        'rate=250KB/s' -- meaning up to 250 kilobytes every second
244        'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
245
246NOTE: The actual underlying limits of rate limiting are dependent
247on the underlying netback implementation.
248
249
250=head2 devid
251
252Specifies the devid manually instead of letting xl choose the lowest index available.
253
254NOTE: This should not be set unless you have a reason to.
255
256=head2 mtu
257
258Specifies the MTU (i.e. the maximum size of an IP payload, exclusing headers). The
259default value is 1500 but, if the VIF is attached to a bridge, it will be set to match
260unless overridden by this parameter.
261
262=head2 vlan
263
264Specifies the VLAN configuration. The format of this parameter is one or more
265VLAN IDs or ranges separated by forward slashes. Each term can be:
266
267=over
268
269=item *
270
271B<vlan> - a single VLAN ID in the range 1 to 4094. This can optionally followed
272by a B<p> to indicate the PVID or by a B<u> to indicate an untagged VLAN. C<p>
273implies B<u>.
274
275=item *
276
277B<vlan1>-B<vlan2> - a range of VLAN IDs from B<vlan1> to B<vlan2>, both between
2781 and 4094 and B<vlan1> being less than or equal to B<vlan2>. This can be
279optionally followed by a B<u> to indicate that the range of VLANs are untagged.
280
281=item *
282
283B<vlan>+B<offset>xB<count> - describing a range of VLAN IDs starting at B<vlan>
284with B<count> additional entries, each incremented by B<offset>. This can be
285optionally followed by a B<u> to indicate that the range of VLANs are untagged.
286
287=back
288
289Note, one VLAN ID must be marked as the PVID. In the case of a vlan
290specification consisting of a single VLAN ID (e.g. C<vlan=10>), the B<p> suffix
291may be omitted. Specifying more than one untagged VLAN ID is an advanced
292configuration - use with caution.
293
294For example:
295
296        'vlan=10' -- meaning a single VLAN that is the PVID.
297        'vlan=10p/20' -- VLAN 10 is the PVID and VLAN 20 is tagged.
298        'vlan=10p/100+10x4' -- VLANs 10, 100, 110, 120, 130, 140, 150.
299
300=head2 trusted / untrusted
301
302An advisory setting for the frontend driver on whether the backend should be
303trusted.  The frontend should deploy whatever protections it has available to
304prevent an untrusted backend from accessing guest data not related to the I/O
305processing or causing malfunction to the frontend or the whole domain.
306
307Note frontends can ignore such recommendation.
308