mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 10:11:27 +01:00
docs: add pod variant of xl-network-configuration.5
Convert source for xl-network-configuration.5 from markdown to pod. This removes the buildtime requirement for pandoc, and subsequently the need for ghc, in the chain for BuildRequires of xen.rpm. Signed-off-by: Olaf Hering <olaf@aepfle.de> Acked-by: Wei Liu <wei.liu2@citrix.com>
This commit is contained in:
Olaf Hering authored and Wei Liu committed
1 parent
4359b86f31
commit
458df9f374
1 file changed
+137
-59
+137
-59
@@ -1,6 +1,11 @@
|
||||
# XL Network Configuration
|
||||
=encoding utf8
|
||||
|
||||
## Syntax Overview
|
||||
=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:
|
||||
@@ -8,7 +13,7 @@ option. It has the following form:
|
||||
vif = [ '<vifspec>', '<vifspec>', ... ]
|
||||
|
||||
where each vifspec is in this form:
|
||||
|
||||
|
||||
[<key>=<value>|<flag>,]
|
||||
|
||||
For example:
|
||||
@@ -24,11 +29,13 @@ These might be specified in the domain config file like this:
|
||||
More formally, the string is a series of comma-separated keyword/value
|
||||
pairs. All keywords are optional.
|
||||
|
||||
Each device has a `DEVID` which is its index within the vif list, starting from 0.
|
||||
Each device has a C<DEVID> which is its index within the vif list, starting from 0.
|
||||
|
||||
## Keywords
|
||||
|
||||
### mac
|
||||
=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
|
||||
@@ -36,89 +43,137 @@ 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
|
||||
[Organizationally Unique Identifier][oui] (00:16:3e).
|
||||
L<Organizationally Unique Identifier|http://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:
|
||||
|
||||
* 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
|
||||
[http://en.wikipedia.org/wiki/MAC_address] for more details the
|
||||
structure of a MAC address.
|
||||
* 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.
|
||||
* 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.
|
||||
=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
|
||||
[http://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.
|
||||
|
||||
### bridge
|
||||
|
||||
=head2 bridge
|
||||
|
||||
Specifies the name of the network bridge which this VIF should be
|
||||
added to. The default is `xenbr0`. The bridge must be configured using
|
||||
your distribution's network configuration tools. See the [wiki][net]
|
||||
added to. The default is C<xenbr0>. The bridge must be configured using
|
||||
your distribution's network configuration tools. See the L<wiki|http://wiki.xen.org/wiki/HostConfiguration/Networking>
|
||||
for guidance and examples.
|
||||
|
||||
### gatewaydev
|
||||
|
||||
=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 [wiki][vifroute] for guidance and
|
||||
by the vif-route hotplug script. See L<wiki|http://wiki.xen.org/wiki/Vif-route> for guidance and
|
||||
examples.
|
||||
|
||||
NOTE: netdev is a deprecated alias of this option.
|
||||
|
||||
### type
|
||||
|
||||
=head2 type
|
||||
|
||||
This keyword is valid for HVM guests only.
|
||||
|
||||
Specifies the type of device to valid values are:
|
||||
|
||||
* `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.
|
||||
* `vif` -- this device will be provided as a paravirtualised device
|
||||
only.
|
||||
=over
|
||||
|
||||
### model
|
||||
=item *
|
||||
|
||||
This keyword is valid for HVM guest devices with `type=ioemu` only.
|
||||
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:
|
||||
|
||||
* `rtl8139` (default) -- Realtek RTL8139
|
||||
* `e1000` -- Intel E1000
|
||||
* in principle any device supported by your device model
|
||||
=over
|
||||
|
||||
### vifname
|
||||
=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 `vifDOMID.DEVID` where
|
||||
`DOMID` is the guest domain ID and `DEVID` is the device
|
||||
number. Likewise the default tap name is `vifDOMID.DEVID-emu`.
|
||||
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>.
|
||||
|
||||
### script
|
||||
|
||||
=head2 script
|
||||
|
||||
Specifies the hotplug script to run to configure this device (e.g. to
|
||||
add it to the relevant bridge). Defaults to
|
||||
`XEN_SCRIPT_DIR/vif-bridge` but can be set to any script. Some example
|
||||
scripts are installed in `XEN_SCRIPT_DIR`.
|
||||
C<XEN_SCRIPT_DIR/vif-bridge> but can be set to any script. Some example
|
||||
scripts are installed in C<XEN_SCRIPT_DIR>.
|
||||
|
||||
### ip
|
||||
|
||||
=head2 ip
|
||||
|
||||
Specifies the IP address for the device, the default is not to
|
||||
specify an IP address.
|
||||
@@ -128,25 +183,51 @@ 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).
|
||||
|
||||
### backend
|
||||
|
||||
=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.
|
||||
|
||||
### rate
|
||||
|
||||
=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 "<RATE>/s" or optionally "<RATE>/s@<INTERVAL>".
|
||||
The rate may be specified as "/s" or optionally "/s@".
|
||||
|
||||
* `RATE` is in bytes and can accept suffixes:
|
||||
* GB, MB, KB, B for bytes.
|
||||
* Gb, Mb, Kb, b for bits.
|
||||
* `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.
|
||||
=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
|
||||
@@ -162,12 +243,9 @@ For example:
|
||||
NOTE: The actual underlying limits of rate limiting are dependent
|
||||
on the underlying netback implementation.
|
||||
|
||||
### devid
|
||||
|
||||
=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.
|
||||
|
||||
[oui]: http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier
|
||||
[net]: http://wiki.xen.org/wiki/HostConfiguration/Networking
|
||||
[vifroute]: http://wiki.xen.org/wiki/Vif-route
|
||||