Common CLI Tasks

This is a list of common tasks to perform with the MAAS CLI. See MAAS CLI on how to get started.

List nodes

To list all nodes (and their characteristics) in the MAAS:

maas $PROFILE nodes read

Add a filter to get just their hostnames:

maas $PROFILE nodes read | grep hostname

Determine a node's system ID

To determine the system ID of a node based on its hostname:

SYSTEM_ID=$(maas $PROFILE nodes read hostname=$HOSTNAME \
    | grep system_id -m 1 | cut -d '"' -f 4)

Commission a node

To commission a node:

maas $PROFILE machine commission $SYSTEM_ID

Note: To commission a node it must have a status of 'New'.

Commission all nodes

To commission all nodes in the 'Ready' state:

maas $PROFILE machines accept-all

Acquire a node

To acquire/allocate a random node:

maas $PROFILE machines allocate

To acquire/allocate a specific node:

maas $PROFILE machines allocate system_id=$SYSTEM_ID

Note: To acquire a node it must have a status of 'Ready'.

Deploy a node

To deploy a node:

maas $PROFILE machine deploy $SYSTEM_ID

Note: To deploy with the CLI the node must have a status of 'Allocated'. See 'Acquire a node' above (or use the web UI).

Assign a tag to a node

To assign a tag to a node:

maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID

Multiple add= arguments (and their values) can be used to apply a tag to multiple nodes.

Create a reserved IP range

See Concepts and terms for an explanation of the two kinds of reserved IP ranges MAAS uses.

To create a range of dynamic IP addresses that will be used by MAAS for node enlistment, commissioning, and possibly deployment:

maas $PROFILE ipranges create type=dynamic \
    comment='This is a reserved dynamic range'

To create a range of IP addresses that will not be used by MAAS:

maas $PROFILE ipranges create type=reserved \
    comment='This is a reserved range'

To reserve a single IP address that will not be used by MAAS:

maas $PROFILE ipaddresses reserve ip_address=$IP_STATIC_SINGLE

To remove such a single reserved IP address:

maas $PROFILE ipaddresses release ip=$IP_STATIC_SINGLE

Determine a fabric ID

To determine a fabric ID based on a subnet address:

FABRIC_ID=$(maas $PROFILE subnet read $SUBNET_CIDR \
    | grep fabric | cut -d ' ' -f 10 | cut -d '"' -f 2)

Enable DHCP

To enable DHCP on a VLAN on a certain fabric:

maas $PROFILE vlan update $FABRIC_ID $VLAN_TAG dhcp_on=True \

To enable DHCP HA you will need both a primary and a secondary controller:

maas $PROFILE vlan update $FABRIC_ID $VLAN_TAG dhcp_on=True \
    primary_rack=$PRIMARY_RACK_CONTROLLER \

You will also need to set a default gateway (see below).

Note: DHCP for PXE booting will need to be enabled on the 'untagged' VLAN.

Set a DNS forwarder

To set a DNS forwarder:

maas $PROFILE maas set-config name=upstream_dns value=$MY_UPSTREAM_DNS

Configure proxying

Enabling and disabling proxying in general is done via a boolean option ('true' or 'false'). This is how proxying is disabled completely:

maas $PROFILE maas set-config name=enable_http_proxy value=false

To set an external proxy, ensure proxying is enabled (see above) and then define it:

maas $PROFILE maas set-config name=http_proxy value=$EXTERNAL_PROXY

For example,

maas $PROFILE maas set-config name=enable_http_proxy value=true
maas $PROFILE maas set-config name=http_proxy value=

Enabling and disabling proxying per subnet is done via a boolean option ('true' or 'false'). This is how proxying is disabled per subnet:

maas $PROFILE subnet update $SUBNET_CIDR allow_proxy=false

For example,

maas $PROFILE subnet update allow_proxy=false

Set a default gateway

To set the default gateway for a subnet:

maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY

Set a DNS server

To set the DNS server for a subnet:

maas $PROFILE subnet update $SUBNET_CIDR dns_servers=$MY_NAMESERVER

Set a zone description

To set a description for a physical zone:

maas $PROFILE zone update default \
    description="This zone was configured by a script."

Add a public SSH key

To add a public SSH key to a MAAS user account:

maas $PROFILE sshkeys create "key=$SSH_KEY"

Determine a hostname

To determine the hostname based on a node's MAC address:

HOSTNAME=$(maas $PROFILE nodes read mac_address=$MAC \
    | grep hostname | cut -d '"' -f 4)

Create a regular user

To create a regular user:

maas $PROFILE users create username=$USERNAME \
    email=$EMAIL_ADDRESS password=$PASSWORD is_superuser=0

All the options are necessary. Note that stipulating a password on the CLI may be a security hazard, depending on your environment. If unsure, use the web UI. See User Accounts for the latter.