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)
- DNS forwarder (e.g.,
CLI setup
- Log in:
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_KEYmust 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
