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 -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

  1. Disable conflicting NTP services:

    sudo systemctl disable --now systemd-timesyncd

  2. 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"

  3. Edit PostgreSQL authentication:
    Add this line to /etc/postgresql/14/main/pg_hba.conf:

    host    $DBNAME    $DBUSER    0/0     md5

  4. Initialize MAAS with the database:

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

  5. 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

  1. Open: http://<API_HOST>:5240/MAAS
  2. Log in with your admin credentials.
  3. 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

  1. Log in:
    maas login $PROFILE $MAAS_URL $(cat api-key-file)
  2. Configure DNS:
    maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8"
  3. 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

  1. Backup your system and database.
  2. Verify Ubuntu release (lsb_release -a). Upgrade to 22.04 Jammy or 24.04 Noble as required.
  3. Verify PostgreSQL version (14 required, 16 recommended).
  4. 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

Related documentation

Last updated 4 days ago.

Help improve this document in the forum.