As well as the web interface, many tasks can be performed by accessing the MAAS API directly through the maas-cli command. This section details how to login with this tool and perform some common operations.

Logging in

Before the API will accept any commands from maas-cli, you must first login. To do this, you need the API key which can be found in the user interface.

Login to the web interface on your MAAS. Click on the username in the top right corner and select ‘Preferences’ from the menu which appears.

A new page will load...

The very first item is a list of MAAS keys. One will have already been generated when the system was installed. It’s easiest to just select and copy the key (it’s quite long!) and then paste it into the commandline. The format of the login command is:

$ maas-cli login <profile-name> <hostname> <key>

The profile name created by default when you install MAAS is “maas”. So an example login might look like this:

$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2

maas-cli commands

The maas-cli command exposes the whole API, so you can do anything you actually can do with MAAS using this command. Unsurprisingly, this leaves us with a vast number of options, but before we delve into detail on the specifics, here is a sort of ‘cheat-sheet’ for common tasks you might want to do using maas-cli.

• Configure DHCP and DNS services
• Commission all enlisted nodes
• Setting IPMI power parameters for a node

The main maas-cli commands are:

list

lists the details [name url auth-key] of all the currently logged-in profiles.

login <profile> <url> <key>

Logs in to the MAAS controller API at the given URL, using the key provided and associates this connection with the given profile name.

refresh

Refreshes the API descriptions of all the current logged in profiles. This may become necessary for example when upgrading the maas packages to ensure the command-line options match with the API.

<profile> [command] [options] ...

Using the given profile name instructs maas-cli to direct the subsequent commands and options to the relevant MAAS, which for the current API are detailed below...

account

This command is used for creating and destroying the MAAS authorisation tokens associated with a profile.

Usage: maas-cli <profile> account [-d –degug] [-h –help] create-authorisation-token | delete-authorisation-token [token_key=<value>]

-create-authorisation-token `

Creates a new MAAS authorisation token for the current profile which can be used to authenticate connections to the API.

-delete-authorisation-token token_key=<value>

Removes the given key from the list of authorisation tokens.

node

API calls which operate on individual nodes. With thes commands, the node is always identified by its “system_id” property - a unique tag allocated at the time of enlistment. To discover the value of the system_id, you can use the ``maas-cli <profile> nodes list``command.

USAGE: maas-cli <profile> node release | start | stop | delete | read | update <system_id>

release <system_id>

Releases the node given by <system_id>

start <system_id>

Powers up the node identified by <system_id> (where MAAS has information for power management for this node).

stop <system_id>

Powers off the node identified by <system_id> (where MAAS has information for power management for this node).

delete <system_id>

Removes the given node from the MAAS database.

read <system_id>

Returns all the current known information aboyt the node specified by <system_id>

update <system_id> [parameters...]

Used to change or set specific values for the node. The valid parameters are listed below:

hostname=<value>
     The new hostname for this node.

architecture=<value>
     Sets the architecture type, where <value> is a string containing a valid architecture type, e.g. "i386/generic"

power_type=<value>
     Apply the given dotted decimal value as the broadcast IP address for this subnet.

power_parameters_{param1}... =<value>
     Set the given power parameters. Note that the valid options for these depend on the power type chosen

power_parameters_skip_check 'true' | 'false'
     Wether to sanity chack the supplied paramters against this node's declared power type. The default is 'false'.

Example: Setting the power parameters for an ipmi enabled node:

maas-cli maas node update <system_id> \
  power_type="ipmi" \
  power_parameters_power_address=192.168.22.33 \
  power_parameters_power_user=root \
  power_parameters_power_pass=ubuntu;

nodes

Examples: Accept and commission all discovered nodes:

$ maas-cli maas nodes accept-all

List all known nodes:

$ maas-cli maas nodes list

Filter the list using specific key/value pairs:

$ maas-cli maas nodes list architecture="i386/generic"

node-group

node-groups

node-group-interface

node-group-interfaces

The node-group-interfaces commands are used for configuring the management of DHCP and DNS services where these are managed by MAAS.

Usage: maas-cli <profile> node-group-interfaces [-d –degug] [-h –help] [-k –insecure] list | new [parameters...]

-d, --debug

Displays debug information listing the API responses.

-h, --help

Display usage information.

-k, --insecure

Disables the SSL certificate check.

list <label>

Lists the current stored configurations for the given identifier label in a key:value format which should be easy to decipher.

new <label> ip=<value> interface=<if_device> [parameters...]

Creates a new interface group. The required parameters are the IP address and the network interface this appies to (e.g. eth0). In order to do anything useful, further parameters are required:

management=  0 | 1 | 2
     The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP and DNS).

subnet_mask=<value>
     Apply the given dotted decimal value as the subnet mask.

broadcast_ip=<value>
     Apply the given dotted decimal value as the broadcast IP address for this subnet.

router_ip=<value>
     Apply the given dotted decimal value as the default router address for this subnet.

ip_range_low=<value>
     The lowest value of IP address to allocate via DHCP

ip_range_high=<value>
     The highest value of IP address to allocate via DHCP

Example: Configuring DHCP and DNS under a new label called ‘master’:

$ maas-cli maas node-group-interfaces new master \
    ip=192.168.21.5             \
    interface=eth1              \
    management=2                \
    subnet_mask=255.255.255.0   \
    broadcast_ip=192.168.21.255 \
    router_ip=192.168.21.1      \
    ip_range_low=192.168.21.10  \
    ip_range_high=192.168.21.50

tag

tags

Note

You can filter the output

unused commands

Because the maas-cli command exposes all of the API, it also lists some command options which are not really intended for end users, such as the “file” and “boot-images” options.