Common CLI tasks

List nodes Determine a node system ID
Commission a node Acquire a node
Deploy a node Configure deployment timeout
Control subnet management Create a reserved IP range
Determine a fabric ID Enable DHCP
Set a DNS forwarder Configure proxying
Set a default gateway Set a DNS server
Set a zone description Add a public SSH key
Determine a node hostname Create a regular user

This page presents a list of common tasks that you can perform with the MAAS CLI. See MAAS CLI for instructions to help get you started.

List nodes

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

maas $PROFILE nodes read

You can also specify various parameters to narrow your search. In the following example, MAAS will return any machines containing ‘node2’ in the hostname parameter.

maas $PROFILE machines read hostname=node2

To see a list of all available search parameters:

maas $PROFILE machines read --help

Determine a node system ID

You can uses jq to determine a node’s system ID. For example, here’s how to output just the hostname and system_id when searching for a particular hostname:

maas $PROFILE machines read | jq '.[] | .hostname, .system_id'

jq is a command-line JSON processor.

The output looks like this:


Commission a node

To commission a node:

maas $PROFILE machine commission $SYSTEM_ID

To commission a node, it must have a status of ‘New’.

To commission all nodes in the ‘New’ state:

maas $PROFILE machines accept-all

See Commission nodes.

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

To acquire a node, it must have a status of ‘Ready’.

Deploy a node

To deploy a node:

maas $PROFILE machine deploy $SYSTEM_ID

To deploy a node as a KVM host:

maas $PROFILE machine deploy $SYSTEM_ID install_kvm=True

To deploy with the CLI, the node must have a status of ‘Allocated’. See ‘Acquire a node’ above (or use the web UI).

See Deploy nodes.

Configure deployment timeout

By default, when you deploy a node, MAAS will consider the deployment a failure if it doesn’t complete within 30 minutes. However, this timeout is configurable:

maas $PROFILE set-config name=node-timeout value=$NUMBER_OF_MINUTES

Control subnet management

To enable or disable subnet management:

maas $PROFILE subnet update $SUBNET_CIDR managed=false|true

For example, to disable:

maas $PROFILE subnet update managed=false

You can use the subnet’s ID in place of the CIDR address.

See Subnet management.

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).

You must enable DHCP for PXE booting on the ‘untagged’ VLAN.

See DHCP for more on this subject.

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’). The following command will disable proxying 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’). Here is how you can disable proxying on a per-subnet basis:

maas $PROFILE subnet update $SUBNET_CIDR allow_proxy=false

For example,

maas $PROFILE subnet update allow_proxy=false

See Proxy for detailed information on how proxying works with MAAS.

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."

See Zones for more information on this topic.

Add a public SSH key

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

maas $PROFILE sshkeys create "key=$SSH_KEY"

See SSH keys.

Determine a node hostname

To determine a node’s hostname based on it’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.