The MAAS CLI provides direct visibility into subnets, VLANs, IP ranges, and system events. This document collects useful commands for troubleshooting and verification in MAAS environments.
Before using these commands, replace $PROFILE with your authenticated MAAS CLI profile name (for example, admin). All commands are run from a host with MAAS CLI access.
List subnets, fabrics, and IP ranges
Use this command set to review how IP space is allocated across fabrics and subnets.
maas $PROFILE subnets read | jq '.[].cidr'
maas $PROFILE ipranges read
Verify that subnets are correctly defined and that IP ranges do not overlap.
Example output:
"10.0.0.0/24"
"10.0.1.0/24"
Check VLAN DHCP status
Use this command to confirm DHCP status for a specific VLAN.
maas $PROFILE vlan read <fabric-id> <vid> | jq '.dhcp_on'
A value of true indicates that DHCP is active on that VLAN. Use maas $PROFILE vlans read <fabric-id> to list available VLANs.
Example output:
true
Recent warnings and errors
Use this command to review recent warning and error events across all MAAS nodes.
maas $PROFILE events query level=WARNING limit=50
You can adjust the query level to ERROR or INFO as needed. Pipe through jq or grep to filter for specific node IDs.
Example output (truncated):
"message": "Node node-1 failed to acquire DHCP lease"
"created": "2025-10-15T08:21:14Z"
Node event lens
Use this command to view commissioning, deployment, and runtime events for a specific node.
maas $PROFILE node-events read <system-id> limit=50
Verify the system ID with maas $PROFILE machines read | jq '.[].system_id'. Look for repeated commissioning failures or timeout messages.
Example output:
"id": 150,
"type": "Commissioning",
"description": "Failed to contact metadata service."
List fabrics and VLANs in detail
Use this command set to understand the logical layout of fabrics and their VLANs.
maas $PROFILE fabrics read | jq '.[].name'
maas $PROFILE vlans read <fabric-id>
Use the first command to identify fabrics, then list VLANs within each. Useful for confirming where DHCP and PXE traffic are expected to flow.
Example output:
"fabric-0"
"fabric-1"
Check proxy configuration
Use this command to verify that MAAS is configured to use the correct proxy for package downloads and metadata access.
maas $PROFILE maas get-config name=http_proxy
If needed, update the proxy configuration:
maas $PROFILE maas set-config name=http_proxy value=http://<rack-ip>:3128/
Verify configuration:
maas $PROFILE maas get-config name=http_proxy | jq '.value'
Example output:
"http://10.0.0.2:3128/"
List DNS zones and records
Use these commands to confirm that DNS zones and records are defined and resolving correctly.
maas $PROFILE dnsdomains read
maas $PROFILE dnsresources read
Verify that the domain associated with your MAAS deployment appears in the output and contains expected A and PTR records.
Example output:
"name": "maas"
"ttl": 300
"resource_record_type": "A"
"fqdn": "node1.maas."
Reboot or power-cycle a node for retest
Use these commands to power on or off a specific machine managed by MAAS.
maas $PROFILE machine power-on <system-id>
maas $PROFILE machine power-off <system-id>
Verify power state changes using:
maas $PROFILE machine read <system-id> | jq '.power_state'
Example output:
"on"
Dump all MAAS configuration
Use this command to capture a complete snapshot of MAAS configuration for audit or escalation.
maas $PROFILE maas get-config > /tmp/maas-config.json
Verify the dump file exists and contains valid JSON data:
jq '.' /tmp/maas-config.json | head
Example output:
{
"name": "http_proxy",
"value": "http://10.0.0.2:3128/"
}
Next steps
The next document in this series covers switch configuration validation, common DHCP relay patterns, and recommended health-check automation for MAAS environments.