How to install MAAS(deb/2.9/CLI)

Docs
1

About installing MAAS

MAAS can be installed in either of two configurations: test or production. The test configuration uses a small PostgreSQL database (in a separate snap), designed for use with MAAS. The full-up production configuration uses a separate PostgreSQL database for performance and scalability.

MAAS is relatively easy to install and configure using Debian packages.

MAAS initialisation modes reference

MAAS supports the following modes, which dictate what services will run on the local system:

Mode Region Rack Database Description
region X Region API server only
rack X Rack controller only
region+rack X X Region API server and rack controller
none Reinitialises MAAS and stops services

About SSH keys

MAAS uses your Launchpad or Github SSH keys to access machines that have been deployed. Normally, you enter this key during the initialisation of MAAS. If you don’t have a key associated with either of these services, you will have an opportunity to paste your public key into the MAAS SSH key list, after you’ve started MAAS for the first time as part of the welcome screens.

About the MAAS URL

All run modes (except none) prompt for a MAAS URL, interpreted differently depending on the mode:

  • region: Used to create a new region controller.
  • rack: Used to locate the region controller.

About the shared secret

The ‘rack’ and ‘region+rack’ modes will additionally ask for a shared secret that will allow the new rack controller to register with the region controller.

How to install MAAS

This article will show you:

How to check system requirements for MAAS

Before installing MAAS for the first time, you should make sure that the target system meets the minimum requirements for the machines that run MAAS, which vary widely depending on local implementation and usage. Below, you will find resource estimates based on MAAS components and operating system (Ubuntu Server). We consider both a test configuration (for proof of concept) and a production environment.

Requirements for a test environment

Here is a proof-of-concept scenario, with all MAAS components installed on a single host. This scenario assumes two complete sets of images (latest two Ubuntu LTS releases) for a single architecture (amd64).

Memory (MB) CPU (GHz) Disk (GB)
Region controller (minus PostgreSQL) 512 0.5 5
PostgreSQL 512 0.5 5
Rack controller 512 0.5 5
Ubuntu Server (including logs) 512 0.5 5

Based on this table, the approximate requirements for this scenario are 2 GB memory, 2 GHz CPU, and 20 GB of disk space.

Requirements for a production environment

Here is a production scenario designed to handle a high number of sustained client connections. This scenario implements both high availability (region and rack) and load balancing (region). MAAS reserves extra space for images (database and rack controller), while some images, such as those for Microsoft Windows, may require a lot more – so plan accordingly.

Memory (MB) CPU (GHz) Disk (GB)
Region controller (minus PostgreSQL) 2048 2.0 5
PostgreSQL 2048 2.0 20
Rack controller 2048 2.0 20
Ubuntu Server (including logs) 512 0.5 5

So, based on the above, the approximate requirements for this scenario are:

  1. A region controller (including PostgreSQL) installed on one host, with 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space.
  2. A duplicate region controller (including PostgreSQL) on a second host, also with 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space.
  3. A rack controller installed on a third host, with 2.5 GB memory, 2.5 GHz CPU, and 40 GB of disk space.
  4. A duplicate rack controller on a fourth host, also with 2.5 GB memory, 2.5 GHz CPU, and 40 GB of disk space.

The tables above refer to MAAS infrastructure only. They do not cover the resources needed by subsequently-added nodes. Note that machines should have IPMI-based BMC controllers for power cycling, see Power management for more details.

Some examples of factors that influence hardware specifications include:

  1. the number of connecting clients (client activity)
  2. how you decide to distribute services
  3. whether or not you use high availability/load balancing.
  4. the number of images that you choose to store (disk space affecting PostgreSQL and the rack controller)

Also, this discussion does not take into account a possible local image mirror, which would be a large consumer of disk space.

One rack controller should only service 1000 machines or less, regardless of how you distribute them across subnets. There is no load balancing at the rack level, so you will need additional, independent rack controllers. Each controller must service its own subnet(s).

Please see the release notes, as directed above, to install MAAS 3.2 Beta.

Please see the release notes, as directed above, to install MAAS 3.2 Beta.

How to upgrade from an earlier snap version to MAAS 3.1

If you want to upgrade from a earlier snap version to the 3.1 snap, and you are using a region+rack configuration, use this command:

$ sudo snap refresh --channel=3.1/stable maas

After entering your password, the snap will refresh from the 3.1 channel. You will not need to re-initialise MAAS.

If you are using a multi-node maas deployment with separate regions and racks, you should first run the upgrade command above for rack nodes, then for region nodes.

How to do a fresh snap install of MAAS 3.1

To install MAAS 3.1 from a snap, simply enter the following:

$ sudo snap install --channel=3.1/stable maas

After entering your password, the snap will download and install from the 3.1 channel.

How to ugprade from MAAS 3.0 to MAAS 3.1

To upgrade from MAAS 3.0 to MAAS 3.1:

  1. Back up your MAAS server completely; the tools and media are left entirely to your discretion. Just be sure that you can definitely restore your previous configuration, should this procedure fail to work correctly.

  2. Add the MAAS 3.1 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo apt-add-repository ppa:maas/3.1
  1. Run the MAAS upgrade like this:
sudo apt update
sudo apt upgrade maas

  1. Check your running MAAS install (by looking at the information on the bottom of the machine list) to make sure you’re running the 3.1 release.

  2. If this didn’t work, you will need to restore from the backup you made in step 1, and consider obtaining separate hardware to install MAAS 3.1.

How to upgrade from 2.8 or lower to MAAS 3.1

If you are running MAAS 2.8 or lower, you can upgrade directly to MAAS 3.1. You must first make sure that the target system is running Ubuntu 20.04 LTS or higher, by executing the following command:

lsb_release -a

The response should look something like this:

Distributor ID:	Ubuntu
Description:	Ubuntu xx.yy
Release:	xx.yy
Codename:	$RELEASE_NAME

The minimum “xx.yy” required for MAAS 3.0 is “20.04,” code-named “focal.”

If you are currently running Ubuntu bionic 18.04 LTS, you can upgrade to focal 20.04 LTS with the following procedure:

  1. Upgrade the release:
sudo do-release-upgrade --allow-third-party

  1. Accept the defaults for any questions asked by the upgrade script.

  2. Reboot the machine when requested.

  3. Check whether the upgrade was successful:

lsb_release -a

A successful upgrade should respond with output similar to the following:

Distributor ID:	Ubuntu
Description:	Ubuntu 20.04(.nn) LTS
Release:	20.04
Codename:	focal

If you’re upgrading from MAAS version 2.8 or lower to version 3.1: While the following procedures should work, note that they are untested. Use at your own risk. Start by making a verifiable backup; see step 1, below.

  1. Back up your MAAS server completely; the tools and media are left entirely to your discretion. Just be sure that you can definitely restore your previous configuration, should this procedure fail to work correctly.

  2. Add the MAAS 3.1 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo apt-add-repository ppa:maas/3.1
  1. Run the release upgrade like this, answering any questions with the given default values:
sudo do-release-upgrade --allow-third-party
  1. Check whether your upgrade has been successful by entering:
lsb_release -a

If the ugprade was successful, this command should yield output similar to the following:

No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 20.04(.nn) LTS
Release:	20.04
Codename:	focal

  1. Check your running MAAS install (by looking at the information on the bottom of the machine list) to make sure you’re running the 3.1 release.

  2. If this didn’t work, you will need to restore from the backup you made in step 1, and consider obtaining separate hardware to install MAAS 3.1.

How to do a fresh install of MAAS 3.1 from packages

The recommended way to set up an initial MAAS environment is to put everything on one machine:

sudo apt-add-repository ppa:maas/3.1
sudo apt update
sudo apt-get -y install maas

Executing this command leads you to a list of dependent packages to be installed, and a summary prompt that lets you choose whether to continue with the install:

Choosing “Y” proceeds with a standard apt package install.

Distributed environment

For a more distributed environment, you can place the region controller on one machine:

sudo apt install maas-region-controller

and the rack controller on another:

sudo apt install maas-rack-controller
sudo maas-rack register

These two steps will lead you through two similar apt install sequences.

How to upgrade from an earlier snap version to MAAS 3.0

If you want to upgrade from a earlier snap version to the 3.0 snap, and you are using a region+rack configuration, use this command:

$ sudo snap refresh --channel=3.0/stable maas

After entering your password, the snap will refresh from the 3.0 channel. You will not need to re-initialise MAAS.

If you are using a multi-node maas deployment with separate regions and racks, you should first run the upgrade command above for rack nodes, then for region nodes.

How to do a fresh snap install of MAAS 3.0

To install MAAS 3.0 from a snap, simply enter the following:

$ sudo snap install --channel=3.0/stable maas

After entering your password, the snap will download and install from the 3.0 stable channel.

How to ugprade from MAAS 2.9 to MAAS 3.0

  1. Back up your MAAS server completely; the tools and media are left entirely to your discretion. Just be sure that you can definitely restore your previous configuration, should this procedure fail to work correctly.

  2. Add the MAAS 3.0 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo apt-add-repository ppa:maas/3.0
  1. Run the MAAS upgrade like this:
sudo apt update
sudo apt upgrade maas

  1. Check your running MAAS install (by looking at the information on the bottom of the machine list) to make sure you’re running the 3.0 release.

  2. If this didn’t work, you will need to restore from the backup you made in step 1, and consider obtaining separate hardware to install MAAS 3.0.

How to upgrade from 2.8 or lower to MAAS 3.0

If you are running MAAS 2.8 or lower, you must also make sure that the target system is running Ubuntu 20.04 LTS or higher, by executing the following command:

lsb_release -a

The response should look something like this:

Distributor ID:	Ubuntu
Description:	Ubuntu xx.yy
Release:	xx.yy
Codename:	$RELEASE_NAME

The minimum “xx.yy” required for MAAS 3.0 is “20.04,” code-named “focal.”

If you are currently running Ubuntu bionic 18.04 LTS, you can upgrade to focal 20.04 LTS with the following procedure:

  1. Upgrade the release:
sudo do-release-upgrade --allow-third-party

  1. Accept the defaults for any questions asked by the upgrade script.

  2. Reboot the machine when requested.

  3. Check whether the upgrade was successful:

lsb_release -a

A successful upgrade should respond with output similar to the following:

Distributor ID:	Ubuntu
Description:	Ubuntu 20.04(.nn) LTS
Release:	20.04
Codename:	focal

If you’re upgrading from MAAS version 2.8 or lower to version 3.0: While the following procedures should work, note that they are untested. Use at your own risk. Start by making a verifiable backup; see step 1, below.

  1. Back up your MAAS server completely; the tools and media are left entirely to your discretion. Just be sure that you can definitely restore your previous configuration, should this procedure fail to work correctly.

  2. Add the MAAS 3.0 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo apt-add-repository ppa:maas/3.0
  1. Run the release upgrade like this, answering any questions with the given default values:
sudo do-release-upgrade --allow-third-party
  1. Check whether your upgrade has been successful by entering:
lsb_release -a

If the ugprade was successful, this command should yield output similar to the following:

No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 20.04(.nn) LTS
Release:	20.04
Codename:	focal

  1. Check your running MAAS install (by looking at the information on the bottom of the machine list) to make sure you’re running the 3.0 release.

  2. If this didn’t work, you will need to restore from the backup you made in step 1, and consider obtaining separate hardware to install MAAS 3.0.

How to do a fresh install of MAAS 3.0 from packages

The recommended way to set up an initial MAAS environment is to put everything on one machine:

sudo apt-add-repository ppa:maas/3.0
sudo apt update
sudo apt-get -y install maas

Executing this command leads you to a list of dependent packages to be installed, and a summary prompt that lets you choose whether to continue with the install:

Choosing “Y” proceeds with a standard apt package install.

Distributed environment

For a more distributed environment, you can place the region controller on one machine:

sudo apt install maas-region-controller

and the rack controller on another:

sudo apt install maas-rack-controller
sudo maas-rack register

These two steps will lead you through two similar apt install sequences.

How to upgrade from an earlier snap version to MAAS 2.9

If you want to upgrade from a earlier snap version to the 2.9 snap, and you are using a region+rack configuration, use this command:

$ sudo snap refresh --channel=3.0/stable maas

After entering your password, the snap will refresh from the 3.0 channel. You will not need to re-initialise MAAS.

If you are using a multi-node maas deployment with separate regions and racks, you should first run the upgrade command above for rack nodes, then for region nodes.

How to do a fresh snap install of MAAS 2.9

To install MAAS 2.9 from a snap, simply enter the following:

$ sudo snap install --channel=2.9/stable maas

After entering your password, the snap will download and install from the 2.9 stable channel.

How to upgrade from MAAS 2.8 or lower to MAAS 2.9

MAAS 2.8 is the last supported version for Ubuntu 18.04 LTS. Newer versions of MAAS will not be back-portable, and consequently, to upgrade to MAAS 2.9 and all future versions, you will also need to upgrade the base operating system to Ubuntu 20.04. You do these two operations all at once, with the following procedure:

sudo add-apt-repository ppa:maas/2.9

You will get a message similar to this:

 For stable releases of 2.9.x
 More info: https://launchpad.net/~maas/+archive/ubuntu/2.9
Press [ENTER] to continue or Ctrl-c to cancel adding it.

Hit:1 http://security.ubuntu.com/ubuntu bionic-security InRelease
Hit:2 http://ppa.launchpad.net/maas/2.8/ubuntu bionic InRelease          
Hit:3 http://archive.ubuntu.com/ubuntu bionic InRelease                  
Hit:4 http://archive.ubuntu.com/ubuntu bionic-updates InRelease                                     
Ign:5 http://ppa.launchpad.net/maas/2.9/ubuntu bionic InRelease          
Hit:6 http://archive.ubuntu.com/ubuntu bionic-backports InRelease        
Err:7 http://ppa.launchpad.net/maas/2.9/ubuntu bionic Release                 
  404  Not Found [IP: 91.189.95.85 80]
Reading package lists... Done
E: The repository 'http://ppa.launchpad.net/maas/2.9/ubuntu bionic Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

This message seems to indicate that nothing happened, but, in fact, this command still creates the file:

/etc/apt/sources.list.d/maas-ubuntu-2_9-bionic.list

This file identifies the path to the 2.9 PPA, even though it incorrectly implies there’s a Bionic release there:

deb http://ppa.launchpad.net/maas/2.9/ubuntu bionic main

Still, that’s enough for do-release-upgrade to figure out that there is a 2.9 PPA, and when it checks, it will find a Focal version of MAAS, which it will bring over and install in place of 2.8. It isn’t necessary to stop MAAS or do anything else, except go ahead and run the upgrade:

sudo do-release-upgrade --allow-third-party

This command will produce a lot of output, ask you a few questions (for which the defaults are usually fine), and eventually ask you to reboot. Once your machine has come back up, you can check whether your upgrade has been successful by entering:

lsb_release -a

If the ugprade was successful, this command should yield output similar to the following:

No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 20.04.1 LTS
Release:	20.04
Codename:	focal

You have now upgraded to the Ubuntu 20.04 LTS base, and if you check your running MAAS install, you should see that the version has been updated to the latest stable 2.9 release.

How to do a fresh install of MAAS 2.9 from packages

The recommended way to set up an initial MAAS environment is to put everything on one machine:

sudo apt-get -y install maas

Executing this command leads you to a list of dependent packages to be installed, and a summary prompt that lets you choose whether to continue with the install:

Choosing “Y” proceeds with a standard apt package install.

Distributed environment

For a more distributed environment, you can place the region controller on one machine:

sudo apt install maas-region-controller

and the rack controller on another:

sudo apt install maas-rack-controller
sudo maas-rack register

These two steps will lead you through two similar apt install sequences.

How to initialise MAAS for a test or POC environment

You can initialise MAAS as a compact version for testing. To achieve this, we provide a separate snap, called maas-test-db, which contains a PostgreSQL database for use in testing and evaluating MAAS. The following instructions will help you take advantage of this test configuration.

Once MAAS is installed, you can use the --help flag with maas init to get relevant instructions:

$ sudo maas init --help
usage: maas init [-h] {region+rack,region,rack} . . .

Initialise MAAS in the specified run mode.

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

run modes:
  {region+rack,region,rack}
    region+rack         Both region and rack controllers
    region              Region controller only
    rack                Rack controller only

When installing region or rack+region modes, MAAS needs a
PostgreSQL database to connect to.

If you want to set up PostgreSQL for a non-production deployment on
this machine, and configure it for use with MAAS, you can install
the maas-test-db snap before running 'maas init':
    sudo snap install maas-test-db
    sudo maas init region+rack --database-uri maas-test-db:-#,

We’ll quickly walk through these instructions to confirm your understanding. First, install the maas-test-db snap:

sudo snap install maas-test-db

Note that this step installs a a running PostgreSQL and a MAAS-ready database instantiation. When it’s done, you can double check with a built-in PostgreSQL shell:

$ sudo maas-test-db.psql
psql (12.4)
Type "help" for help.

postgres=# \l

This will produce a list of databases, one of which will be maasdb, owned by maas. Note that this database is still empty because MAAS is not yet initialised and, hence, is not yet using the database. Once this is done, you can run the maas init command:

sudo maas init region+rack --database-uri maas-test-db:-#,

After running for a moment, the command will prompt you for a MAAS URL; typically, you can use the default:

MAAS URL [default=http://10.45.222.159:5240/MAAS]:

When you’ve entered a suitable URL, or accepted the default, the following prompt will appear:

MAAS has been set up.

If you want to configure external authentication or use
MAAS with Canonical RBAC, please run

  sudo maas configauth

To create admins when not using external authentication, run

  sudo maas createadmin

Let’s assume you just want a local testing user named admin:

$ sudo maas createadmin
Username: admin
Password: ******
Again: ******
Email: admin@example.com
Import SSH keys [] (lp:user-id or gh:user-id): gh:yourusername

At this point, MAAS is basically set up and running. You can confirm this with sudo maas status. If you need an API key, you can obtain this with sudo maas apikey --username yourusername. Now you will be able to test and evaluate MAAS by going to the URL you entered or accepted above and entering your admin username and password.

Initialise MAAS for a production configuration

To install MAAS in a production configuration, you need to setup PostgreSQL, as described below.

Setting up PostgreSQL from scratch

To set up PostgreSQL, even if it’s running on a different machine, you can use the following procedure:

  1. You will need to install PostgreSQL on the machine where you want to keep the database. This can be the same machine as the MAAS region/rack controllers or a totally separate machine. If PostgreSQL (version 10 or better) is already running on your target machine, you can skip this step. To install PostgreSQL, run these commands:

     sudo apt update -y
 sudo apt install -y postgresql

  2. You want to make sure you have a suitable PostgreSQL user, which can be accomplished with the following command, where $MAAS_DBUSER is your desired database username, and $MAAS_DBPASS is the intended password for that username. Note that if you’re executing this step in a LXD container (as root, which is the default), you may get a minor error, but the operation will still complete correctly.

     sudo -u postgres psql -c "CREATE USER \"$MAAS_DBUSER\" WITH ENCRYPTED PASSWORD '$MAAS_DBPASS'"

  3. Create the MAAS database with the following command, where $MAAS_DBNAME is your desired name for the MAAS database (typically known as maas). Again, if you’re executing this step in a LXD container as root, you can ignore the minor error that results.

     sudo -u postgres createdb -O "$MAAS_DBUSER" "$MAAS_DBNAME"

  4. Edit /etc/postgresql/10/main/pg_hba.conf and add a line for the newly created database, replacing the variables with actual names. You can limit access to a specific network by using a different CIDR than 0/0.

     host    $MAAS_DBNAME    $MAAS_DBUSER    0/0     md5

  5. You can then initialise MAAS via the following command:

     sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"

You should use localhost for $HOSTNAME if you’re running PostgreSQL on the same box as MAAS.

Don’t worry; if you leave out any of the database parameters, you’ll be prompted for those details.

How to create a MAAS user

You will need to create a MAAS administrator user to access the web UI:

sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS

$PROFILE is the administrative MAAS username you wish to create. $EMAIL_ADDRESS is an email address you may type in at random (currently, MAAS does not use this email address).

The createadmin option will ask for an SSH key. If you have an SSH key associated with your launchpad or github accounts, you can enter the username here to use the associated key. For launchpad, just enter lp:username, and for github, enter gh:username at the prompt. In both cases, the actual username has to be supplied after the lp: or gh: prefix.

How to check the status of MAAS services

You can check the status of running services with:

sudo maas status

Typically, the output looks something like this:

bind9                            RUNNING   pid 7999, uptime 0:09:17
dhcpd                            STOPPED   Not started
dhcpd6                           STOPPED   Not started
ntp                              RUNNING   pid 8598, uptime 0:05:42
postgresql                       RUNNING   pid 8001, uptime 0:09:17
proxy                            STOPPED   Not started
rackd                            RUNNING   pid 8000, uptime 0:09:17
regiond:regiond-0                RUNNING   pid 8003, uptime 0:09:17
regiond:regiond-1                RUNNING   pid 8008, uptime 0:09:17
regiond:regiond-2                RUNNING   pid 8005, uptime 0:09:17
regiond:regiond-3                RUNNING   pid 8015, uptime 0:09:17
tgt                              RUNNING   pid 8040, uptime 0:09:15

How to re-initialise MAAS

It is also possible to re-initialise MAAS to switch modes. For example, to switch from rack to region:

sudo maas init region

How to list additional MAAS initialisation options

The init command can takes optional arguments. To list them, as well as read a brief description of each, you can enter:

sudo maas init --help

How to configure MAAS

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, 192.168.43.251:5240/MAAS. 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 http://192.168.43.251:5240/MAAS/api/2.0/.

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

drill down:
COMMAND
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.
boot-source-selection
Manage a boot source selection.
boot-source-selections
Manage the collection of boot source selections.
boot-sources Manage the collection of boot sources.
commissioning-script
Manage a custom commissioning script.
commissioning-scripts
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.
dnsresource-records
Manage DNS resource records (e.g. CNAME, MX, NS, SRV,
TXT)
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.
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
MAAS.
package-repositories
Manage the collection of all Package Repositories in
MAAS.
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
MAAS.
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
MAAS.
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
nodes.
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.

Configuration

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

How to set upstream 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="8.8.8.8"

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

How to set up 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"

How to import 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:

Success.
Machine-readable output follows:
{
    "os": "ubuntu",
    "release": "trusty",
    "arches": [
        "amd64"
    ],
    "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:

Success.
Machine-readable output follows:
Import of boot resources started

How to enable 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., 192.168.123.0/24) 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:

$RACK_CONTR_HOSTNAME

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:

Success.
Machine-readable output follows:
{
    "subnet": {
        "name": "192.168.123.0/24",
        "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": "192.168.123.0/24",
        "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": "192.168.123.190",
    "end_ip": "192.168.123.253",
    "user": {
        "is_superuser": true,
        "username": "admin",
        "email": "admin@admin.com",
        "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_HOSTNAME

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

Success.
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/"
}

Once you’ve successfully installed MAAS (regardless of method), you can now login here:

http://${API_HOST}:5240/MAAS

where $API_HOST is the hostname or IP address of the region API server, which was set during installation. You will see a screen like this:

Log in at the prompts, with the login information you created when initialising MAAS.

Configuration

After a fresh MAAS installation, the web UI presents a couple of welcome screens. From these screens, you can set many system-wide options, including connectivity, image downloads, and authentication keys.

Your main concerns for this experiment are the DNS forwarder, the Ubuntu image import section, and the SSH public key, though you might want to set the region name to something memorable, since this text will appear at the bottom of every MAAS screen in this install domain. Set the DNS forwarder to something obvious, e.g., 8.8.8.8, Google’s DNS server. Set this to your own internal DNS server if you know the IP address.

Select an Ubuntu image to import, noting that you may be required to select at least one LTS version, depending upon the version of MAAS that snap installed. In this example, we’ve already chosen an image, and downloading is partially complete.

When you click on “Continue,” the screen will shift to a screen labelled, “SSH keys for admin:”

In the source drop-down, select “Launchpad,” “Github,” or “Upload.” If you choose one of the first two, you will need to enter your username for that service. For example, if you want to upload your SSH public key from Launchpad, you would enter:

lp:<username>

Likewise, if you want to upload your github public SSH key, you would enter:

gh:<username>

If you want to use your existing public key from your home directory, you can select “Upload”and then copy your entire public key from .ssh/id_rsa.pub (or wherever you may have stored the key):

and paste it into the block labelled “Public key.” Finally, press the “Import” button to import this key:

With this complete, you’ll see that MAAS has been successfully set up. Click ‘Go to the Dashboard’ to proceed.

Note that you may have to wait a few moments for your selected images to sync locally.

How to enable DHCP

Before moving forward with MAAS, you’ll want to enable DHCP. You can do this very easily from the web UI by selecting “Subnets” from the top menu, choosing the VLAN on which you want to enable DHCP, and select the button marked, “Enable DHCP.”

About network discovery

The Dashboard landing page lists non-registered devices that MAAS detected automatically on the network. This network discovery process allows you to easily add or map devices already connected to your network – devices that you may not necessarily want to manage with MAAS.

2

Small typo there, it says gp:username instead of gh:username.

1 Like
3

:slight_smile: nice catch, @tvon! thanks for the pointer. will fix today.

4

do-release-upgrade command doesn’t have the option --allow-third-parties on Ubuntu 18

$ sudo do-release-upgrade --allow-third-parties
Usage: do-release-upgrade [options]

do-release-upgrade: error: no such option: --allow-third-parties

5

@jsutherl, it’s a typo. should be “–allow-third-party” (singular). it should be fixed now, sorry about that.