Configuration journey (deb/2.9/CLI)

Once you’ve successfully installed MAAS (regardless of method), you can login to the MAAS CLI via the following process. First, generate the API-key for the user you’re going to employing:

sudo maas apikey --username=$PROFILE > api-key-file

Replace $PROFILE with whatever username you set during the createadmin part of the install process. Next, login with the following command:

maas login $PROFILE $MAAS_URL < api-key-file

Substitute $MAAS_URL with the URL that was returned to you when you initialised MAAS, for example, Remember that, once you’ve logged in, you can get extensive CLI help with the command:

maas admin --help

Sample output is shown in the detail section below.

MAAS CLI help, sample output
usage: maas admin [-h] COMMAND ...

Issue commands to the MAAS region controller at

optional arguments:
  -h, --help            show this help message and exit

drill down:
    account             Manage the current logged-in user.
    bcache-cache-set    Manage bcache cache set on a machine.
    bcache-cache-sets   Manage bcache cache sets on a machine.
    bcache              Manage bcache device on a machine.
    bcaches             Manage bcache devices on a machine.
    block-device        Manage a block device on a machine.
    block-devices       Manage block devices on a machine.
    boot-resource       Manage a boot resource.
    boot-resources      Manage the boot resources.
    boot-source         Manage a boot source.
                        Manage a boot source selection.
                        Manage the collection of boot source selections.
    boot-sources        Manage the collection of boot sources.
                        Manage a custom commissioning script.
                        Manage custom commissioning scripts.
    dhcpsnippet         Manage an individual DHCP snippet.
    dhcpsnippets        Manage the collection of all DHCP snippets in MAAS.
    dnsresource         Manage dnsresource.
    dnsresource-record  Manage dnsresourcerecord.
                        Manage DNS resource records (e.g. CNAME, MX, NS, SRV,
    dnsresources        Manage dnsresources.
    device              Manage an individual device.
    devices             Manage the collection of all the devices in the MAAS.
    discoveries         Query observed discoveries.
    discovery           Read or delete an observed discovery.
    domain              Manage domain.
    domains             Manage domains.
    events              Retrieve filtered node events.
    fabric              Manage fabric.
    fabrics             Manage fabrics.
    fan-network         Manage Fan Network.
    fan-networks        Manage Fan Networks.
    file                Manage a FileStorage object.
    files               Manage the collection of all the files in this MAAS.
    ipaddresses         Manage IP addresses allocated by MAAS.
    iprange             Manage IP range.
    ipranges            Manage IP ranges.
    interface           Manage a node's or device's interface.
    interfaces          Manage interfaces on a node.
    license-key         Manage a license key.
    license-keys        Manage the license keys.
    maas                Manage the MAAS server.
    machine             Manage an individual machine.
    machines            Manage the collection of all the machines in the MAAS.
    network             Manage a network.
    networks            Manage the networks.
    node                Manage an individual Node.
    node-results        Read the collection of commissioning script results.
    node-script         Manage or view a custom script.
    node-script-result  Manage node script results.
                        Manage node script results.
    node-scripts        Manage custom scripts.
    nodes               Manage the collection of all the nodes in the MAAS.
    notification        Manage an individual notification.
    notifications       Manage the collection of all the notifications in
                        Manage the collection of all Package Repositories in
    package-repository  Manage an individual package repository.
    partition           Manage partition on a block device.
    partitions          Manage partitions on a block device.
    pod                 Manage an individual pod.
    pods                Manage the collection of all the pod in the MAAS.
    rack-controller     Manage an individual rack controller.
    rack-controllers    Manage the collection of all rack controllers in MAAS.
    raid                Manage a specific RAID (Redundant Array of Independent
                        Disks) on a machine.
    raids               Manage all RAIDs (Redundant Array of Independent
                        Disks) on a machine.
    region-controller   Manage an individual region controller.
    region-controllers  Manage the collection of all region controllers in
    resource-pool       Manage a resource pool.
    resource-pools      Manage resource pools.
    sshkey              Manage an SSH key.
    sshkeys             Manage the collection of all the SSH keys in this
    sslkey              Manage an SSL key.
    sslkeys             Operations on multiple keys.
    space               Manage space.
    spaces              Manage spaces.
    static-route        Manage static route.
    static-routes       Manage static routes.
    subnet              Manage subnet.
    subnets             Manage subnets.
    tag                 Tags are properties that can be associated with a Node
                        and serve as criteria for selecting and allocating
    tags                Manage all tags known to MAAS.
    user                Manage a user account.
    users               Manage the user accounts of this MAAS.
    version             Information about this MAAS instance.
    vlan                Manage a VLAN on a fabric.
    vlans               Manage VLANs on a fabric.
    vm-host             Manage an individual vm-host.
    vm-hosts            Manage the collection of all the vm-hosts in the MAAS.
    vmfs-datastore      Manage VMFS datastore on a machine.
    vmfs-datastores     Manage VMFS datastores on a machine.
    volume-group        Manage volume group on a machine.
    volume-groups       Manage volume groups on a machine.
    zone                Manage a physical zone.
    zones               Manage physical zones.

This is a profile.  Any commands you issue on this profile will
operate on the MAAS region server.

The command information you see here comes from the region server's
API; it may differ for different profiles.  If you believe the API may
have changed, use the command's 'refresh' sub-command to fetch the
latest version of this help information from the server.


Configuring MAAS consists of four broad steps:

  1. Setting upstream DNS
  2. Importing an SSH key for your admin user
  3. Importing images
  4. Configuring DNS

This section will cover those four operations

Setting DNS

After logging in for the first time, you will need to set a number of system-wide configuration options. First up, you should configure DNS. You can check out the help for DNS settings, known in the CLI as a “DNS forwarder”:

maas $PROFILE maas set-config name=upstream_dns value=""

Here, we’ve set the DNS forwarder to “” (Google), which is a reliable value.

Setting SSH for the admin user

To add a public SSH key to a MAAS user account, type the following command:

maas $PROFILE sshkeys create "key=$SSH_KEY"

Importing images

Before going any further, it’s worthwhile to start the image import, as it can sometimes take a few minutes. You can see what images you already have downloaded with this command:

maas $PROFILE boot-resources read | jq -r '.[] | "\(.name)\t\(.architecture)"'

This command will return a list similar to the following:

grub-efi-signed/uefi        amd64/generic
grub-efi/uefi           arm64/generic
grub-ieee1275/open-firmware ppc64el/generic
pxelinux/pxe            i386/generic
ubuntu/bionic           amd64/ga-18.04
ubuntu/bionic           amd64/ga-18.04-lowlatency
ubuntu/bionic           amd64/hwe-18.04
ubuntu/bionic           amd64/hwe-18.04-edge
ubuntu/bionic           amd64/hwe-18.04-lowlatency
ubuntu/bionic           amd64/hwe-18.04-lowlatency-edge

Suppose you also want a version called “Trusty” – you can import a new image by first selecting it for download, like this:

maas $PROFILE boot-source-selections create 1 \ > os="ubuntu" release="trusty" arches="amd64" subarches="*" \ > labels="*"

which returns some JSON confirming your action:

Machine-readable output follows:
    "os": "ubuntu",
    "release": "trusty",
    "arches": [
    "subarches": [
    "labels": [
    "boot_source_id": 1,
    "id": 2,
    "resource_uri": "/MAAS/api/2.0/boot-sources/1/selections/2/"

Once selected, you can start the image import with this command:

maas admin boot-resources import

which offers a shorter confirmation message:

Machine-readable output follows:
Import of boot resources started

Enabling DHCP

Once your image has been imported, you’ll want to get DHCP working, which means finding the untagged VLAN. In truth, it shouldn’t be too hard, because at this point, there still should only be one.

In order to turn on DHCP, you need to know two things besides the VLAN name (“untagged”): the fabric ID and the primary rack controller name. To start, all the fabrics will be on the same untagged VLAN, so any fabric will do. You can find a valid fabric ID by reading it from any subnet, so just pick one (e.g., and find a usable fabric ID like this:

maas $PROFILE subnet read $SUBNET_CIDR | grep fabric_id

which returns (in this example):

"fabric_id": $FABRIC_ID,

Next, find the name of the primary rack controller. It’s usually fairly obvious, but for purposes of argument, assume that it’s not known. You can get it this way:

maas $PROFILE rack-controllers read | grep hostname | cut -d '"' -f 4

This returns a hostname, which we’ll call:


Finally, you need to create an IP range for DHCP, in this case, a dynamic range:

maas $PROFILE ipranges create type=dynamic start_ip=$START_IP end_ip=$END_IP

This command returns something similar to this sample output:

Machine-readable output follows:
    "subnet": {
        "name": "",
        "description": "",
        "vlan": {
            "vid": 0,
            "mtu": 1500,
            "dhcp_on": false,
            "external_dhcp": null,
            "relay_vlan": null,
            "fabric": "fabric-2",
            "primary_rack": null,
            "name": "untagged",
            "id": 5003,
            "space": "undefined",
            "secondary_rack": null,
            "fabric_id": 2,
            "resource_uri": "/MAAS/api/2.0/vlans/5003/"
        "cidr": "",
        "rdns_mode": 2,
        "gateway_ip": null,
        "dns_servers": [],
        "allow_dns": true,
        "allow_proxy": true,
        "active_discovery": false,
        "managed": true,
        "id": 4,
        "space": "undefined",
        "resource_uri": "/MAAS/api/2.0/subnets/4/"
    "type": "dynamic",
    "start_ip": "",
    "end_ip": "",
    "user": {
        "is_superuser": true,
        "username": "admin",
        "email": "",
        "is_local": true,
        "resource_uri": "/MAAS/api/2.0/users/admin/"
    "comment": "",
    "id": 1,
    "resource_uri": "/MAAS/api/2.0/ipranges/1/"

So you should now be able to turn on DHCP like this:

maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True primary_rack=$RACK_CONTR_HOSTHNAME

If you’ve done everything correctly, you should see JSON output similar to this sample:

Machine-readable output follows:
    "vid": 0,
    "mtu": 1500,
    "dhcp_on": true,
    "external_dhcp": null,
    "relay_vlan": null,
    "fabric": "fabric-2",
    "space": "undefined",
    "primary_rack": "8dwnne",
    "secondary_rack": null,
    "name": "untagged",
    "fabric_id": 2,
    "id": 5003,
    "resource_uri": "/MAAS/api/2.0/vlans/5003/"

Spaces, fabrics, zones and subnets

Networks in large data centres can be very complex. MAAS offers comprehensive control over networking so that you have the flexibility to reconfigure racks and deploy machines as you see fit. You can isolate machine deployment not only with DNS domains, but also via subnets, spaces, zones, and fabrics. The links provide more details, but these are all basically collections:

  • subnet has the traditional meaning: a range of IP addresses covering a subset of IP addresses. Generally speaking , a subnet is a collection of IP addresses which includes at least two addresses.
  • a space is a collection of subnets that you can create with MAAS, understanding that each subnet can belong to only one space. Spaces allow multiple subnets to communicate without requiring a direct network path between them.
  • a zone is also an ad-hoc collection, but one which groups individual nodes, rather than subnets. MAAS allows you to create and edit zones at will.
  • a fabric is essentially a collection of trunked switches, allowing you to access a group of VLANs.

Here is a diagram that helps to illustrate these concepts:

VM hosts

VM hosts can give you greater control over your hardware. A VM host is a collection of individual virtual machines. You can use a VM host to compose machines into an abstraction of resources that functions like a physical machine – without building one!

There you have it: A quick tour of MAAS and its capabilities. Read on through the documentation to learn more.