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

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 use 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'

Output looks like this:

"node2"
"e8xa8m"

Commission a node

To commission a node:

maas $PROFILE machine commission $SYSTEM_ID

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

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

See Deploy nodes.

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 192.168.1.0/24 managed=false

The subnet's ID can also be used 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 \
    start_ip=$IP_DYNAMIC_RANGE_LOW end_ip=$IP_DYNAMIC_RANGE_HIGH \
    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 \
    start_ip=$IP_STATIC_RANGE_LOW end_ip=$IP_STATIC_RANGE_HIGH \
    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 \
    primary_rack=$PRIMARY_RACK_CONTROLLER

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 \
    secondary_rack=$SECONDARY_RACK_CONTROLLER 

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

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'). 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=http://squid.example.com:3128/

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 192.168.0.0/22 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.