Common CLI tasks

Docs
1

As of MAAS 3.0 Beta1, this page has been deprecated and the content moved to the CLI sections of other, relevant MAAS documents. The contents may or may not diverge from the latest information over time.

This page presents a list of many 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 machine

To commission a machine:

maas $PROFILE machine commission $SYSTEM_ID

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

To commission all machines in the ‘New’ state:

maas $PROFILE machines accept-all

You have the option of setting some parameters to change how commission runs:

  • enable_ssh: Optional integer. Controls whether to enable SSH for the commissioning environment using the user’s SSH key(s). ‘1’ == True, ‘0’ == False. Roughly equivalent to the Allow SSH access and prevent machine powering off in the web UI.

  • skip_bmc_config: Optional integer. Controls whether to skip re-configuration of the BMC for IPMI based machines. ‘1’ == True, ‘0’ == False.

  • skip_networking: Optional integer. Controls whether to skip re-configuring the networking on the machine after the commissioning has completed. ‘1’ == True, ‘0’ == False. Roughly equivalent to Retain network configuration in the web UI.

  • skip_storage: Optional integer. Controls hether to skip re-configuring the storage on the machine after the commissioning has completed. ‘1’ == True, ‘0’ == False. Roughly equivalent to Retain storage configuration in the web UI.

  • commissioning_scripts: Optional string. A comma seperated list of commissioning script names and tags to be run. By default all custom commissioning scripts are run. Built-in commissioning scripts always run. Selecting ‘update_firmware’ or ‘configure_hba’ will run firmware updates or configure HBA’s on matching machines.

  • testing_scripts: Optional string. A comma seperated list of testing script names and tags to be run. By default all tests tagged ‘commissioning’ will be run. Set to ‘none’ to disable running tests.

  • parameters: Optional string. Scripts selected to run may define their own parameters. These parameters may be passed using the parameter name. Optionally a parameter may have the script name prepended to have that parameter only apply to that specific script.

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.

2

The command maas $PROFILE set-config name=node-timeout value=$NUMBER_OF_MINUTES, it should be “node_timeout”, with an underscore instead of a dash.