.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "xl-network-configuration 5" .TH xl-network-configuration 5 "2023-03-23" "4.14.5" "Xen" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" xl\-network\-configuration \- XL Network Configuration Syntax .SH "SYNTAX" .IX Header "SYNTAX" This document specifies the xl config file format vif configuration option. It has the following form: .PP .Vb 1 \& vif = [ \*(Aq\*(Aq, \*(Aq\*(Aq, ... ] .Ve .PP where each vifspec is in this form: .PP .Vb 1 \& [=|,] .Ve .PP For example: .PP .Vb 3 \& \*(Aqmac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0\*(Aq \& \*(Aqmac=00:16:3E:74:34:32\*(Aq \& \*(Aq\*(Aq # The empty string .Ve .PP These might be specified in the domain config file like this: .PP .Vb 1 \& vif = [ \*(Aqmac=00:16:3E:74:34:32\*(Aq, \*(Aqmac=00:16:3e:5f:48:e4,bridge=xenbr1\*(Aq ] .Ve .PP More formally, the string is a series of comma-separated keyword/value pairs. All keywords are optional. .PP Each device has a \f(CW\*(C`DEVID\*(C'\fR which is its index within the vif list, starting from 0. .SH "Keywords" .IX Header "Keywords" .SS "mac" .IX Subsection "mac" If specified then this option specifies the \s-1MAC\s0 address inside the guest of this \s-1VIF\s0 device. The value is a 48\-bit number represented as six groups of two hexadecimal digits, separated by colons (:). .PP The default if this keyword is not specified is to be automatically generate a \s-1MAC\s0 address inside the space assigned to Xen's Organizationally Unique Identifier (00:16:3e). .PP If you are choosing a \s-1MAC\s0 address then it is strongly recommend to follow one of the following strategies: .IP "\(bu" 4 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 \s-1MAC\s0 address. .IP "\(bu" 4 Allocate an address from within the space defined by your organization's \s-1OUI\s0 (if you have one) following your organization's procedures for doing so. .IP "\(bu" 4 Allocate an address from within the space defined by Xen's \s-1OUI\s0 (00:16:3e). Taking care not to clash with other users of the physical network segment where this \s-1VIF\s0 will reside. .PP If you have an \s-1OUI\s0 for your own use then that is the preferred strategy. Otherwise in general you should prefer to generate a random \&\s-1MAC\s0 and set the locally administered bit since this allows for more bits of randomness than using the Xen \s-1OUI.\s0 .SS "bridge" .IX Subsection "bridge" Specifies the name of the network bridge which this \s-1VIF\s0 should be added to. The default is \f(CW\*(C`xenbr0\*(C'\fR. The bridge must be configured using your distribution's network configuration tools. See the wiki for guidance and examples. .SS "gatewaydev" .IX Subsection "gatewaydev" Specifies the name of the network interface which has an \s-1IP\s0 and which is in the network the \s-1VIF\s0 should communicate with. This is used in the host by the vif-route hotplug script. See wiki for guidance and examples. .PP \&\s-1NOTE:\s0 netdev is a deprecated alias of this option. .SS "type" .IX Subsection "type" This keyword is valid for \s-1HVM\s0 guests only. .PP Specifies the type of device to valid values are: .IP "\(bu" 4 \&\f(CW\*(C`ioemu\*(C'\fR (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. .IP "\(bu" 4 \&\f(CW\*(C`vif\*(C'\fR \*(-- this device will be provided as a paravirtualised device only. .SS "model" .IX Subsection "model" This keyword is valid for \s-1HVM\s0 guest devices with \f(CW\*(C`type=ioemu\*(C'\fR only. .PP Specifies the type device to emulated for this guest. Valid values are: .IP "\(bu" 4 \&\f(CW\*(C`rtl8139\*(C'\fR (default) \*(-- Realtek \s-1RTL8139\s0 .IP "\(bu" 4 \&\f(CW\*(C`e1000\*(C'\fR \*(-- Intel E1000 .IP "\(bu" 4 in principle any device supported by your device model .SS "vifname" .IX Subsection "vifname" Specifies the backend device name for the virtual device. .PP If the domain is an \s-1HVM\s0 domain then the associated emulated (tap) device will have a \*(L"\-emu\*(R" suffice added. .PP The default name for the virtual device is \f(CW\*(C`vifDOMID.DEVID\*(C'\fR where \&\f(CW\*(C`DOMID\*(C'\fR is the guest domain \s-1ID\s0 and \f(CW\*(C`DEVID\*(C'\fR is the device number. Likewise the default tap name is \f(CW\*(C`vifDOMID.DEVID\-emu\*(C'\fR. .SS "script" .IX Subsection "script" Specifies the hotplug script to run to configure this device (e.g. to add it to the relevant bridge). Defaults to \&\f(CW\*(C`XEN_SCRIPT_DIR/vif\-bridge\*(C'\fR but can be set to any script. Some example scripts are installed in \f(CW\*(C`XEN_SCRIPT_DIR\*(C'\fR. .SS "ip" .IX Subsection "ip" Specifies the \s-1IP\s0 address for the device, the default is not to specify an \s-1IP\s0 address. .PP 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 \s-1IP\s0 address to be used by the guest (blocking all others). .SS "backend" .IX Subsection "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. .SS "rate" .IX Subsection "rate" Specifies the rate at which the outgoing traffic will be limited to. The default if this keyword is not specified is unlimited. .PP The rate may be specified as \*(L"/s\*(R" or optionally \*(L"/s@\*(R". .IP "\(bu" 4 \&\f(CW\*(C`RATE\*(C'\fR is in bytes and can accept suffixes: .RS 4 .IP "\(bu" 4 \&\s-1GB, MB, KB, B\s0 for bytes. .IP "\(bu" 4 Gb, Mb, Kb, b for bits. .RE .RS 4 .RE .IP "\(bu" 4 \&\f(CW\*(C`INTERVAL\*(C'\fR 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. .PP Vif rate limiting is credit-based. It means that for \*(L"1MB/s@20ms\*(R", the available credit will be equivalent of the traffic you would have done at \*(L"1MB/s\*(R" during 20ms. This will results in a credit of 20,000 bytes replenished every 20,000 us. .PP For example: .PP .Vb 3 \& \*(Aqrate=10Mb/s\*(Aq \-\- meaning up to 10 megabits every second \& \*(Aqrate=250KB/s\*(Aq \-\- meaning up to 250 kilobytes every second \& \*(Aqrate=1MB/s@20ms\*(Aq \-\- meaning 20,000 bytes in every 20 millisecond period .Ve .PP \&\s-1NOTE:\s0 The actual underlying limits of rate limiting are dependent on the underlying netback implementation. .SS "devid" .IX Subsection "devid" Specifies the devid manually instead of letting xl choose the lowest index available. .PP \&\s-1NOTE:\s0 This should not be set unless you have a reason to.