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:
- How can I list nodes?
- How can I determine a node system ID?
- How can I commission a node?
- How can I acquire a node?
- How can I deploy a node?
- How can I configure the deployment timeout?
- How can I control subnet management?
- How can I create a reserved IP range?
- How can I determine a fabric ID?
- How can I enable DHCP?
- How can I set a DNS forwarder?
- How can I configure proxying?
- How can I set a default gateway?
- How can I set a DNS server?
- How can I set a zone description?
- How can I add a public SSH key?
- How can I determine a node hostname?
- How can I create a regular user?
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
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
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 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)
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
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
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
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.