How to install MAAS

Install MAAS (snap or packages)

  • Install from snap:

    sudo snap install --channel=<version> maas

    Replace <version> with the desired MAAS version.

  • Install from packages:

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

Post-install setup (POC)

There is a proof-of-concept configuration defined for the MAAS snap version only. To initialise the MAAS snap in this POC configuration, use the --help flag with maas init and follow the instructions. This POC uses the maas-test-db.

Post-install setup (production)

  1. Disable conflicting NTP:

    sudo systemctl disable --now systemd-timesyncd

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

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

     host    $MAAS_DBNAME    $MAAS_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 create admin --username=$PROFILE --email=$EMAIL_ADDRESS

Configuring and starting MAAS

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

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

MAAS CLI setup

  1. Login:
    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 SSH key:
    maas $PROFILE sshkeys create "key=$SSH_KEY"

Enabling DHCP

UI

  1. Navigate to Subnets > VLAN > Configure DHCP.
  2. Select the appropriate DHCP options (Managed or Relay).
  3. Save and apply changes.

CLI

  1. Enable DHCP:
    maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True \
    primary_rack=$PRIMARY_RACK_CONTROLLER
  2. Set 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.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

  1. Upgrade PostgreSQL: If running PostgreSQL 12, upgrade to 14.
  2. Ensure Ubuntu 22.04 (Jammy):
    lsb_release -a
    If on Ubuntu 20.04, upgrade:
    sudo do-release-upgrade --allow-third-party
  3. Add PPA and Upgrade:
    sudo apt-add-repository ppa:maas/3.5
sudo apt update && sudo apt upgrade maas
  4. Verify Installation:
    maas --version

Upgrade packages from MAAS 2.8 or earlier

  1. Backup your system completely.
  2. Ensure Ubuntu 22.04 (see steps above).
  3. Add PPA and Upgrade:
    sudo apt-add-repository ppa:maas/3.5
sudo apt update && sudo apt upgrade maas
  4. 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

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 a day ago.

Help improve this document in the forum.