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

bgp.ipv6.nexthop

Override the IPv6 next-hop for advertised prefixes

bgp.peers.NAME.address

Peer address (IPv4 or IPv6)

bgp.peers.NAME.asn

Peer AS number

bgp.peers.NAME.holdtime

Peer session hold time

bgp.peers.NAME.password

Peer session password

bridge.driver

Bridge driver

bridge.external_interfaces

Unconfigured network interfaces to include in the bridge

bridge.hwaddr

MAC address for the bridge

bridge.mode

Bridge operation mode

bridge.mtu

Bridge MTU

dns.domain

Domain to advertise to DHCP clients and use for DNS resolution

dns.mode

DNS registration mode

dns.search

Full domain search list

dns.zone.forward

DNS zone names for forward DNS records

dns.zone.reverse.ipv4

DNS zone name for IPv4 reverse DNS records

dns.zone.reverse.ipv6

DNS zone name for IPv6 reverse DNS records

fan.overlay_subnet

Subnet to use as the overlay for the FAN

fan.type

Tunneling type for the FAN

fan.underlay_subnet

Subnet to use as the underlay for the FAN

ipv4.address

IPv4 address for the bridge

ipv4.dhcp

Whether to allocate IPv4 addresses using DHCP

ipv4.dhcp.expiry

When to expire DHCP leases

ipv4.dhcp.gateway

Address of the gateway for the IPv4 subnet

ipv4.dhcp.ranges

IPv4 ranges to use for DHCP

ipv4.firewall

Whether to generate filtering firewall rules for this network

ipv4.nat

Whether to use NAT for IPv4

ipv4.nat.address

Source address used for outbound traffic from the bridge

ipv4.nat.order

Where to add the required NAT rules

ipv4.ovn.ranges

IPv4 ranges to use for child OVN network routers

ipv4.routes

Additional IPv4 CIDR subnets to route to the bridge

ipv4.routing

Whether to route IPv4 traffic in and out of the bridge

ipv6.address

IPv6 address for the bridge

ipv6.dhcp

Whether to provide additional network configuration over DHCP

ipv6.dhcp.expiry

When to expire DHCP leases

ipv6.dhcp.ranges

IPv6 ranges to use for DHCP

ipv6.dhcp.stateful

Whether to allocate IPv6 addresses using DHCP

ipv6.firewall

Whether to generate filtering firewall rules for this network

ipv6.nat

Whether to use NAT for IPv6

ipv6.nat.address

Source address used for outbound traffic from the bridge

ipv6.nat.order

Where to add the required NAT rules

ipv6.ovn.ranges

IPv6 ranges to use for child OVN network routers

ipv6.routes

Additional IPv6 CIDR subnets to route to the bridge

ipv6.routing

Whether to route IPv6 traffic in and out of the bridge

maas.subnet.ipv4

MAAS IPv4 subnet to register instances in

maas.subnet.ipv6

MAAS IPv6 subnet to register instances in

raw.dnsmasq

Additional dnsmasq configuration to append to the configuration file

security.acls

Network ACLs to apply to NICs connected to this network

security.acls.default.egress.action

Default action to use for egress traffic

security.acls.default.egress.logged

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

security.acls.default.ingress.action

Default action to use for ingress traffic

security.acls.default.ingress.logged

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

tunnel.NAME.group

Multicast address for vxlan

tunnel.NAME.id

Specific tunnel ID to use for the vxlan tunnel

tunnel.NAME.interface

Specific host interface to use for the tunnel

tunnel.NAME.local

Local address for the tunnel

tunnel.NAME.port

Specific port to use for the vxlan tunnel

tunnel.NAME.protocol

Tunneling protocol

tunnel.NAME.remote

Remote address for the tunnel

tunnel.NAME.ttl

Specific TTL to use for multicast routing topologies

user.*

User-provided free-form key/value pairs

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.