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 (opens in a new tab) where network subnet information is required, for example,
192.0.2.0/24or2001: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 `vx