How to get MAAS up and running

This guide shows you how to install MAAS, set it up for either a Proof-of-Concept (POC) or a production environment, and verify that it is working.

Prerequisites

A host running Ubuntu 22.04 LTS (Jammy) or newer.
Administrative privileges (sudo) on the host.
Network access to download snaps or packages.
(Production only) A PostgreSQL server (version 14 or newer recommended).
(Production only) A plan for DNS forwarder and DHCP scope.

Install MAAS

Option 1 – Snap (recommended)

sudo snap install --channel=<version>/stable maas

Replace <version> with the desired MAAS version (for example, 3.6).

Option 2 – Debian packages

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

Post-install setup

POC setup

Install the test database and initialize MAAS:

sudo snap install maas-test-db
maas init --help

Follow the prompts to configure the POC environment.

Production setup

Disable conflicting NTP services:

sudo systemctl disable --now systemd-timesyncd

Install and configure PostgreSQL:

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 PostgreSQL authentication:
Add this line to /etc/postgresql/14/main/pg_hba.conf:
```
host    $DBNAME    $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 createadmin --username=$PROFILE --email=$EMAIL_ADDRESS

Configure and start MAAS

Check MAAS service status

sudo maas status

Example:

bind9        RUNNING
dhcpd        STOPPED
postgresql   RUNNING

Web UI setup

Open: http://<API_HOST>:5240/MAAS
Log in with your admin credentials.
Configure:
- DNS forwarder (e.g., 8.8.8.8)
- At least one Ubuntu LTS image
- SSH key (Launchpad, GitHub, or upload from ~/.ssh/id_rsa.pub)

CLI setup

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 ($SSH_KEY must be set to a valid SSH key):
```
maas $PROFILE sshkeys create "key=$SSH_KEY"
```

Enable DHCP

Web UI

Go to Subnets > VLAN > Configure DHCP
Select options
Save and apply

CLI

Find the subnet CIDR and fabric you want using this expression:

maas $PROFILE subnets read | jq -r '
  ["subnet", "|", "fabric ID", "|", "gateway IP"],          # header                                    
  (.[] | [ .cidr, "|", (.vlan.fabric_id|tostring), "|", .gateway_ip ]) #rows
  | @tsv
' | column -t

Find the precise name of the primary rack controller with this expression, which always finds the primary rack, regardless of how many racks are active:

maas $PROFILE rack-controllers read | jq -r '.[] | .interface_set[] | .vlan?.primary_rack // empty'

Plug those values into the following commands to configure DHCP:

maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True primary_rack=$PRIMARY_RACK_CONTROLLER
maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY

Upgrading MAAS

General steps

Backup your system and database.
Verify Ubuntu release (lsb_release -a). Upgrade to 22.04 Jammy or 24.04 Noble as required.
Verify PostgreSQL version (14 required, 16 recommended).
Upgrade rack nodes first, then region nodes.

Upgrade commands

Snap

sudo snap refresh maas --channel=<version>/stable

Debian package (PPA)

sudo apt-add-repository ppa:maas/<version>
sudo apt update && sudo apt upgrade maas

Version-specific notes

MAAS 3.6: PostgreSQL 14+ supported; PostgreSQL 16 recommended.
MAAS 3.5: Requires PostgreSQL 14.
MAAS 3.3: PostgreSQL 12 deprecated. Upgrade to 14 before proceeding.
MAAS 2.8 or earlier: Full backup required. Fresh install recommended if upgrade fails.

Troubleshooting notes

NTP conflicts:

sudo systemctl disable --now systemd-timesyncd

BMC migration (3.3+): Ensure unique BMC IP/username/password combinations.

Verification

After installation or upgrade:

lsb_release -a   # Verify Ubuntu release
maas --version   # Verify MAAS version
sudo maas status # Verify services running