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:
- Login:
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):
If on Ubuntu 20.04, upgrade:lsb_release -asudo 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