mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 02:01:24 +01:00
Leigh Brown
0cc01c603f
Update parse_nic_config() to support a new `vlan' keyword. This keyword specifies the VLAN configuration to assign to the VIF when attaching it to the bridge port, on operating systems that support the capability (e.g. Linux). The vlan keyword will allow one or more VLANs to be configured on the VIF when adding it to the bridge port. This will be done by the vif-bridge script and functions. Signed-off-by: Leigh Brown <leigh@solinno.co.uk> Reviewed-by: Jason Andryuk <jandryuk@gmail.com>
308 lines
8.2 KiB
Plaintext
308 lines
8.2 KiB
Plaintext
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
xl-network-configuration - XL Network Configuration Syntax
|
|
|
|
|
|
=head1 SYNTAX
|
|
|
|
This document specifies the xl config file format vif configuration
|
|
option. It has the following form:
|
|
|
|
vif = [ '<vifspec>', '<vifspec>', ... ]
|
|
|
|
where each vifspec is in this form:
|
|
|
|
[<key>=<value>|<flag>,]
|
|
|
|
For example:
|
|
|
|
'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
|
|
'mac=00:16:3E:74:34:32'
|
|
'' # The empty string
|
|
|
|
These might be specified in the domain config file like this:
|
|
|
|
vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]
|
|
|
|
More formally, the string is a series of comma-separated keyword/value
|
|
pairs. All keywords are optional.
|
|
|
|
Each device has a C<DEVID> which is its index within the vif list, starting from 0.
|
|
|
|
|
|
=head1 Keywords
|
|
|
|
|
|
=head2 mac
|
|
|
|
If specified then this option specifies the MAC address inside the
|
|
guest of this VIF device. The value is a 48-bit number represented as
|
|
six groups of two hexadecimal digits, separated by colons (:).
|
|
|
|
The default if this keyword is not specified is to be automatically
|
|
generate a MAC address inside the space assigned to Xen's
|
|
L<Organizationally Unique Identifier|https://en.wikipedia.org/wiki/Organizationally_Unique_Identifier> (00:16:3e).
|
|
|
|
If you are choosing a MAC address then it is strongly recommend to
|
|
follow one of the following strategies:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
Generate a random sequence of 6 byte, set the locally administered
|
|
bit (bit 2 of the first byte) and clear the multicast bit (bit 1
|
|
of the first byte). In other words the first byte should have the
|
|
bit pattern xxxxxx10 (where x is a randomly generated bit) and the
|
|
remaining 5 bytes are randomly generated See
|
|
[https://en.wikipedia.org/wiki/MAC_address] for more details the
|
|
structure of a MAC address.
|
|
|
|
|
|
=item *
|
|
|
|
Allocate an address from within the space defined by your
|
|
organization's OUI (if you have one) following your organization's
|
|
procedures for doing so.
|
|
|
|
|
|
=item *
|
|
|
|
Allocate an address from within the space defined by Xen's OUI
|
|
(00:16:3e). Taking care not to clash with other users of the
|
|
physical network segment where this VIF will reside.
|
|
|
|
|
|
=back
|
|
|
|
If you have an OUI for your own use then that is the preferred
|
|
strategy. Otherwise in general you should prefer to generate a random
|
|
MAC and set the locally administered bit since this allows for more
|
|
bits of randomness than using the Xen OUI.
|
|
|
|
|
|
=head2 bridge
|
|
|
|
Specifies the name of the network bridge which this VIF should be
|
|
added to. The default is C<xenbr0>. The bridge must be configured using
|
|
your distribution's network configuration tools. See the L<wiki|https://wiki.xenproject.org/wiki/Network_Configuration_Examples_(Xen_4.1%2B)>
|
|
for guidance and examples.
|
|
|
|
|
|
=head2 gatewaydev
|
|
|
|
Specifies the name of the network interface which has an IP and which
|
|
is in the network the VIF should communicate with. This is used in the host
|
|
by the vif-route hotplug script. See L<wiki|https://wiki.xenproject.org/wiki/Vif-route> for guidance and
|
|
examples.
|
|
|
|
NOTE: netdev is a deprecated alias of this option.
|
|
|
|
|
|
=head2 type
|
|
|
|
This keyword is valid for HVM guests only.
|
|
|
|
Specifies the type of device to valid values are:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<ioemu> (default) -- this device will be provided as an emulate
|
|
device to the guest and also as a paravirtualised device which the
|
|
guest may choose to use instead if it has suitable drivers
|
|
available.
|
|
|
|
|
|
=item *
|
|
|
|
C<vif> -- this device will be provided as a paravirtualised device
|
|
only.
|
|
|
|
|
|
=back
|
|
|
|
|
|
=head2 model
|
|
|
|
This keyword is valid for HVM guest devices with C<type=ioemu> only.
|
|
|
|
Specifies the type device to emulated for this guest. Valid values
|
|
are:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<rtl8139> (default) -- Realtek RTL8139
|
|
|
|
|
|
=item *
|
|
|
|
C<e1000> -- Intel E1000
|
|
|
|
|
|
=item *
|
|
|
|
in principle any device supported by your device model
|
|
|
|
|
|
=back
|
|
|
|
|
|
=head2 vifname
|
|
|
|
Specifies the backend device name for the virtual device.
|
|
|
|
If the domain is an HVM domain then the associated emulated (tap)
|
|
device will have a "-emu" suffice added.
|
|
|
|
The default name for the virtual device is C<vifDOMID.DEVID> where
|
|
C<DOMID> is the guest domain ID and C<DEVID> is the device
|
|
number. Likewise the default tap name is C<vifDOMID.DEVID-emu>.
|
|
|
|
|
|
=head2 script
|
|
|
|
Specifies the hotplug script to run to configure this device (e.g. to
|
|
add it to the relevant bridge). Defaults to
|
|
C<@XEN_SCRIPT_DIR@/vif-bridge> but can be set to any script. Some example
|
|
scripts are installed in C<@XEN_SCRIPT_DIR@>.
|
|
|
|
Note on NetBSD HVM guests will ignore the script option for tap
|
|
(emulated) interfaces and always use
|
|
C<XEN_SCRIPT_DIR/qemu-ifup> to configure the interface in bridged mode.
|
|
|
|
=head2 ip
|
|
|
|
Specifies the IP address for the device, the default is not to
|
|
specify an IP address.
|
|
|
|
What, if any, effect this has depends on the hotplug script which is
|
|
configured. A typically behaviour (exhibited by the example hotplug
|
|
scripts) if set might be to configure firewall rules to allow only the
|
|
specified IP address to be used by the guest (blocking all others).
|
|
|
|
|
|
=head2 backend
|
|
|
|
Specifies the backend domain which this device should attach to. This
|
|
defaults to domain 0. Specifying another domain requires setting up a
|
|
driver domain which is outside the scope of this document.
|
|
|
|
|
|
=head2 rate
|
|
|
|
Specifies the rate at which the outgoing traffic will be limited to.
|
|
The default if this keyword is not specified is unlimited.
|
|
|
|
The rate may be specified as "/s" or optionally "/s@".
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<RATE> is in bytes and can accept suffixes:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
GB, MB, KB, B for bytes.
|
|
|
|
|
|
=item *
|
|
|
|
Gb, Mb, Kb, b for bits.
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
=item *
|
|
|
|
C<INTERVAL> is in microseconds and can accept suffixes: ms, us, s.
|
|
It determines the frequency at which the vif transmission credit
|
|
is replenished. The default is 50ms.
|
|
|
|
|
|
=back
|
|
|
|
Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
|
|
available credit will be equivalent of the traffic you would have done
|
|
at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
|
|
replenished every 20,000 us.
|
|
|
|
For example:
|
|
|
|
'rate=10Mb/s' -- meaning up to 10 megabits every second
|
|
'rate=250KB/s' -- meaning up to 250 kilobytes every second
|
|
'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
|
|
|
|
NOTE: The actual underlying limits of rate limiting are dependent
|
|
on the underlying netback implementation.
|
|
|
|
|
|
=head2 devid
|
|
|
|
Specifies the devid manually instead of letting xl choose the lowest index available.
|
|
|
|
NOTE: This should not be set unless you have a reason to.
|
|
|
|
=head2 mtu
|
|
|
|
Specifies the MTU (i.e. the maximum size of an IP payload, exclusing headers). The
|
|
default value is 1500 but, if the VIF is attached to a bridge, it will be set to match
|
|
unless overridden by this parameter.
|
|
|
|
=head2 vlan
|
|
|
|
Specifies the VLAN configuration. The format of this parameter is one or more
|
|
VLAN IDs or ranges separated by forward slashes. Each term can be:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
B<vlan> - a single VLAN ID in the range 1 to 4094. This can optionally followed
|
|
by a B<p> to indicate the PVID or by a B<u> to indicate an untagged VLAN. C<p>
|
|
implies B<u>.
|
|
|
|
=item *
|
|
|
|
B<vlan1>-B<vlan2> - a range of VLAN IDs from B<vlan1> to B<vlan2>, both between
|
|
1 and 4094 and B<vlan1> being less than or equal to B<vlan2>. This can be
|
|
optionally followed by a B<u> to indicate that the range of VLANs are untagged.
|
|
|
|
=item *
|
|
|
|
B<vlan>+B<offset>xB<count> - describing a range of VLAN IDs starting at B<vlan>
|
|
with B<count> additional entries, each incremented by B<offset>. This can be
|
|
optionally followed by a B<u> to indicate that the range of VLANs are untagged.
|
|
|
|
=back
|
|
|
|
Note, one VLAN ID must be marked as the PVID. In the case of a vlan
|
|
specification consisting of a single VLAN ID (e.g. C<vlan=10>), the B<p> suffix
|
|
may be omitted. Specifying more than one untagged VLAN ID is an advanced
|
|
configuration - use with caution.
|
|
|
|
For example:
|
|
|
|
'vlan=10' -- meaning a single VLAN that is the PVID.
|
|
'vlan=10p/20' -- VLAN 10 is the PVID and VLAN 20 is tagged.
|
|
'vlan=10p/100+10x4' -- VLANs 10, 100, 110, 120, 130, 140, 150.
|
|
|
|
=head2 trusted / untrusted
|
|
|
|
An advisory setting for the frontend driver on whether the backend should be
|
|
trusted. The frontend should deploy whatever protections it has available to
|
|
prevent an untrusted backend from accessing guest data not related to the I/O
|
|
processing or causing malfunction to the frontend or the whole domain.
|
|
|
|
Note frontends can ignore such recommendation.
|