How to get MAAS up and running

MAAS can be installed from snap or Debian packages, and configured for a Proof-of-Concept (POC) or a production environment.

Install MAAS (snap or packages)

Snap is the preferred method for installing MAAS. It offers simple installation & updates, strong isolation and security, and predictable file paths. To install MAAS using snap:

sudo snap install --channel=$VERSION maas

Replace $VERSION with the desired MAAS version.

MAAS can also be installed using the more traditional Debian package:

sudo apt-add-repository ppa:maas/<version>
sudo apt update
sudo apt-get -y install maas

Post-install setup (POC)

The MAAS snap can use a POC configuration with the maas-test-db snap. Enter maas init --help and follow the instructions to set up this configuration.

Post-install setup (production)

Setting up MAAS for production is a little more involved than a POC, but not particularly difficult to accomplish using the following steps:

Disable conflicting NTP:

sudo systemctl disable --now systemd-timesyncd

Configure PostgreSQL for production:

sudo apt install -y postgresql
sudo -i -u postgres psql -c "CREATE USER \"$DBUSER\" WITH ENCRYPTED PASSWORD '$DBPASS'"
sudo -i -u postgres createdb -O "$DBUSER" "$DBNAME"

Edit /etc/postgresql/14/main/pg_hba.conf, adding a line for the newly created database:
```
 host    $MAAS_DBNAME    $MAAS_DBUSER    0/0     md5
```

Initialize MAAS with the database:

sudo maas init region+rack --database-uri "postgres://$DBUSER:$DBPASS@$HOSTNAME/$DBNAME"

Create an admin user:

sudo maas create admin --username=$PROFILE --email=$EMAIL_ADDRESS

Configuring and starting MAAS

Once MAAS is up and running successfully, there are a few additional steps to fully enable it.

Checking MAAS status

To check the status of MAAS services, use:

sudo maas status

Output example:

bind9        RUNNING   pid 7999, uptime 0:09:17
dhcpd        STOPPED   Not started
postgresql   RUNNING   pid 8001, uptime 0:09:17
...

MAAS UI setup

You can set up MAAS using the Web UI:

Access the UI:
http://$API_HOST:5240/MAAS
Log in with the credentials created during installation.
DNS forwarder: Set to a suitable value (e.g., 8.8.8.8).
Image import: Select at least one Ubuntu LTS image.
SSH key import: Choose between Launchpad, GitHub, or upload a key from .ssh/id_rsa.pub.

MAAS CLI setup

You can also set up MAAS with the CLI:

maas login $PROFILE $MAAS_URL $(cat api-key-file)

Configure DNS:

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

Add an SSH key:

maas $PROFILE sshkeys create "key=$SSH_KEY"

Enabling DHCP

DHCP must be enabled before MAAS can commission and deploy machines.

UI
Subnets > VLAN > Configure DHCP > Select options > Save and apply changes

CLI

Enable DHCP:

maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True \
    primary_rack=$PRIMARY_RACK_CONTROLLER

Set the default gateway:

maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY

Notes on upgrading MAAS

The following general notes apply to an upgrade:

Review PostgreSQL Requirements: MAAS 3.5 and later require PostgreSQL 14. Upgrade instructions here.
Upgrade Ubuntu if needed: Ensure you’re running Ubuntu 22.04 (Jammy) before upgrading MAAS.
Backup your data: Always create a backup before upgrading.
Multi-node setups: Upgrade rack nodes first, then region nodes.

Upgrade to MAAS 3.6

Upgrade Snap (region + rack)

sudo snap refresh maas --channel=3.6/stable

Upgrade package (PPA-based installations)

sudo apt-add-repository ppa:maas/3.6
sudo apt update && sudo apt upgrade maas

Upgrade to MAAS 3.5

Upgrade Snap (region + rack)

sudo snap refresh maas --channel=3.5/stable

Upgrade package (PPA-based installations)

sudo apt-add-repository ppa:maas/3.5
sudo apt update && sudo apt upgrade maas

Upgrade packages from MAAS versions 2.9-3.3

Upgrade PostgreSQL: If running PostgreSQL 12, upgrade to 14.

Ensure Ubuntu 22.04 (Jammy):

lsb_release -a

If on Ubuntu 20.04, upgrade:

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

Add PPA and Upgrade:

sudo apt-add-repository ppa:maas/3.5
sudo apt update && sudo apt upgrade maas

Verify Installation:
```
maas --version
```

Upgrade packages from MAAS 2.8 or earlier

Backup your system completely.
Ensure Ubuntu 22.04 (see steps above).

Add PPA and Upgrade:

sudo apt-add-repository ppa:maas/3.5
sudo apt update && sudo apt upgrade maas

If the upgrade fails, restore from backup and consider a fresh installation.

Upgrade to MAAS 3.4

Upgrade snap

sudo snap refresh maas --channel=3.4/stable

Upgrade package

sudo apt-add-repository ppa:maas/3.4
sudo apt update && sudo apt upgrade maas

Follow the same Ubuntu and PostgreSQL upgrade steps as above.

Upgrade to MAAS 3.3

Upgrade snap

sudo snap refresh maas --channel=3.3/stable

Upgrade packages

sudo apt-add-repository ppa:maas/3.3
sudo apt update && sudo apt upgrade maas

PostgreSQL 12 is deprecated in MAAS 3.3 and unsupported in 3.5. Upgrade to PostgreSQL 14 before proceeding.

Additional notes

The following general notes apply to an upgrade:

Review PostgreSQL Requirements: MAAS 3.6 supports Postgres 14 and recommends PostgreSQL 16. Upgrade instructions to Postgres 14 here. Upgrade instructions to Postgres 16 here.
Upgrade Ubuntu if needed: Ensure you’re running Ubuntu 24.04 (Noble) before upgrading MAAS.
Backup your data: Always create a backup before upgrading.
Multi-node setups: Upgrade rack nodes first, then region nodes

Avoiding NTP conflicts

If you experience time synchronization issues:

sudo systemctl disable --now systemd-timesyncd

BMC migration issue (MAAS 3.3+)

Ensure unique BMC IP/username/password combinations before upgrading to avoid migration failures.

Verification steps

After upgrading, confirm MAAS is running correctly:

lsb_release -a  # Ensure Ubuntu version is correct
maas --version  # Verify MAAS version

Last updated 16 days ago.

Help improve this document in the forum.