# 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](https://canonical.com/lxd/docs/default/howto/network_bridge_firewalld/index.html.md#network-bridge-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 . 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](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) 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 [](#network-bridge-network-conf:bgp.ipv4.nexthop) | **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 [](#network-bridge-network-conf:bgp.ipv6.nexthop) | **Key:** | `bgp.ipv6.nexthop` | |----------------|----------------------| | **Type:** | string | | **Default:** | local address | | **Condition:** | BGP server | | **Scope:** | local | `bgp.peers.NAME.address` Peer address (IPv4 or IPv6) [](#network-bridge-network-conf:bgp.peers.NAME.address) | **Key:** | `bgp.peers.NAME.address` | |----------------|----------------------------| | **Type:** | string | | **Condition:** | BGP server | | **Scope:** | global | `bgp.peers.NAME.asn` Peer AS number [](#network-bridge-network-conf:bgp.peers.NAME.asn) | **Key:** | `bgp.peers.NAME.asn` | |----------------|------------------------| | **Type:** | integer | | **Condition:** | BGP server | | **Scope:** | global | `bgp.peers.NAME.holdtime` Peer session hold time [](#network-bridge-network-conf:bgp.peers.NAME.holdtime) | **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 [](#network-bridge-network-conf:bgp.peers.NAME.password) | **Key:** | `bgp.peers.NAME.password` | |----------------|-----------------------------| | **Type:** | string | | **Default:** | (no password) | | **Condition:** | BGP server | | **Required:** | no | | **Scope:** | global | `bridge.driver` Bridge driver [](#network-bridge-network-conf: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 [](#network-bridge-network-conf:bridge.external_interfaces) | **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 [](#network-bridge-network-conf:bridge.hwaddr) | **Key:** | `bridge.hwaddr` | |-------------|-------------------| | **Type:** | string | | **Scope:** | global | `bridge.mode` Bridge operation mode [](#network-bridge-network-conf:bridge.mode) | **Key:** | `bridge.mode` | |--------------|-----------------| | **Type:** | string | | **Default:** | `standard` | | **Scope:** | global | Possible values are `standard` and `fan`. `bridge.mtu` Bridge MTU [](#network-bridge-network-conf: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 [](#network-bridge-network-conf:dns.domain) | **Key:** | `dns.domain` | |--------------|----------------| | **Type:** | string | | **Default:** | `lxd` | | **Scope:** | global | `dns.mode` DNS registration mode [](#network-bridge-network-conf:dns.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 [](#network-bridge-network-conf:dns.search) | **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 [](#network-bridge-network-conf:dns.zone.forward) | **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 [](#network-bridge-network-conf:dns.zone.reverse.ipv4) | **Key:** | `dns.zone.reverse.ipv4` | |-------------|---------------------------| | **Type:** | string | | **Scope:** | global | `dns.zone.reverse.ipv6` DNS zone name for IPv6 reverse DNS records [](#network-bridge-network-conf:dns.zone.reverse.ipv6) | **Key:** | `dns.zone.reverse.ipv6` | |-------------|---------------------------| | **Type:** | string | | **Scope:** | global | `fan.overlay_subnet` Subnet to use as the overlay for the FAN [](#network-bridge-network-conf:fan.overlay_subnet) | **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 [](#network-bridge-network-conf:fan.type) | **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 [](#network-bridge-network-conf:fan.underlay_subnet) | **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 [](#network-bridge-network-conf:ipv4.address) | **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 [](#network-bridge-network-conf:ipv4.dhcp) | **Key:** | `ipv4.dhcp` | |----------------|---------------| | **Type:** | bool | | **Default:** | `true` | | **Condition:** | IPv4 address | | **Scope:** | global | `ipv4.dhcp.expiry` When to expire DHCP leases [](#network-bridge-network-conf:ipv4.dhcp.expiry) | **Key:** | `ipv4.dhcp.expiry` | |----------------|----------------------| | **Type:** | string | | **Default:** | `1h` | | **Condition:** | IPv4 DHCP | | **Scope:** | global | `ipv4.dhcp.gateway` Address of the gateway for the IPv4 subnet [](#network-bridge-network-conf:ipv4.dhcp.gateway) | **Key:** | `ipv4.dhcp.gateway` | |----------------|-----------------------| | **Type:** | string | | **Default:** | IPv4 address | | **Condition:** | IPv4 DHCP | | **Scope:** | global | `ipv4.dhcp.ranges` IPv4 ranges to use for DHCP [](#network-bridge-network-conf:ipv4.dhcp.ranges) | **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 [](#network-bridge-network-conf:ipv4.firewall) | **Key:** | `ipv4.firewall` | |----------------|-------------------| | **Type:** | bool | | **Default:** | `true` | | **Condition:** | IPv4 address | | **Scope:** | global | `ipv4.nat` Whether to use NAT for IPv4 [](#network-bridge-network-conf:ipv4.nat) | **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 [](#network-bridge-network-conf:ipv4.nat.address) | **Key:** | `ipv4.nat.address` | |----------------|----------------------| | **Type:** | string | | **Condition:** | IPv4 address | | **Scope:** | global | `ipv4.nat.order` Where to add the required NAT rules [](#network-bridge-network-conf:ipv4.nat.order) | **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 [](#network-bridge-network-conf:ipv4.ovn.ranges) | **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 [](#network-bridge-network-conf:ipv4.routes) | **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 [](#network-bridge-network-conf:ipv4.routing) | **Key:** | `ipv4.routing` | |----------------|------------------| | **Type:** | bool | | **Default:** | `true` | | **Condition:** | IPv4 address | | **Scope:** | global | `ipv6.address` IPv6 address for the bridge [](#network-bridge-network-conf:ipv6.address) | **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 [](#network-bridge-network-conf:ipv6.dhcp) | **Key:** | `ipv6.dhcp` | |----------------|---------------| | **Type:** | bool | | **Default:** | `true` | | **Condition:** | IPv6 address | | **Scope:** | global | `ipv6.dhcp.expiry` When to expire DHCP leases [](#network-bridge-network-conf:ipv6.dhcp.expiry) | **Key:** | `ipv6.dhcp.expiry` | |----------------|----------------------| | **Type:** | string | | **Default:** | `1h` | | **Condition:** | IPv6 DHCP | | **Scope:** | global | `ipv6.dhcp.ranges` IPv6 ranges to use for DHCP [](#network-bridge-network-conf:ipv6.dhcp.ranges) | **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 [](#network-bridge-network-conf:ipv6.dhcp.stateful) | **Key:** | `ipv6.dhcp.stateful` | |----------------|------------------------| | **Type:** | bool | | **Default:** | `false` | | **Condition:** | IPv6 DHCP | | **Scope:** | global | `ipv6.firewall` Whether to generate filtering firewall rules for this network [](#network-bridge-network-conf:ipv6.firewall) | **Key:** | `ipv6.firewall` | |----------------|-------------------| | **Type:** | bool | | **Default:** | `true` | | **Condition:** | IPv6 DHCP | | **Scope:** | global | `ipv6.nat` Whether to use NAT for IPv6 [](#network-bridge-network-conf:ipv6.nat) | **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 [](#network-bridge-network-conf:ipv6.nat.address) | **Key:** | `ipv6.nat.address` | |----------------|----------------------| | **Type:** | string | | **Condition:** | IPv6 address | | **Scope:** | global | `ipv6.nat.order` Where to add the required NAT rules [](#network-bridge-network-conf:ipv6.nat.order) | **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 [](#network-bridge-network-conf:ipv6.ovn.ranges) | **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 [](#network-bridge-network-conf:ipv6.routes) | **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 [](#network-bridge-network-conf:ipv6.routing) | **Key:** | `ipv6.routing` | |----------------|------------------| | **Type:** | bool | | **Condition:** | IPv6 address | | **Scope:** | global | `maas.subnet.ipv4` MAAS IPv4 subnet to register instances in [](#network-bridge-network-conf:maas.subnet.ipv4) | **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 [](#network-bridge-network-conf:maas.subnet.ipv6) | **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 [](#network-bridge-network-conf:raw.dnsmasq) | **Key:** | `raw.dnsmasq` | |-------------|-----------------| | **Type:** | string | | **Scope:** | global | `security.acls` Network ACLs to apply to NICs connected to this network [](#network-bridge-network-conf:security.acls) | **Key:** | `security.acls` | |-------------|-------------------| | **Type:** | string | | **Scope:** | global | Specify a comma-separated list of network ACLs. Also see [Bridge limitations](https://canonical.com/lxd/docs/default/howto/network_acls/index.html.md#network-acls-bridge-limitations). `security.acls.default.egress.action` Default action to use for egress traffic [](#network-bridge-network-conf:security.acls.default.egress.action) | **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 [](#network-bridge-network-conf:security.acls.default.egress.logged) | **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 [](#network-bridge-network-conf:security.acls.default.ingress.action) | **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 [](#network-bridge-network-conf:security.acls.default.ingress.logged) | **Key:** | `security.acls.default.ingress.logged` | |----------------|------------------------------------------| | **Type:** | bool | | **Condition:** | `security.acls` | | **Scope:** | global | `tunnel.NAME.group` Multicast address for `vxlan` [](#network-bridge-network-conf:tunnel.NAME.group) | **Key:** | `tunnel.NAME.group` | |----------------|-----------------------| | **Type:** | string | | **Condition:** | `vxlan` | This address is used if [`tunnel.NAME.local`](#network-bridge-network-conf:tunnel.NAME.local) and [`tunnel.NAME.remote`](#network-bridge-network-conf:tunnel.NAME.remote) aren’t set. `tunnel.NAME.id` Specific tunnel ID to use for the `vxlan` tunnel [](#network-bridge-network-conf:tunnel.NAME.id) | **Key:** | `tunnel.NAME.id` | |----------------|--------------------| | **Type:** | integer | | **Condition:** | `vxlan` | `tunnel.NAME.interface` Specific host interface to use for the tunnel [](#network-bridge-network-conf:tunnel.NAME.interface) | **Key:** | `tunnel.NAME.interface` | |----------------|---------------------------| | **Type:** | string | | **Condition:** | `vxlan` | `tunnel.NAME.local` Local address for the tunnel [](#network-bridge-network-conf:tunnel.NAME.local) | **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 [](#network-bridge-network-conf:tunnel.NAME.port) | **Key:** | `tunnel.NAME.port` | |----------------|----------------------| | **Type:** | integer | | **Default:** | `0` | | **Condition:** | `vxlan` | `tunnel.NAME.protocol` Tunneling protocol [](#network-bridge-network-conf:tunnel.NAME.protocol) | **Key:** | `tunnel.NAME.protocol` | |----------------|--------------------------| | **Type:** | string | | **Condition:** | standard mode | Possible values are `vxlan` and `gre`. `tunnel.NAME.remote` Remote address for the tunnel [](#network-bridge-network-conf:tunnel.NAME.remote) | **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 [](#network-bridge-network-conf:tunnel.NAME.ttl) | **Key:** | `tunnel.NAME.ttl` | |----------------|---------------------| | **Type:** | string | | **Default:** | `1` | | **Condition:** | `vxlan` | `user.*` User-provided free-form key/value pairs [](#network-bridge-network-conf:user.*) | **Key:** | `user.*` | |-------------|------------| | **Type:** | string | | **Scope:** | global | ## Supported features The following features are supported for the `bridge` network type: - [How to configure network ACLs](https://canonical.com/lxd/docs/default/howto/network_acls/index.html.md#network-acls) - [How to configure network forwards](https://canonical.com/lxd/docs/default/howto/network_forwards/index.html.md#network-forwards) - [How to configure network zones](https://canonical.com/lxd/docs/default/howto/network_zones/index.html.md#network-zones) - [How to configure LXD as a BGP server](https://canonical.com/lxd/docs/default/howto/network_bgp/index.html.md#network-bgp) - [How to integrate with `systemd-resolved`](https://canonical.com/lxd/docs/default/howto/network_bridge_resolved/index.html.md#network-bridge-resolved) ## Firewall issues See [How to configure your firewall](https://canonical.com/lxd/docs/default/howto/network_bridge_firewalld/index.html.md#network-bridge-firewall) for instructions on how to troubleshoot firewall issues.