Network troubleshooting: Lab cookbook

Docs
1

Many MAAS users start in labs with Multipass, LXD, or KVM before moving to bare metal. These environments introduce quirks that can derail provisioning if not configured carefully. This appendix provides working patterns and recipes for lab setups that coexist peacefully with MAAS.

Principles for Lab Networking

  • Eliminate rogue DHCP: Libvirt and LXD spawn dnsmasq by default, which collides with MAAS DHCP. Disable or isolate them.
  • Prefer bridges over NAT: Nodes must be on the same L2 domain as MAAS rack controllers for DHCP/PXE.
  • Control VLANs explicitly: If your host uplink is a trunk, create VLAN interfaces and bridges intentionally.
  • Keep one clear default path: Avoid multiple services answering TFTP/DHCP/DNS on the same segment.

Multipass Labs

Problem: Multipass launches VMs with a NAT network and its own dnsmasq. Nodes cannot reach MAAS DHCP.

Solution:

  • Launch Multipass with a bridged interface to the physical network:
multipass launch --network enp3s0 --name maas-node
  • Ensure the host does not run its own DHCP on that bridge.
  • Use multipass shell to log in and confirm ip a shows the correct VLAN/subnet.

Tips:

  • Multipass often prefers cloud-init. Disable conflicting cloud-init net config if using MAAS-managed DHCP.

LXD Labs

Problem: Default lxdbr0 includes dnsmasq. Nodes get DHCP from LXD, not MAAS.

Solution:

  • Delete or disable the default LXD network:
lxc network delete lxdbr0
  • Create a bridge tied to the host NIC:
lxc network create br0 bridge.driver=bridge ipv4.address=none ipv6.address=none
lxc network attach br0 <container> eth0
  • Confirm MAAS DHCP leases appear in the UI.

Tips:

  • LXD containers are not PXE-bootable by default. Use LXD VMs with UEFI and the --vm flag for true PXE.

KVM/Libvirt Labs

Problem: Libvirt’s default network virbr0 runs dnsmasq, which conflicts with MAAS.

Solution:

  • Disable the default network:
virsh net-destroy default
virsh net-undefine default
  • Create a host bridge and bind it to the physical NIC:
<network>
  <name>br0</name>
  <forward mode='bridge'/>
  <bridge name='br0'/>
</network>
  • Attach VMs to br0. Ensure boot firmware is set to network first.

Tips:

  • Use VirtIO NICs for performance, or e1000 for maximum PXE compatibility.
  • If VLAN trunking, add <vlan> XML entries to match MAAS fabrics.

Nested Virtualization

  • Ensure the outer hypervisor passes through correct NIC features.
  • Enable promiscuous mode on VMware/ESXi port groups if nesting MAAS inside.
  • Some UEFI firmwares in nested VMs lack HTTPBoot; fall back to legacy PXE + TFTP.

Cookbook: Host Bridge on Ubuntu

# /etc/netplan/01-netcfg.yaml
network:
  version: 2
  ethernets:
    enp3s0:
      dhcp4: no
  bridges:
    br0:
      interfaces: [enp3s0]
      dhcp4: no
      addresses: [192.168.1.10/24]
      gateway4: 192.168.1.1
      nameservers:
        addresses: [192.168.1.1]

Apply with:

sudo netplan apply

Attach Multipass, LXD, or Libvirt VMs to br0 to share the same L2 domain as MAAS.

Troubleshooting Checklist for Labs

  • Run ps aux | grep dnsmasq on the host; kill unwanted dnsmasq processes.
  • Run tcpdump -i br0 '(port 67 or 68)' while booting a VM to confirm DHCP from MAAS, not the host.
  • Check MAAS UI leases to ensure lab VMs appear.
  • Verify TFTP/HTTP boot files served from the rack are accessible from lab VMs.

Patterns That Work

  • Single NIC host: Bridge NIC into br0, attach VMs directly.
  • Dual NIC host: Dedicate one NIC to lab VLAN, one for host management.
  • Nested hypervisors: Always enable promiscuous mode and disable NAT.
  • Cloud labs (AWS/GCP/Azure): MAAS not recommended due to lack of PXE broadcast, unless overlay networks are engineered.

Next Steps

This closes the main troubleshooting reference set. Combine these appendices with the checklists, tools, and playbooks to build your own standardized runbooks and evidence bundles.