Description: 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 connec...

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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:

- How to configure network ACLs

- How to configure network forwards

- How to configure network zones

- How to configure LXD as a BGP server

- How to integrate with `systemd-resolved`

## Firewall issues

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