Sometimes you don’t need a deep dive — you just need to get a stalled machine moving again. This document lists ten high‑confidence fixes you can try in about ten minutes. These are the “usual suspects” that solve the majority of MAAS networking problems.
1. Eliminate stray DHCP servers
Problem: Another service (like dnsmasq from libvirt or a Wi‑Fi router) is offering DHCP on the same VLAN as MAAS.
Check:
ps aux | egrep 'dnsmasq|libvirtd'
Fix: Stop or disable conflicting services so that only MAAS provides DHCP on the relevant VLAN.
2. Enable portfast on access switchports
Problem: Spanning Tree Protocol delays ports from going active, so PXE clients time out.
Check: Machine link LEDs are on, but PXE boot fails quickly.
Fix: On switches, enable portfast (or equivalent) on all access ports used by PXE clients.
3. Verify the correct untagged VLAN for PXE
Problem: PXE clients boot on the wrong VLAN or no VLAN at all.
Check:
tcpdump -i <iface> port 67 or port 68
If no DHCP is seen, VLAN might be wrong.
Fix: Ensure the access port is configured with the correct native/untagged VLAN for PXE.
4. Confirm DHCP relay (IP helper) targets MAAS
Problem: DHCP broadcasts don’t reach MAAS when servers are on different subnets.
Check: Look for missing offers in a tcpdump.
Fix: Configure your switch/router DHCP relay (IP helper) to point to the MAAS rack controller’s IP.
5. Allowlist PXE protocols through firewalls
Problem: Firewalls block DHCP, TFTP, or HTTP boot traffic.
Check:
nc -vz <maas-ip> 67 69 80
Fix: Permit UDP 67/68 (DHCP), UDP 69 (TFTP), TCP 80/443 (HTTP/HTTPS), and any proxy ports.
6. Correct MTU mismatches
Problem: Packets drop silently during image download or commissioning.
Check:
tracepath <maas-ip>
If you see “pmtu” errors, MTU is mismatched.
Fix: Ensure bridges, bonds, and uplinks all use the same MTU (e.g. 1500, or 9000 for jumbo).
7. Ensure NTP reachability
Problem: Commissioning or deployment fails due to clock skew.
Check:
chronyc sources -v
Fix: Verify that NTP is reachable from ephemeral and deployed nodes, either via MAAS or external servers.
8. Confirm machine firmware settings
Problem: BIOS/UEFI is not set to PXE or HTTP boot.
Check: Enter machine setup and review boot order.
Fix: Ensure network boot is enabled and precedes local disks.
9. Test metadata service reachability
Problem: Commissioning scripts fail to fetch metadata.
Check:
curl -I http://<maas-host>/MAAS/
Fix: Verify routing, DNS, and firewall rules from the commissioning subnet to the MAAS region.
10. Clear stale leases and overlapping ranges
Problem: Nodes get wrong or duplicate IPs.
Check:
maas $PROFILE ipranges read
Fix: Remove overlapping ranges, clear stale leases, and confirm the right VLAN has DHCP enabled.
Next steps
If none of these quick fixes solve the problem, move on to the detailed symptom‑driven playbooks, which walk through full troubleshooting flows by failure point.