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.