Skip to content

Configure an LXD App Server in bridged mode

Bridged mode puts chosen guests of an LXD App Server directly on your LAN. The other guests of the host, its App Servers included, keep running as before.

Situation

Your LXD App Server is a machine of your LAN, enrolled in Muppy through Tailscale. Its guests sit behind lxdbr0, the NAT bridge LXD creates: each one has a private address that only the host can reach. Muppy reaches them through the host, used as SSH jump host.

Problem

Some guests must be reachable from the LAN itself:

  • a test machine that colleagues open from their workstation;
  • a VM that runs its own LXD and serves its own guests;
  • a service that a device of the LAN calls.

A NAT guest cannot be: no machine of the LAN has a route to its address.

Resolution

Create a bridge on the host's network card, then a second LXC profile whose network card is attached to that bridge. A guest launched with this profile takes its address from your LAN's DHCP server, like any other machine of the LAN.

The host's default profile, muppy, stays in NAT. App Servers keep being created with it, and the host stays in its App Server pool.

Prerequisites

  • An LXD App Server: a host on which the Install LXD App. Server wizard ran. Its Default LXC Profile is muppy, in NAT.
  • Enrolled through Tailscale: Muppy reaches the host at its Tailscale address. See Private hosts (Tailscale).
  • Ubuntu 24.04 or later, configured by netplan.
  • A wired network card. A Wi-Fi interface cannot be attached to a bridge.
  • A DHCP server on the LAN, usually your router. The bridge and each bridged guest take their address from it.
  • A console on the host: its screen and keyboard, IPMI, or the console of its hypervisor. The host loses its network for a few seconds while the bridge comes up, and a mistake cuts SSH and Tailscale until you fix it locally.

Do not use the Bridged host option of Setup LXD (Expert mode)

That option switches the muppy profile itself to bridged and marks the host as a bridged host. Every new guest, App Servers included, then lands on the LAN, and Muppy reaches each guest directly at its LAN address, which a Muppy outside your LAN cannot do. A bridged host also leaves App Server allocation: Manganese and the provisioning wizard no longer offer its pool.

Step 1 — Create the bridge on the host

Muppy does not change the network configuration of the host. You do, on the host, with netplan. Run these commands from the host's console.

  1. Find the network card that carries the default route. Its name follows dev, for example enp1s0:

    ip route show default
    
  2. Back up the netplan configuration:

    sudo cp -a /etc/netplan /root/netplan.bak
    
  3. Write the bridge configuration. Replace enp1s0 with your card, twice:

    sudo tee /etc/netplan/99-muppy-br0.yaml > /dev/null <<'EOF'
    network:
      version: 2
      renderer: networkd
      ethernets:
        enp1s0:
          dhcp4: false
          dhcp6: false
      bridges:
        br0:
          interfaces: [enp1s0]
          dhcp4: true
          dhcp6: false
          parameters:
            stp: false
            forward-delay: 0
    EOF
    sudo chmod 600 /etc/netplan/99-muppy-br0.yaml
    

    netplan reads its files in name order, so this file overrides the card's settings found in the existing ones: the card loses its address, and the bridge br0 takes one from DHCP.

  4. Apply it. Use netplan apply: netplan try cannot roll back a bridge.

    sudo netplan apply
    
  5. Check that br0 is UP with an address of your LAN, and that Tailscale is connected again:

    ip -br addr show br0
    tailscale status
    

The bridge may get another address than the one the card had. Muppy is not affected: it reaches the host at its Tailscale address. If the LAN must find the host at a fixed address, reserve one for the bridge in your DHCP server.

Step 2 — Create the bridged profile

  1. Open Muppy / LXD / LXC Profiles and click New.
  2. Fill in:
    • Name: muppy-bridged. It is also the name of the profile in LXD, on the host.
    • LXC Server: your LXD App Server.
  3. In the Settings tab, fill in:

    • Network Mode: Bridged.
    • Bridge Name: br0.
    • Security Nesting (Docker), User Data Template and SSH Authorized Keys: the same values as the muppy profile of the host. The user data installs the SSH keys Muppy connects with. Without them, Muppy cannot reach the guests launched with this profile.
  4. Save, then click Update. Muppy creates the profile on the host as a copy of the LXD default profile, replaces its eth0 network card with one bridged on br0, then writes the user data and security.nesting. The button returns once the host has answered.

  5. Click Read. The Managed-keys diff is empty when the profile on the host matches the form.

Step 3 — Launch a guest on the LAN

  1. On the Host form of the LXD App Server, open the LXD tab, then LXCs ▸ Create LXC.
  2. Set LXC Profile to muppy-bridged. The Create SSH Proxy and SSH Proxy Port fields disappear: a bridged guest has its own address.
  3. Fill in the other fields as described in Creating a Container or VM, then click Launch.

The creation runs in the background, as a job named Create LXC '<name>' on host '<host>'. Follow it in Muppy / Qs / Messages.

Once the guest is up, its Host record carries its LAN address as Host IP, and the LXD App Server as SSH Gateway Host: Muppy reaches it through the host, as it reaches a NAT guest. Any machine of the LAN reaches it at that address.

An agent launches the same guest with the Muppy MCP method create_lxc, the bridged profile given as lxc_profile_id: see Creating a container.

Information

The NAT profile and the bridged profile

muppy (NAT) muppy-bridged
Guest's address Private, on lxdbr0, given by LXD On your LAN, given by your DHCP server
Reachable from the LAN No Yes
How Muppy reaches the guest Through the host as jump host, or through an SSH proxy device when the pool asks for one Through the host as jump host. Never a proxy device.
Used by App Servers, and every guest launched without another profile The guests you launch with it

App Servers stay in NAT

Keep muppy as the Default LXC Profile of the host. The App Server provisioning launches its containers with that profile, and the host's Traefik publishes them. The bridged profile serves the guests you create with Create LXC or create_lxc.

A bridged guest is a machine of your LAN

It sees the LAN, and the LAN sees it. The UFW rules of the host protect the host, not the guest: traffic between the LAN and the guest crosses the bridge without being routed by the host. Protect the guest with its own firewall rules, as any machine of the LAN.

Troubleshooting

The host is unreachable after netplan apply. From the host's console, remove the bridge file and apply again. The card gets its previous configuration back:

sudo rm /etc/netplan/99-muppy-br0.yaml
sudo netplan apply

Check the card's name with ip route show default, then start Step 1 again.

br0 is up but has no address. The DHCP server does not answer on the bridge. Check that the card is wired and that ip route show default named it.

The launch fails on the eth0 device. The host has no bridge with the profile's Bridge Name. List the bridges of the host with ip -br link show type bridge. Fix the bridge or the profile's Bridge Name, then click Update on the profile.

The guest gets no address. The DHCP server of the LAN did not answer the guest. Check its state on the host with lxc list <name>, and check that your DHCP server has free addresses and does not filter unknown machines.