1 files changed, 260 insertions, 0 deletions
diff --git a/docs/man/xl-network-configuration.5.pod.in b/docs/man/xl-network-configuration.5.pod.in
new file mode 100644
index 0000000000..cf92d7960c
--- /dev/null
+++ b/docs/man/xl-network-configuration.5.pod.in
@@ -0,0 +1,260 @@
+=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.