Network troubleshooting tools

Docs
1

Every network issue in MAAS comes down to the right tool used at the right time. This document catalogus the essential troubleshooting tools, explains how to use them, and shows examples in a MAAS context.

Link and interface state

ip link, ip addr, ip -d link

  • Purpose: Show interfaces, addresses, VLAN tagging, bridge membership.
  • Example:
ip -d link show dev eno1
  • MAAS use: Verify PXE NIC is up and tagged correctly.

ethtool

  • Purpose: Show speed, duplex, offloads, driver info.
  • Examples:
ethtool eno1
ethtool -k eno1
ethtool -S eno1
  • MAAS use: Detect driver quirks that break image downloads.

lldpcli, lldpd

  • Purpose: Discover switchport neighbors.
  • Example:
lldpcli show neighbors
  • MAAS use: Confirm correct switchport and VLAN.

VLANs, bonds, and bridges

bridge link, bridge vlan, bridge fdb

  • Show bridge memberships and VLAN info.

Netplan

  • Validate configs:
netplan get
netplan try
netplan apply

Open vSwitch

  • Example:
ovs-vsctl show

Discovery and reachability

Ping/arping

ping <ip>
arping -I br0 <gateway>

Traceroute/MTR

mtr -ezbwrc 100 <host>
  • MAAS use: Spot asymmetric routing or packet loss.

Packet capture and protocol lenses

tcpdump

  • General capture:
tcpdump -n -e -vv -s0 -i <iface> -w /tmp/boot.pcap
  • Filters:
    • DHCP: port 67 or port 68
    • TFTP: port 69
    • DNS: port 53
    • HTTP: tcp port 80 and host <maas-ip>

tshark, termshark, ngrep

  • In-terminal decodes and quick protocol filters.

Wireshark

  • Decode BOOTP/DHCP, follow TCP streams, export boot files.

Service checks

ss -ltnup, ss -uanp

  • Show active listeners.

curl, wget, httping

  • Test HTTP endpoints.
curl -I http://<maas-host>/MAAS/

nc/ncat/socat

  • Check connectivity.
nc -vz <host> 67 69 80 3128

TFTP clients

atftp -g -r pxelinux.0 <tftp-ip>

Name resolution

dig, kdig, host

dig @<dns-ip> <node>.maas A +noall +answer +ttl

resolvectl status

  • Inspect systemd-resolved configuration.

Time sync

chronyc, timedatectl, ntpq

chronyc sources -v
  • MAAS use: Ensure clocks are in sync for commissioning.

Performance profiling

iperf3

iperf3 -c <server> -P 4 -t 30

nload, iftop, bmon

  • Real-time bandwidth monitoring.

TCP info

ss -ti

Logs and events

Systemd journals

journalctl -u snap.maas.regiond -u snap.maas.rackd

MAAS event logs

maas $PROFILE events query level=WARNING

Installer logs

  • /var/log/cloud-init.log
  • /var/log/curtin/install.log
  • /var/log/installer/*

Firewalls and ACLs

nft, iptables, ufw

nft list ruleset
  • MAAS use: Verify PXE/DHCP/DNS/TFTP/HTTP not blocked.

Next steps

With these tools in your belt, the next reference dives into MAAS‑specific deep dives: how PXE, DHCP, metadata, and proxies behave in detail.