xl-network-configuration(5)

💅 xl-network-configuration — XL Network Configuration Syntax 🦋

Okay bestie, so this is the manual page for xl-network-configuration from the Xen fam — it's literally the whole rundown on how you write the vif configuration syntax for xl config files. Sit down, grab a strawberry drink 🍓, and let's get into it.

---

✨ SYNTAX ✨

So the doc specifies the xl config file format vif configuration option, and it looks like this:

vif = [ '<vifspec>', '<vifspec>', ... ]

and each individual vifspec is shaped like this:

[<key>=<value>|<flag>,]

Like, for example:

'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
'mac=00:16:3E:74:34:32'
'' # The empty string

And you'd drop those into the domain config file like this, no cap:

vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]

Being all formal about it 💅 — the string is a series of comma-separated keyword/value pairs. All keywords are optional. Every single one. Iconic.

Each device has a "DEVID" which is literally its index within the vif list, and it starts from 0. Periodt.

---

🎀 Keywords 🎀

mac

If you specify this, it sets the MAC address inside the guest for this VIF device. The value is a 48-bit number written as six groups of two hexadecimal digits, separated by colons (:).

The default, if you don't say anything, is that a MAC address gets automatically generated inside the space assigned to Xen's Organizationally Unique Identifier (that's 00:16:3e).

If you are picking a MAC address yourself, it is strongly recommend to follow one of these strategies, bestie:

• Generate a random sequence of 6 bytes, 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 on 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). Just take care not to clash with other users of the physical network segment where this VIF will reside 🙈.

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

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 for guidance and examples 👑

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 for guidance and examples.

NOTE: netdev is a deprecated alias of this option. (Yes, deprecated. Use the new one, bestie 💀)

type

This keyword is valid for HVM guests only.

Specifies the type of device. 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.

model

This keyword is valid for HVM guest devices with type=ioemu only.

Specifies the type of device to be emulated for this guest. Valid values are:

• "rtl8139" (default) — Realtek RTL8139
• "e1000" — Intel E1000
• in principle any device supported by your device model ✨

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 suffix 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".

script

Specifies the hotplug script to run to configure this device (e.g. to add it to the relevant bridge). Defaults to /etc/xen/scripts/vif-bridge but can be set to any script. Some example scripts are installed in /etc/xen/scripts.

Note: on NetBSD, HVM guests will ignore the script option for tap (emulated) interfaces and always use XEN_SCRIPT_DIR/qemu-ifup to configure the interface in bridged mode. Just so you know 🫶

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 typical 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). Lowkey protective, honestly 🔥

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. (So don't come for this page about it 💀)

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.

• 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.

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. Math is mathing ✨

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. No promises beyond that, bestie 🙈

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. Fr fr, leave it alone unless you know why you're there.

mtu

Specifies the MTU (i.e. the maximum size of an IP payload, excluding 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.

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:

• vlan — a single VLAN ID in the range 1 to 4094. This can optionally be followed by a p to indicate the PVID or by a u to indicate an untagged VLAN. p implies u.
• vlan1-vlan2 — a range of VLAN IDs from vlan1 to vlan2, both between 1 and 4094 and vlan1 being less than or equal to vlan2. This can be optionally followed by a u to indicate that the range of VLANs are untagged.
• vlan+offsetxcount — describing a range of VLAN IDs starting at vlan with count additional entries, each incremented by offset. This can be optionally followed by a u to indicate that the range of VLANs are untagged.

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. "vlan=10"), the 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.

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. It's advisory, bestie — main character frontends do what they want 💅

---

Okay that's the whole page, you ate that 🫶✨ This was xl-network-configuration(5) — the Xen source, version 4.20.5-pre, dated 2026-10-16. Go forth and configure your vifs, icon 👑💜