Common CLI tasks (snap/2.9/UI)

Docs
1

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

Quick questions you may have:

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:

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

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

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

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