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.
-
Find the network card that carries the default route. Its name follows
dev, for exampleenp1s0:ip route show default -
Back up the netplan configuration:
sudo cp -a /etc/netplan /root/netplan.bak -
Write the bridge configuration. Replace
enp1s0with 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.yamlnetplan 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
br0takes one from DHCP. -
Apply it. Use
netplan apply:netplan trycannot roll back a bridge.sudo netplan apply -
Check that
br0isUPwith 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¶
- Open Muppy / LXD / LXC Profiles and click New.
- Fill in:
- Name:
muppy-bridged. It is also the name of the profile in LXD, on the host. - LXC Server: your LXD App Server.
- Name:
-
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
muppyprofile of the host. The user data installs the SSH keys Muppy connects with. Without them, Muppy cannot reach the guests launched with this profile.
-
Save, then click Update. Muppy creates the profile on the host as a copy of the LXD
defaultprofile, replaces itseth0network card with one bridged onbr0, then writes the user data andsecurity.nesting. The button returns once the host has answered. -
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¶
- On the Host form of the LXD App Server, open the LXD tab, then LXCs ▸ Create LXC.
- Set LXC Profile to
muppy-bridged. The Create SSH Proxy and SSH Proxy Port fields disappear: a bridged guest has its own address. - 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.