Common CLI Tasks


#1

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'

jq is a command-line JSON processor.

Output looks like this:

"node2"
"e8xa8m"

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 a node is deployed, 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 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).

DHCP for PXE booting will need to be enabled 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’). 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.


Subnet Management
IP Ranges
Dhcp
Documentation index
MAAS Documentation
Proxy
Interactive search
Manage composable machines
Advanced CLI Tasks
Custom node setup (preseed)