Offline docs (switch to live docs)                          UI-only  CLI-only

How to install MAAS

You can't use MAAS unless you install it

Errors or typos? Topics missing? Hard to read? Let us know!

This page explains how to install MAAS from scratch. If you're already running MAAS, it's probably easier to upgrade.

Note that support for PostgreSQL version 12 is deprecated for MAAS version 3.4, and will be discontinued in MAAS 3.5. We recommend upgrading to PostgreSQL version 14 before installing MAAS 3.4.

To install MAAS 3.4 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Enter the following command:

    nohighlight sudo snap install --channel=3.4 maas

  3. Enter your account password.

At this point, the snap will download and install from the 3.4 channel.

Some installation notes

When installing MAAS on Ubuntu, there can be conflicts between the existing NTP client, systemd-timesyncd, and the NTP client/server provided by MAAS, chrony. This can lead to time synchronization issues, especially if MAAS is configured with different upstream NTP servers than the ones used by systemd-timesyncd. To avoid conflicts, users can manually disable and stop systemd-timesyncd using the following command:

sudo systemctl disable --now systemd-timesyncd

Also note that support for PostgreSQL 12 has been deprecated in MAAS 3.3 and will be discontinued in MAAS 3.5.

Initialise MAAS for a test or POC

To initialise the MAAS snap in a test/POC configuration, simply use the --help flag with maas init and follow the instructions.

Initialise MAAS for production

To install MAAS in a production configuration:

  1. Install PostgreSQL on any machine where you want to keep the database with the following commands:

    nohighlight sudo apt update -y sudo apt install -y postgresql

  2. Create desired values for the following variables (replace them in the commands below):

    nohighlight $MAAS_DBUSER = ___________ $MAAS_DBPASS = ___________ $MAAS_DBNAME = ___________ $HOSTNAME = _________

Note that for most situations, you can use localhost for $HOSTNAME.

  1. Create a suitable PostgreSQL user:

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

  2. Create the MAAS database:

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

  3. Edit /etc/postgresql/14/main/pg_hba.conf and add a line for the newly created database:

    nohighlight host $MAAS_DBNAME $MAAS_DBUSER 0/0 md5

  4. Initialise MAAS via the following command:

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

Check the status of MAAS services

To check the status of running services, enter:

sudo maas status

Typical output looks 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

Your mileage may vary.

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

Configure MAAS

To configure MAAS for first-time use:

  1. Access MAAS at this address, where $API_HOST is the hostname or IP address of the region API server, which was set during installation:

    http://${API_HOST}:5240/MAAS 2. Log in at the prompts, with the login information you created when initialising MAAS.

  2. On the first welcome screen, set the DNS forwarder to a suitable value, e.g., 8.8.8.8. This could be your own internal DNS server, if you have one.

  3. Select an Ubuntu image to import; you may be required to select at least one LTS version.

  4. Click Continue; a screen labelled, “SSH keys for admin:” appears.

  5. In the Source drop-down, select “Launchpad,” “Github,” or “Upload.”

  6. If you want to upload your SSH public key from Launchpad, you would enter the following, where <username> is your Launchpad username:

    nohighlight lp:<username>

  7. If you want to upload your github public SSH key, you would enter the following, where <username> is your GitHub username:

    nohighlight gh:<username>

  8. If you want to use your existing public key from your home directory, select Upload.

  9. Copy your entire public key from .ssh/id_rsa.pub (or wherever you may have stored the key).

  10. Paste the public key into the block labelled “Public key.”

  11. Press the “Import” button to import this key.

  12. You should see a message that MAAS has been successfully set up. Click Go to the Dashboard to proceed.

  13. Select Subnets from the top menu.

  14. Choose the VLAN on which you want to enable DHCP.

  15. Select Enable DHCP.

You should now be able to add, commission, and deploy machines.