1xl-network-configuration(5)           Xen          xl-network-configuration(5)
2
3
4

NAME

6       xl-network-configuration - XL Network Configuration Syntax
7

SYNTAX

9       This document specifies the xl config file format vif configuration
10       option.  It has the following form:
11
12               vif = [ '<vifspec>', '<vifspec>', ... ]
13
14       where each vifspec is in this form:
15
16               [<key>=<value>|<flag>,]
17
18       For example:
19
20               'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
21               'mac=00:16:3E:74:34:32'
22               '' # The empty string
23
24       These might be specified in the domain config file like this:
25
26               vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]
27
28       More formally, the string is a series of comma-separated keyword/value
29       pairs. All keywords are optional.
30
31       Each device has a "DEVID" which is its index within the vif list,
32       starting from 0.
33

Keywords

35   mac
36       If specified then this option specifies the MAC address inside the
37       guest of this VIF device. The value is a 48-bit number represented as
38       six groups of two hexadecimal digits, separated by colons (:).
39
40       The default if this keyword is not specified is to be automatically
41       generate a MAC address inside the space assigned to Xen's
42       Organizationally Unique Identifier
43       <https://en.wikipedia.org/wiki/Organizationally_Unique_Identifier>
44       (00:16:3e).
45
46       If you are choosing a MAC address then it is strongly recommend to
47       follow one of the following strategies:
48
49       •   Generate a random sequence of 6 byte, set the locally administered
50           bit (bit 2 of the first byte) and clear the multicast bit (bit 1 of
51           the first byte). In other words the first byte should have the bit
52           pattern xxxxxx10 (where x is a randomly generated bit) and the
53           remaining 5 bytes are randomly generated See
54           [https://en.wikipedia.org/wiki/MAC_address] for more details the
55           structure of a MAC address.
56
57       •   Allocate an address from within the space defined by your
58           organization's OUI (if you have one) following your organization's
59           procedures for doing so.
60
61       •   Allocate an address from within the space defined by Xen's OUI
62           (00:16:3e). Taking care not to clash with other users of the
63           physical network segment where this VIF will reside.
64
65       If you have an OUI for your own use then that is the preferred
66       strategy. Otherwise in general you should prefer to generate a random
67       MAC and set the locally administered bit since this allows for more
68       bits of randomness than using the Xen OUI.
69
70   bridge
71       Specifies the name of the network bridge which this VIF should be added
72       to. The default is "xenbr0". The bridge must be configured using your
73       distribution's network configuration tools. See the wiki
74       <https://wiki.xenproject.org/wiki/Network_Configuration_Examples_(Xen_4.1%2B)>
75       for guidance and examples.
76
77   gatewaydev
78       Specifies the name of the network interface which has an IP and which
79       is in the network the VIF should communicate with. This is used in the
80       host by the vif-route hotplug script. See wiki
81       <https://wiki.xenproject.org/wiki/Vif-route> for guidance and examples.
82
83       NOTE: netdev is a deprecated alias of this option.
84
85   type
86       This keyword is valid for HVM guests only.
87
88       Specifies the type of device to valid values are:
89
90       •   "ioemu" (default) -- this device will be provided as an emulate
91           device to the guest and also as a paravirtualised device which the
92           guest may choose to use instead if it has suitable drivers
93           available.
94
95       •   "vif" -- this device will be provided as a paravirtualised device
96           only.
97
98   model
99       This keyword is valid for HVM guest devices with "type=ioemu" only.
100
101       Specifies the type device to emulated for this guest. Valid values are:
102
103       •   "rtl8139" (default) -- Realtek RTL8139
104
105       •   "e1000" -- Intel E1000
106
107       •   in principle any device supported by your device model
108
109   vifname
110       Specifies the backend device name for the virtual device.
111
112       If the domain is an HVM domain then the associated emulated (tap)
113       device will have a "-emu" suffice added.
114
115       The default name for the virtual device is "vifDOMID.DEVID" where
116       "DOMID" is the guest domain ID and "DEVID" is the device number.
117       Likewise the default tap name is "vifDOMID.DEVID-emu".
118
119   script
120       Specifies the hotplug script to run to configure this device (e.g. to
121       add it to the relevant bridge). Defaults to
122       "/etc/xen/scripts/vif-bridge" but can be set to any script. Some
123       example scripts are installed in "/etc/xen/scripts".
124
125       Note on NetBSD HVM guests will ignore the script option for tap
126       (emulated) interfaces and always use "XEN_SCRIPT_DIR/qemu-ifup" to
127       configure the interface in bridged mode.
128
129   ip
130       Specifies the IP address for the device, the default is not to specify
131       an IP address.
132
133       What, if any, effect this has depends on the hotplug script which is
134       configured. A typically behaviour (exhibited by the example hotplug
135       scripts) if set might be to configure firewall rules to allow only the
136       specified IP address to be used by the guest (blocking all others).
137
138   backend
139       Specifies the backend domain which this device should attach to. This
140       defaults to domain 0.  Specifying another domain requires setting up a
141       driver domain which is outside the scope of this document.
142
143   rate
144       Specifies the rate at which the outgoing traffic will be limited to.
145       The default if this keyword is not specified is unlimited.
146
147       The rate may be specified as "/s" or optionally "/s@".
148
149       •   "RATE" is in bytes and can accept suffixes:
150
151           •   GB, MB, KB, B for bytes.
152
153           •   Gb, Mb, Kb, b for bits.
154
155       •   "INTERVAL" is in microseconds and can accept suffixes: ms, us, s.
156           It determines the frequency at which the vif transmission credit is
157           replenished. The default is 50ms.
158
159       Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
160       available credit will be equivalent of the traffic you would have done
161       at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
162       replenished every 20,000 us.
163
164       For example:
165
166               'rate=10Mb/s' -- meaning up to 10 megabits every second
167               'rate=250KB/s' -- meaning up to 250 kilobytes every second
168               'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
169
170       NOTE: The actual underlying limits of rate limiting are dependent on
171       the underlying netback implementation.
172
173   devid
174       Specifies the devid manually instead of letting xl choose the lowest
175       index available.
176
177       NOTE: This should not be set unless you have a reason to.
178
179   mtu
180       Specifies the MTU (i.e. the maximum size of an IP payload, exclusing
181       headers). The default value is 1500 but, if the VIF is attached to a
182       bridge, it will be set to match unless overridden by this parameter.
183
184   trusted / untrusted
185       An advisory setting for the frontend driver on whether the backend
186       should be trusted.  The frontend should deploy whatever protections it
187       has available to prevent an untrusted backend from accessing guest data
188       not related to the I/O processing or causing malfunction to the
189       frontend or the whole domain.
190
191       Note frontends can ignore such recommendation.
192
193
194
1954.17.2                            2023-11-14       xl-network-configuration(5)
Impressum