Bridge network

As one of the possible network configuration types under LXD, LXD supports creating and managing network bridges.

A network bridge creates a virtual L2 Ethernet switch that instance NICs can connect to, making it possible for them to communicate with each other and the host. LXD bridges can leverage underlying native Linux bridges and Open vSwitch.

The bridge network type allows to create an L2 bridge that connects the instances that use it together into a single network L2 segment. Bridges created by LXD are managed, which means that in addition to creating the bridge interface itself, LXD also sets up a local dnsmasq process to provide DHCP, IPv6 route announcements and DNS services to the network. By default, it also performs NAT for the bridge.

See How to configure your firewall for instructions on how to configure your firewall to work with LXD bridge networks.

Note

Static DHCP assignments depend on the client using its MAC address as the DHCP identifier. This method prevents conflicting leases when copying an instance, and thus makes statically assigned leases work properly.

IPv6 prefix size

If you’re using IPv6 for your bridge network, you should use a prefix size of 64.

Larger subnets (i.e., using a prefix smaller than 64) should work properly too, but they aren’t typically that useful for SLAAC.

Smaller subnets are in theory possible (when using stateful DHCPv6 for IPv6 allocation), but they aren’t properly supported by dnsmasq and might cause problems. If you must create a smaller subnet, use static allocation or another standalone router advertisement daemon.

Configuration options

The following configuration key namespaces are currently supported for the bridge network type:

  • bgp (BGP peer configuration)

  • bridge (L2 interface configuration)

  • dns (DNS server and resolution configuration)

  • fan (configuration specific to the Ubuntu FAN overlay)

  • ipv4 (L3 IPv4 configuration)

  • ipv6 (L3 IPv6 configuration)

  • maas (MAAS network identification)

  • security (network ACL configuration)

  • raw (raw configuration file content)

  • tunnel (cross-host tunneling configuration)

  • user (free-form key/value for user metadata)

Note

LXD uses the CIDR notation where network subnet information is required, for example, 192.0.2.0/24 or 2001:db8::/32. This does not apply to cases where a single address is required, for example, local/remote addresses of tunnels, NAT addresses or specific addresses to apply to an instance.

The following configuration options are available for the bridge network type:

bgp.ipv4.nexthop

Override the IPv4 next-hop for advertised prefixes

Key: bgp.ipv4.nexthop
Type:

string

Default:

local address

Condition:

BGP server

bgp.ipv6.nexthop

Override the IPv6 next-hop for advertised prefixes

Key: bgp.ipv6.nexthop
Type:

string

Default:

local address

Condition:

BGP server

bgp.peers.NAME.address

Peer address (IPv4 or IPv6)

Key: bgp.peers.NAME.address
Type:

string

Condition:

BGP server

bgp.peers.NAME.asn

Peer AS number

Key: bgp.peers.NAME.asn
Type:

integer

Condition:

BGP server

bgp.peers.NAME.holdtime

Peer session hold time

Key: bgp.peers.NAME.holdtime
Type:

integer

Default:

180

Condition:

BGP server

Required:

no

Specify the hold time in seconds.

bgp.peers.NAME.password

Peer session password

Key: bgp.peers.NAME.password
Type:

string

Default:

(no password)

Condition:

BGP server

Required:

no

bridge.driver

Bridge driver

Key: bridge.driver
Type:

string

Default:

native

Possible values are native and openvswitch.

bridge.external_interfaces

Unconfigured network interfaces to include in the bridge

Key: bridge.external_interfaces
Type:

string

Specify a comma-separated list of unconfigured network interfaces to include in the bridge.

bridge.hwaddr

MAC address for the bridge

Key: bridge.hwaddr
Type:

string

bridge.mode

Bridge operation mode

Key: bridge.mode
Type:

string

Default:

standard

Possible values are standard and fan.

bridge.mtu

Bridge MTU

Key: bridge.mtu
Type:

integer

Default:

1500 if bridge.mode=standard, 1480 if bridge.mode=fan and fan.type=ipip, or 1450 if bridge.mode=fan and fan.type=vxlan

The default value varies depending on whether the bridge uses a tunnel or a fan setup.

dns.domain

Domain to advertise to DHCP clients and use for DNS resolution

Key: dns.domain
Type:

string

Default:

lxd

dns.mode

DNS registration mode

Key: dns.mode
Type:

string

Default:

managed

Possible values are none for no DNS record, managed for LXD-generated static records, and dynamic for client-generated records.

dns.search

Full domain search list

Key: dns.search
Type:

string

Default:

dns.domain value

Specify a comma-separated list of domains.

dns.zone.forward

DNS zone names for forward DNS records

Key: dns.zone.forward
Type:

string

Specify a comma-separated list of DNS zone names.

dns.zone.reverse.ipv4

DNS zone name for IPv4 reverse DNS records

Key: dns.zone.reverse.ipv4
Type:

string

dns.zone.reverse.ipv6

DNS zone name for IPv6 reverse DNS records

Key: dns.zone.reverse.ipv6
Type:

string

fan.overlay_subnet

Subnet to use as the overlay for the FAN

Key: fan.overlay_subnet
Type:

string

Default:

240.0.0.0/8

Condition:

fan mode

Use CIDR notation.

fan.type

Tunneling type for the FAN

Key: fan.type
Type:

string

Default:

vxlan

Condition:

fan mode

Possible values are vxlan and ipip.

fan.underlay_subnet

Subnet to use as the underlay for the FAN

Key: fan.underlay_subnet
Type:

string

Default:

initial value on creation: auto

Condition:

fan mode

Use CIDR notation.

You can set the option to auto to use the default gateway subnet.

ipv4.address

IPv4 address for the bridge

Key: ipv4.address
Type:

string

Default:

initial value on creation: auto

Condition:

standard mode

Use CIDR notation.

You can set the option to none to turn off IPv4, or to auto to generate a new random unused subnet.

ipv4.dhcp

Whether to allocate IPv4 addresses using DHCP

Key: ipv4.dhcp
Type:

bool

Default:

true

Condition:

IPv4 address

ipv4.dhcp.expiry

When to expire DHCP leases

Key: ipv4.dhcp.expiry
Type:

string

Default:

1h

Condition:

IPv4 DHCP

ipv4.dhcp.gateway

Address of the gateway for the IPv4 subnet

Key: ipv4.dhcp.gateway
Type:

string

Default:

IPv4 address

Condition:

IPv4 DHCP

ipv4.dhcp.ranges

IPv4 ranges to use for DHCP

Key: ipv4.dhcp.ranges
Type:

string

Default:

all addresses

Condition:

IPv4 DHCP

Specify a comma-separated list of IPv4 ranges in FIRST-LAST format.

ipv4.firewall

Whether to generate filtering firewall rules for this network

Key: ipv4.firewall
Type:

bool

Default:

true

Condition:

IPv4 address

ipv4.nat

Whether to use NAT for IPv4

Key: ipv4.nat
Type:

bool

Default:

false (initial value on creation if ipv4.address is set to auto: true)

Condition:

IPv4 address

ipv4.nat.address

Source address used for outbound traffic from the bridge

Key: ipv4.nat.address
Type:

string

Condition:

IPv4 address

ipv4.nat.order

Where to add the required NAT rules

Key: ipv4.nat.order
Type:

string

Default:

before

Condition:

IPv4 address

Set this option to before to add the NAT rules before any pre-existing rules, or to after to add them after the pre-existing rules.

ipv4.ovn.ranges

IPv4 ranges to use for child OVN network routers

Key: ipv4.ovn.ranges
Type:

string

Specify a comma-separated list of IPv4 ranges in FIRST-LAST format.

ipv4.routes

Additional IPv4 CIDR subnets to route to the bridge

Key: ipv4.routes
Type:

string

Condition:

IPv4 address

Specify a comma-separated list of IPv4 CIDR subnets.

ipv4.routing

Whether to route IPv4 traffic in and out of the bridge

Key: ipv4.routing
Type:

bool

Default:

true

Condition:

IPv4 address

ipv6.address

IPv6 address for the bridge

Key: ipv6.address
Type:

string

Default:

initial value on creation: auto

Condition:

standard mode

Use CIDR notation.

You can set the option to none to turn off IPv6, or to auto to generate a new random unused subnet.

ipv6.dhcp

Whether to provide additional network configuration over DHCP

Key: ipv6.dhcp
Type:

bool

Default:

true

Condition:

IPv6 address

ipv6.dhcp.expiry

When to expire DHCP leases

Key: ipv6.dhcp.expiry
Type:

string

Default:

1h

Condition:

IPv6 DHCP

ipv6.dhcp.ranges

IPv6 ranges to use for DHCP

Key: ipv6.dhcp.ranges
Type:

string

Default:

all addresses

Condition:

IPv6 stateful DHCP

Specify a comma-separated list of IPv6 ranges in FIRST-LAST format.

ipv6.dhcp.stateful

Whether to allocate IPv6 addresses using DHCP

Key: ipv6.dhcp.stateful
Type:

bool

Default:

false

Condition:

IPv6 DHCP

ipv6.firewall

Whether to generate filtering firewall rules for this network

Key: ipv6.firewall
Type:

bool

Default:

true

Condition:

IPv6 DHCP

ipv6.nat

Whether to use NAT for IPv6

Key: ipv6.nat
Type:

bool

Default:

false (initial value on creation if ipv6.address is set to auto: true)

Condition:

IPv6 address

ipv6.nat.address

Source address used for outbound traffic from the bridge

Key: ipv6.nat.address
Type:

string

Condition:

IPv6 address

ipv6.nat.order

Where to add the required NAT rules

Key: ipv6.nat.order
Type:

string

Default:

before

Condition:

IPv6 address

Set this option to before to add the NAT rules before any pre-existing rules, or to after to add them after the pre-existing rules.

ipv6.ovn.ranges

IPv6 ranges to use for child OVN network routers

Key: ipv6.ovn.ranges
Type:

string

Specify a comma-separated list of IPv6 ranges in FIRST-LAST format.

ipv6.routes

Additional IPv6 CIDR subnets to route to the bridge

Key: ipv6.routes
Type:

string

Condition:

IPv6 address

Specify a comma-separated list of IPv6 CIDR subnets.

ipv6.routing

Whether to route IPv6 traffic in and out of the bridge

Key: ipv6.routing
Type:

bool

Condition:

IPv6 address

maas.subnet.ipv4

MAAS IPv4 subnet to register instances in

Key: maas.subnet.ipv4
Type:

string

Condition:

IPv4 address; using the network property on the NIC

maas.subnet.ipv6

MAAS IPv6 subnet to register instances in

Key: maas.subnet.ipv6
Type:

string

Condition:

IPv6 address; using the network property on the NIC

raw.dnsmasq

Additional dnsmasq configuration to append to the configuration file

Key: raw.dnsmasq
Type:

string

security.acls

Network ACLs to apply to NICs connected to this network

Key: security.acls
Type:

string

Specify a comma-separated list of network ACLs.

Also see Bridge limitations.

security.acls.default.egress.action

Default action to use for egress traffic

Key: security.acls.default.egress.action
Type:

string

Condition:

security.acls

The specified action is used for all egress traffic that doesn’t match any ACL rule.

security.acls.default.egress.logged

Whether to log egress traffic that doesn’t match any ACL rule

Key: security.acls.default.egress.logged
Type:

bool

Condition:

security.acls

security.acls.default.ingress.action

Default action to use for ingress traffic

Key: security.acls.default.ingress.action
Type:

string

Condition:

security.acls

The specified action is used for all ingress traffic that doesn’t match any ACL rule.

security.acls.default.ingress.logged

Whether to log ingress traffic that doesn’t match any ACL rule

Key: security.acls.default.ingress.logged
Type:

bool

Condition:

security.acls

tunnel.NAME.group

Multicast address for vxlan

Key: tunnel.NAME.group
Type:

string

Condition:

vxlan

This address is used if tunnel.NAME.local and tunnel.NAME.remote aren’t set.

tunnel.NAME.id

Specific tunnel ID to use for the vxlan tunnel

Key: tunnel.NAME.id
Type:

integer

Condition:

vxlan

tunnel.NAME.interface

Specific host interface to use for the tunnel

Key: tunnel.NAME.interface
Type:

string

Condition:

vxlan

tunnel.NAME.local

Local address for the tunnel

Key: tunnel.NAME.local
Type:

string

Condition:

gre or vxlan

Required:

not required for multicast vxlan

tunnel.NAME.port

Specific port to use for the vxlan tunnel

Key: tunnel.NAME.port
Type:

integer

Default:

0

Condition:

vxlan

tunnel.NAME.protocol

Tunneling protocol

Key: tunnel.NAME.protocol
Type:

string

Condition:

standard mode

Possible values are vxlan and gre.

tunnel.NAME.remote

Remote address for the tunnel

Key: tunnel.NAME.remote
Type:

string

Condition:

gre or vxlan

Required:

not required for multicast vxlan

tunnel.NAME.ttl

Specific TTL to use for multicast routing topologies

Key: tunnel.NAME.ttl
Type:

string

Default:

1

Condition:

vxlan

user.*

User-provided free-form key/value pairs

Key: user.*
Type:

string

Supported features

The following features are supported for the bridge network type:

Firewall issues

See How to configure your firewall for instructions on how to troubleshoot firewall issues.