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|http://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[http://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|http://wiki.xen.org/wiki/HostConfiguration/Networking>
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|http://wiki.xen.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
175
176=head2 ip
177
178Specifies the IP address for the device, the default is not to
179specify an IP address.
180
181What, if any, effect this has depends on the hotplug script which is
182configured. A typically behaviour (exhibited by the example hotplug
183scripts) if set might be to configure firewall rules to allow only the
184specified IP address to be used by the guest (blocking all others).
185
186
187=head2 backend
188
189Specifies the backend domain which this device should attach to. This
190defaults to domain 0.  Specifying another domain requires setting up a
191driver domain which is outside the scope of this document.
192
193
194=head2 rate
195
196Specifies the rate at which the outgoing traffic will be limited to.
197The default if this keyword is not specified is unlimited.
198
199The rate may be specified as "/s" or optionally "/s@".
200
201=over
202
203=item *
204
205C<RATE> is in bytes and can accept suffixes:
206
207=over
208
209=item *
210
211GB, MB, KB, B for bytes.
212
213
214=item *
215
216Gb, Mb, Kb, b for bits.
217
218
219=back
220
221
222
223=item *
224
225C<INTERVAL> is in microseconds and can accept suffixes: ms, us, s.
226It determines the frequency at which the vif transmission credit
227is replenished. The default is 50ms.
228
229
230=back
231
232Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
233available credit will be equivalent of the traffic you would have done
234at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
235replenished every 20,000 us.
236
237For example:
238
239        'rate=10Mb/s' -- meaning up to 10 megabits every second
240        'rate=250KB/s' -- meaning up to 250 kilobytes every second
241        'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
242
243NOTE: The actual underlying limits of rate limiting are dependent
244on the underlying netback implementation.
245
246
247=head2 devid
248
249Specifies the devid manually instead of letting xl choose the lowest index available.
250
251NOTE: This should not be set unless you have a reason to.
252