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
Scope:	local

bgp.ipv6.nexthop

Override the IPv6 next-hop for advertised prefixes

Key:	`bgp.ipv6.nexthop`
Type:	string
Default:	local address
Condition:	BGP server
Scope:	local

bgp.peers.NAME.address

Peer address (IPv4 or IPv6)

Key:	`bgp.peers.NAME.address`
Type:	string
Condition:	BGP server
Scope:	global

bgp.peers.NAME.asn

Peer AS number

Key:	`bgp.peers.NAME.asn`
Type:	integer
Condition:	BGP server
Scope:	global

bgp.peers.NAME.holdtime

Peer session hold time

Key:	`bgp.peers.NAME.holdtime`
Type:	integer
Default:	`180`
Condition:	BGP server
Required:	no
Scope:	global

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
Scope:	global

bridge.driver

Bridge driver

Key:	`bridge.driver`
Type:	string
Default:	`native`
Scope:	global

Possible values are native and openvswitch.

bridge.external_interfaces

Unconfigured network interfaces to include in the bridge

Key:	`bridge.external_interfaces`
Type:	string
Scope:	local

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
Scope:	global

bridge.mode

Bridge operation mode

Key:	`bridge.mode`
Type:	string
Default:	`standard`
Scope:	global

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`
Scope:	global

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`
Scope:	global

dns.mode

DNS registration mode

Key:	`dns.mode`
Type:	string
Default:	`managed`
Scope:	global

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
Scope:	global

Specify a comma-separated list of domains.

dns.zone.forward

DNS zone names for forward DNS records

Key:	`dns.zone.forward`
Type:	string
Scope:	global

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
Scope:	global

dns.zone.reverse.ipv6

DNS zone name for IPv6 reverse DNS records

Key:	`dns.zone.reverse.ipv6`
Type:	string
Scope:	global

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
Scope:	global

Use CIDR notation.

fan.type

Tunneling type for the FAN

Key:	`fan.type`
Type:	string
Default:	`vxlan`
Condition:	fan mode
Scope:	global

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
Scope:	global

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
Scope:	global

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
Scope:	global

ipv4.dhcp.expiry

When to expire DHCP leases

Key:	`ipv4.dhcp.expiry`
Type:	string
Default:	`1h`
Condition:	IPv4 DHCP
Scope:	global

ipv4.dhcp.gateway

Address of the gateway for the IPv4 subnet

Key:	`ipv4.dhcp.gateway`
Type:	string
Default:	IPv4 address
Condition:	IPv4 DHCP
Scope:	global

ipv4.dhcp.ranges

IPv4 ranges to use for DHCP

Key:	`ipv4.dhcp.ranges`
Type:	string
Default:	all addresses
Condition:	IPv4 DHCP
Scope:	global

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
Scope:	global

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
Scope:	global

ipv4.nat.address

Source address used for outbound traffic from the bridge

Key:	`ipv4.nat.address`
Type:	string
Condition:	IPv4 address
Scope:	global

ipv4.nat.order

Where to add the required NAT rules

Key:	`ipv4.nat.order`
Type:	string
Default:	`before`
Condition:	IPv4 address
Scope:	global

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
Scope:	global

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
Scope:	global

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
Scope:	global

ipv6.address

IPv6 address for the bridge

Key:	`ipv6.address`
Type:	string
Default:	initial value on creation: `auto`
Condition:	standard mode
Scope:	global

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
Scope:	global

ipv6.dhcp.expiry

When to expire DHCP leases

Key:	`ipv6.dhcp.expiry`
Type:	string
Default:	`1h`
Condition:	IPv6 DHCP
Scope:	global

ipv6.dhcp.ranges

IPv6 ranges to use for DHCP

Key:	`ipv6.dhcp.ranges`
Type:	string
Default:	all addresses
Condition:	IPv6 stateful DHCP
Scope:	global

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
Scope:	global

ipv6.firewall

Whether to generate filtering firewall rules for this network

Key:	`ipv6.firewall`
Type:	bool
Default:	`true`
Condition:	IPv6 DHCP
Scope:	global

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
Scope:	global

ipv6.nat.address

Source address used for outbound traffic from the bridge

Key:	`ipv6.nat.address`
Type:	string
Condition:	IPv6 address
Scope:	global

ipv6.nat.order

Where to add the required NAT rules

Key:	`ipv6.nat.order`
Type:	string
Default:	`before`
Condition:	IPv6 address
Scope:	global

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
Scope:	global

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
Scope:	global

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
Scope:	global

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
Scope:	global

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
Scope:	global

raw.dnsmasq

Additional dnsmasq configuration to append to the configuration file

Key:	`raw.dnsmasq`
Type:	string
Scope:	global

security.acls

Network ACLs to apply to NICs connected to this network

Key:	`security.acls`
Type:	string
Scope:	global

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`
Scope:	global

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`
Scope:	global

security.acls.default.ingress.action

Default action to use for ingress traffic

Key:	`security.acls.default.ingress.action`
Type:	string
Condition:	`security.acls`
Scope:	global

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`
Scope:	global

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
Scope:	global

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.