1xl-network-configuration(5) Xen xl-network-configuration(5)
2
6 xl-network-configuration - XL Network Configuration Syntax
7
9 This document specifies the xl config file format vif configuration
10 option. It has the following form:
11 vif = [ '<vifspec>', '<vifspec>', ... ]
13 where each vifspec is in this form:
15 [<key>=<value>|<flag>,]
17 For example:
19 'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
21 'mac=00:16:3E:74:34:32'
22 '' # The empty string
23 These might be specified in the domain config file like this:
25 vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]
27 More formally, the string is a series of comma-separated keyword/value
29 pairs. All keywords are optional.
30 Each device has a "DEVID" which is its index within the vif list,
32 starting from 0.
33
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 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 If you are choosing a MAC address then it is strongly recommend to
47 follow one of the following strategies:
48 • 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 • 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 • 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 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 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 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 NOTE: netdev is a deprecated alias of this option.
84 type
86 This keyword is valid for HVM guests only.
87 Specifies the type of device to valid values are:
89 • "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 • "vif" -- this device will be provided as a paravirtualised device
96 only.
97 model
99 This keyword is valid for HVM guest devices with "type=ioemu" only.
100 Specifies the type device to emulated for this guest. Valid values are:
102 • "rtl8139" (default) -- Realtek RTL8139
104 • "e1000" -- Intel E1000
106 • in principle any device supported by your device model
108 vifname
110 Specifies the backend device name for the virtual device.
111 If the domain is an HVM domain then the associated emulated (tap)
113 device will have a "-emu" suffice added.
114 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 script
120 Specifies the hotplug script to run to configure this device (e.g. to
121 add it to the relevant bridge). Defaults to "XEN_SCRIPT_DIR/vif-bridge"
122 but can be set to any script. Some example scripts are installed in
123 "XEN_SCRIPT_DIR".
124 ip
126 Specifies the IP address for the device, the default is not to specify
127 an IP address.
128 What, if any, effect this has depends on the hotplug script which is
130 configured. A typically behaviour (exhibited by the example hotplug
131 scripts) if set might be to configure firewall rules to allow only the
132 specified IP address to be used by the guest (blocking all others).
133 backend
135 Specifies the backend domain which this device should attach to. This
136 defaults to domain 0. Specifying another domain requires setting up a
137 driver domain which is outside the scope of this document.
138 rate
140 Specifies the rate at which the outgoing traffic will be limited to.
141 The default if this keyword is not specified is unlimited.
142 The rate may be specified as "/s" or optionally "/s@".
144 • "RATE" is in bytes and can accept suffixes:
146 • GB, MB, KB, B for bytes.
148 • Gb, Mb, Kb, b for bits.
150 • "INTERVAL" is in microseconds and can accept suffixes: ms, us, s.
152 It determines the frequency at which the vif transmission credit is
153 replenished. The default is 50ms.
154 Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
156 available credit will be equivalent of the traffic you would have done
157 at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
158 replenished every 20,000 us.
159 For example:
161 'rate=10Mb/s' -- meaning up to 10 megabits every second
163 'rate=250KB/s' -- meaning up to 250 kilobytes every second
164 'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
165 NOTE: The actual underlying limits of rate limiting are dependent on
167 the underlying netback implementation.
168 devid
170 Specifies the devid manually instead of letting xl choose the lowest
171 index available.
172 NOTE: This should not be set unless you have a reason to.
1744.14.2 2021-05-04 xl-network-configuration(5)