Type: nic
▶ Watch on YouTube (opens in a new tab)
Note
Thenicdevice type is supported for both containers and VMs.
NICs support hotplugging for both containers and VMs (with the exception of theipvlanNIC type).
Network devices, also referred to as Network Interface Controllers or NICs, supply a connection to a network. LXD supports several different types of network devices (NIC types).
nictype vs. network
When adding a network device to an instance, there are two methods to specify the type of device that you want to add: through the nictype device option or the network device option.
These two device options are mutually exclusive, and you can specify only one of them when you create a device. However, note that when you specify the network option, the nictype option is derived automatically from the network type.
nictype
When using the nictype device option, you can specify a network interface that is not controlled by LXD. Therefore, you must specify all information that LXD needs to use the network interface.
When using this method, the nictype option must be specified when creating the device, and it cannot be changed later.
network
When using the network device option, the NIC is linked to an existing managed network. In this case, LXD has all required information about the network, and you need to specify only the network name when adding the device.
When using this method, LXD derives the nictype option automatically. The value is read-only and cannot be changed.
Other device options that are inherited from the network are marked with a "yes" in the "Managed" field of the NIC-specific device options. You cannot customize these options directly for the NIC if you're using the network method.
See Networking setups for more information.
Available NIC types
The following NICs can be added using the nictype or network options:
bridged: Uses an existing bridge on the host and creates a virtual device pair to connect the host bridge to the instance.macvlan: Sets up a new network device based on an existing one, but using a different MAC address.sriov: Passes a virtual function of an SR-IOV-enabled physical network device into the instance.physical: Passes a physical device from the host through to the instance. The targeted device will vanish from the host and appear in the instance.
The following NICs can be added using only the network option:
ovn: Uses an existing OVN network and creates a virtual device pair to connect the instance to it.
The following NICs can be added using only the nictype option:
ipvlan: Sets up a new network device based on an existing one, using the same MAC address but a different IP.p2p: Creates a virtual device pair, putting one side in the instance and leaving the other side on the host.routed: Creates a virtual device pair to connect the host to the instance and sets up static routes and proxy ARP/NDP entries to allow the instance to join the network of a designated parent interface.
The available device options depend on the NIC type and are listed in the following sections.
nictype: bridged
Note
You can select this NIC type through thenictypeoption or thenetworkoption (see Bridge network for information about the managedbridgenetwork).
A bridged NIC uses an existing bridge on the host and creates a virtual device pair to connect the host bridge to the instance.
Device options
NIC devices of type bridged have the following device options:
boot.priority
Boot priority for VMs
Key: boot.priority
Type: integer
Managed: no
A higher value for this option means that the VM boots first.
host_name
Name of the interface inside the host
Key: host_name
Type: string
Default: randomly assigned
Managed: no
hwaddr
MAC address of the new interface
Key: hwaddr
Type: string
Default: randomly assigned
Managed: no
ipv4.address
IPv4 address to assign to the instance through DHCP
Key: ipv4.address
Type: string
Managed: no
Set this option to none to restrict all IPv4 traffic when security.ipv4_filtering is set.
ipv4.routes
IPv4 static routes for the NIC to add on the host
Key: ipv4.routes
Type: string
Managed: no
Specify a comma-delimited list of IPv4 static routes for this NIC to add on the host.
ipv4.routes.external
IPv4 static routes to route to NIC
Key: ipv4.routes.external
Type: string
Managed: no
Specify a comma-delimited list of IPv4 static routes to route to the NIC and publish on the uplink network (BGP).
ipv6.address
IPv6 address to assign to the instance through DHCP
Key: ipv6.address
Type: string
Managed: no
Set this option to none to restrict all IPv6 traffic when security.ipv6_filtering is set.
ipv6.routes
IPv6 static routes for the NIC to add on the host
Key: ipv6.routes
Type: string
Managed: no
Specify a comma-delimited list of IPv6 static routes for this NIC to add on the host.
ipv6.routes.external
IPv6 static routes to route to NIC
Key: ipv6.routes.external
Type: string
Managed: no
Specify a comma-delimited list of IPv6 static routes to route to the NIC and publish on the uplink network (BGP).
limits.egress
I/O limit for outgoing traffic
Key: limits.egress
Type: string
Managed: no
Specify the limit in bit/s. Various suffixes are supported (see Units for storage and network limits).
limits.ingress
I/O limit for incoming traffic
Key: limits.ingress
Type: string
Managed: no
Specify the limit in bit/s. Various suffixes are supported (see Units for storage and network limits).
limits.max
I/O limit for both incoming and outgoing traffic
Key: limits.max
Type: string
Managed: no
This option is the same as setting both limits.ingress and limits.egress.
Specify the limit in bit/s. Various suffixes are supported (see Units for storage and network limits).
limits.priority
skb->priority value for outgoing traffic
Key: limits.priority
Type: integer
Managed: no
The skb->priority value for outgoing traffic is used by the kernel queuing discipline (qdisc) to prioritize network packets. Specify the value as a 32-bit unsigned integer.
The effect of this value depends on the particular qdisc implementation, for example, SKBPRIO or QFQ. Consult the kernel qdisc documentation before setting this value.
maas.subnet.ipv4
MAAS IPv4 subnet to register the instance in
Key: maas.subnet.ipv4
Type: string
Managed: yes
maas.subnet.ipv6
MAAS IPv6 subnet to register the instance in
Key: maas.subnet.ipv6
Type: string
Managed: yes
mtu
MTU of the new interface
Key: mtu
Type: integer
Default: parent MTU
Managed: yes
name
Name of the interface inside the instance
Key: name
Type: string
Default: kernel assigned
Managed: no
network
Managed network to link the device to
Key: network
Type: string
Managed: no
You can specify this option instead of specifying the nictype directly.
parent
Name of the host device
Key: parent
Type: string
Managed: yes
Required: if specifying the nictype directly
queue.tx.length
Transmit queue length for the NIC
Key: queue.tx.length
Type: integer
Managed: no
security.ipv4_filtering
Whether to prevent the instance from spoofing an IPv4 address
Key: security.ipv4_filtering
Type: bool
Default: false
Managed: no
Set this option to true to prevent the instance from spoofing another instance's IPv4 address. This option enables security.mac_filtering.
security.ipv6_filtering
Whether to prevent the instance from spoofing an IPv6 address
Key: security.ipv6_filtering
Type: bool
Default: false
Managed: no
Set this option to true to prevent the instance from spoofing another instance's IPv6 address. This option enables security.mac_filtering.
security.mac_filtering
Whether to prevent the instance from spoofing a MAC address
Key: security.mac_filtering
Type: bool
Default: false
Managed: no
Set this option to true to prevent the instance from spoofing another instance's MAC address.
security.port_isolation
Whether to respect port isolation
Key: security.port_isolation
Type: bool
Default: false
Managed: no
Set this option to true to prevent the NIC from communicating with other NICs in the network that have port isolation enabled.
vlan
VLAN ID to use for non-tagged traffic
Key: vlan
Type: integer
Managed: no
Set this option to none to remove the port from the default VLAN.
vlan.tagged
VLAN IDs or VLAN ranges to join for tagged traffic
Key: vlan.tagged
Type: integer
Managed: no
Specify the VLAN IDs or ranges as a comma-delimited list.
Configuration examples
Add a bridged network device to an instance, connecting to a LXD managed network:
lxc network create <network_name> --type=bridge
lxc config device add <instance_name> <device_name> nic network=<network_name>Note that bridge is the type when creating a managed bridge network, while the device nictype that is required when connecting to an unmanaged bridge is bridged.
Add a bridged network device to an instance, connecting to an existing bridge interface with nictype:
lxc config device add <instance_name> <device_name> nic nictype=bridged parent=<existing_bridge>See How to create a network and Configure devices for more information.
nictype: macvlan
Note
You can select this NIC type through thenictypeoption or thenetworkoption (see Macvlan network for information about the managedmacvlannetwork).
A macvlan NIC sets up a new network device based on an existing one, but using a different MAC address.
If you are using a macvlan NIC, communication between the LXD host and the instances is not possible. Both the host and the instances can talk to the gateway, but they cannot communicate directly.
Device options
NIC devices of type macvlan have the following device options:
boot.priority
Boot priority for VMs
Key: boot.priority
Type: integer
Managed: no
A higher value for this option means that the VM boots first.
gvrp
Whether to use GARP VLAN Registration Protocol
Key: gvrp
Type: bool
Default: false
Managed: no
This option specifies whether to register the VLAN using the GARP VLAN Registration Protocol.
hwaddr
MAC address of the new interface
Key: hwaddr
Type: string
Default: randomly assigned
Managed: no
maas.subnet.ipv4
MAAS IPv4 subnet to register the instance in
Key: maas.subnet.ipv4
Type: string
Managed: yes
maas.subnet.ipv6
MAAS IPv6 subnet to register the instance in
Key: maas.subnet.ipv6
Type: string
Managed: yes
mtu
MTU of the new interface
Key: mtu
Type: integer
Default: parent MTU
Managed: yes
name
Name of the interface inside the instance
Key: name
Type: string
Default: kernel assigned
Managed: no
network
Managed network to link the device to
Key: network
Type: string
Managed: no
You can specify this option instead of specifying the nictype directly.
parent
Name of the host device
Key: parent
Type: string
Managed: yes
Required: if specifying the nictype directly
vlan
VLAN ID to attach to
Key: vlan
Type: integer
Managed: no
Configuration examples
Add a macvlan network device to an instance, connecting to a LXD managed network:
lxc network create <network_name> --type=macvlan parent=<existing_NIC>
lxc config device add <instance_name> <device_name> nic network=<network_name>Add a macvlan network device to an instance, connecting to an existing network interface with nictype:
lxc config device add <instance_name> <device_name> nic nictype=macvlan parent=<existing_NIC>See How to create a network and Configure devices for more information.
nictype: sriov
Note
You can select this NIC type through thenictypeoption or thenetworkoption (see SR-IOV network for information about the managedsriovnetwork).
An sriov NIC passes a virtual function of an SR-IOV-enabled physical network device into the instance.
An SR-IOV-enabled network device associates a set of virtual functions (VFs) with the single physical function (PF) of the network device. PFs are standard PCIe functions. VFs, on the other hand, are very lightweight PCIe functions that are optimized for data movement. They come with a limited set of configuration capabilities to prevent changing properties of the PF.
Given that VFs appear as regular PCIe devices to the system, they can be passed to instances just like a regular physical device.
VF allocation
The sriov interface type expects to be passed the name of an SR-IOV enabled network device on the system via the parent property. LXD then checks for any available VFs on the system.
By default, LXD allocates the first free VF it finds. If it detects that either none are enabled or all currently enabled VFs are in use, it bumps the number of supported VFs to the maximum value and uses the first free VF. If all possible VFs are in use or the kernel or card doesn't support incrementing the number of VFs, LXD returns an error.
Note
If you need LXD to use a specific VF, use aphysicalNIC instead of asriovNIC and set itsparentoption to the VF name.
Device options
NIC devices of type sriov have the following device options:
boot.priority
Boot priority for VMs
Key: boot.priority
Type: integer
Managed: no
A higher value for this option means that the VM boots first.
hwaddr
MAC address of the new interface
Key: hwaddr
Type: string
Default: randomly assigned
Managed: no
maas.subnet.ipv4
MAAS IPv4 subnet to register the instance in
Key: maas.subnet.ipv4
Type: string
Managed: yes
maas.subnet.ipv6
MAAS IPv6 subnet to register the instance in
Key: maas.subnet.ipv6
Type: string
Managed: yes
mtu
MTU of