Introduction to network troubleshooting

Docs
1

Network troubleshooting: An introduction

This reference section provides a single, unified place to explore network troubleshooting in MAAS. It aims to cover most of the tools, techniques, and pitfalls that might appear when you’re diagnosing network issues in a MAAS environment.

Most system administrators know how to test basic connectivity with ping or check logs with journalctl. MAAS depends on a much wider range of network services (DHCP, TFTP, HTTP, DNS, NTP, and more) all working together, across multiple layers of the network stack. When one of those layers fails, a MAAS workflow, like commissioning or deployment, can stall in hard-to-diagnose ways.

This section gathers all of those practices into one voice, so you don’t have to piece them together from scattered sources.

Scope and intent

This section is designed to offer:

  • Comprehensive coverage: You’ll find step-by-step guides to every layer of the network stack as it touches MAAS.
  • Practical tools: Each tool is explained with essential flags, examples, and MAAS-specific context.
  • Symptom-driven choices: Playbooks show what to check when commissioning fails, when DHCP packets aren’t seen, or when machines won’t reboot into a deployed state.
  • Reference first: This section is designed to be something you can search, skim, or read line-by-line to build confidence.

Reading conventions

Note the following conventions:

  • Commands are shown in fenced code blocks, ready to copy and paste.
  • Output examples are trimmed to the parts that matter most.
  • File paths are presented as they are installed with MAAS on Ubuntu (snap packages by default).
  • Linux conventions: Examples assume an Ubuntu host with systemd-networkd or netplan in use. Equivalent commands for other distros or tools are noted where relevant.

Safety notes

Before diving in, a few words of caution:

  • Change with care: Some troubleshooting steps involve restarting services, applying netplan, or disabling conflicting daemons. Always make sure you know the impact on production networks before running these commands.
  • Capture with consent: Packet captures (tcpdump, wireshark) can expose sensitive data. Don’t capture indiscriminately on busy or sensitive production links without authorization.
  • One DHCP per VLAN: MAAS requires control of DHCP on a broadcast domain. Two active DHCP servers on the same VLAN will almost always cause trouble.
  • Record baselines: Before you change switch configs, netplan files, or firewall rules, record their current state so you can roll back quickly.

Next steps

This introduction is the first of many documents in the network troubleshooting reference section. Each document tackles one area in depth:

  • A mental model of the MAAS networking stack
  • Quick fixes you can try in 10 minutes
  • Symptom-driven playbooks
  • Tool-by-tool guides
  • MAAS-specific deep dives
  • Environment and topology gotchas
  • Performance troubleshooting
  • Security and compliance intersections
  • Checklists, runbooks, and evidence collection

Together, they provide a complete troubleshooting manual for any MAAS deployment, from a small test lab to a production data centre.