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

  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

On Ubuntu 20.04, postgresql is version 12 so this path doesn’t exist.

1 Like

thanks for reading so closely. kudos for catching this.

I think this should be --database-uri maas-test-db:///

Maybe in the following paragraph, we could mention that gh stands for github, and this should be and existing github username from which ssh keys would be imported, e.g. gh:your-github-username

hiiiii! Sorry to bump an old topic, but I uh… was testing out the install with the maas-test-db instructions. After running the sudo maas init region+rack --database-uri maas-test-db:/// command and confirming the MAAS URL, I realized I probably didn’t want to use the default IP of the KVM machine I’m running in (as it doesn’t have a guaranteed address since this is a test environment) and hit ctrl+c.

This led to a borked install and some interesting errors (no stdout after the init command finished, running maas createadmin led to a weird error, etc). I figured out that I needed to remove/reinstall the maas-test-db snap, but it might be worth noting on the page how to get back to a ‘clean install’ for similarly indecisive individuals such as myself.

1 Like

lol. good point. got some suggested text? we crowdsource doc when we can…

1 Like

How about something like… (assuming that I’m correct in that the database needs to be sandblasted away):

How to uninstall/revert to a clean install

If something goes wrong during the installation process, it might be necessary to return to a clean state before proceeding with the tutorial. As MAAS stores configuration information in database, the DB must be cleaned up.

If you used the maas-test-db snap, it’s as simple as uninstalling and reinstalling the snap:

  1. sudo snap remove maas-test-db
  2. sudo snap install maas-test-db

Since I have no idea yet what is actually stored in the database, I have no idea what you’d need to remove if you configured it with a stand alone install hah! But.

1 Like

nice. that’s a great starting point for the test version, and I see ways to do something similar for the production version, too. lemme play with this and come back to see if i’ve captured your thoughts adequately! :slight_smile:

1 Like

Yay! That’s awesome!

I know this isn’t the place to suggest it, but I wonder if maas could be configured to capture ctrl-c events and print back that stopping now may lead to an inconsistent state, etc, and to hit ctrl-c again to confirm killing the process… I should figure out where to go make that suggestion, hah.

heh. there’s a doc for that!

1 Like

The documentation for package installation of MAAS suggests adding “ppa:maas/3.3-next”, but that repo is for beta builds of MAAS. Shouldn’t people be using “ppa:maas/3.3” instead for normal (non-developmental) installs?

Hello,

Maybe I’m missing a point but, when installing MAAS 3.2+ with PGSQL14 appears to be having some problems.

When I edit like you did :

with :

When I init the cluster I get a :

sudo maas init region+rack --database-uri “postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME”
MAAS URL [default=http://172.16.XX.YY:5240/MAAS]:
Failed to perfom migrations:ations
Traceback (most recent call last):
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 217, in ensure_connection
self.connect()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 195, in connect
self.connection = self.get_new_connection(conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/postgresql/base.py”, line 178, in get_new_connection
connection = Database.connect(**conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/psycopg2/init.py”, line 126, in connect
conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
psycopg2.OperationalError: could not connect to server: Connection refused
Is the server running on host “172.16.XX.YY” and accepting
TCP/IP connections on port 5432?

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
File “/snap/maas/26274/bin/maas-region”, line 8, in
sys.exit(run())
File “/snap/maas/26274/lib/python3.8/site-packages/maasserver/region_script.py”, line 77, in run
run_django(is_snap, is_devenv)
File “/snap/maas/26274/lib/python3.8/site-packages/maasserver/region_script.py”, line 66, in run_django
management.execute_from_command_line()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/init.py”, line 381, in execute_from_command_line
utility.execute()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/init.py”, line 375, in execute
self.fetch_command(subcommand).run_from_argv(self.argv)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/base.py”, line 323, in run_from_argv
self.execute(*args, **cmd_options)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/base.py”, line 364, in execute
output = self.handle(*args, **options)
File “/snap/maas/26274/lib/python3.8/site-packages/maasserver/management/commands/dbupgrade.py”, line 107, in handle
conn.ensure_connection()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 217, in ensure_connection
self.connect()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/utils.py”, line 89, in exit
raise dj_exc_value.with_traceback(traceback) from exc_value
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 217, in ensure_connection
self.connect()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 195, in connect
self.connection = self.get_new_connection(conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/postgresql/base.py”, line 178, in get_new_connection
connection = Database.connect(**conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/psycopg2/init.py”, line 126, in connect
conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
django.db.utils.OperationalError: could not connect to server: Connection refused
Is the server running on host “172.16.XX.YY” and accepting
TCP/IP connections on port 5432?

My workaround was :
Edit pg_hba.conf
host $MAAS_DBNAME $MAAS_DBUSER 172.16.XX.YY/ZZ md5
And postgresql.conf
listen_addresses = '*'

And restarting postgresql service.

Hello,

On the documentation page, when you select: v3.4 Snap, it tells you to sudo snap install --channel=latest/edge maas, which will bring the wrong version (3.5.0~alpha1-14457-g.c9d08507b).

I think that the correct one should be snap install maas --channel=3.4/beta.

Cheers!

THanks @tmartins. It also looks like the latest docs page has the “How to Configure MaaS” section at the bottom completely missing… THe only place I can find docs on this are on the 3.4 announcement page: https://maas.io/docs/what-is-new-with-maas-3-4. Anyone know the right place for the docs for 3.4 beta?

EDIT: After much head scratching, I now believe that THE OP IN THIS THREAD IS THE LATEST DOCUMENTATION FOR 3.4-BETA.

image

This should be “maas $PROFILE” and not “maas admin”.

Hi there, it seems that the maas packages where not published to the ppa for the version 3.4, https://ppa.launchpadcontent.net/maas/3.4/ubuntu/pool/main/

there is no maas package which make it impossible to install it over debian package.

Hi @erickeller

MAAS 3.4 is not released yet. We expect to release it in the next weeks or so.

1 Like
  1. The second line here appears to merely be a typo :slight_smile:

Go to custom anchor

Should be more like

[Install MAAS](link)

  1. In the “Distributed env (Deb)” section a useful step is given:

Add the MAAS 3.3 PPA to your apt repository paths on both region and rack target hosts:

It’s probably better to specify “Add the MAAS PPA for the version of MAAS you want” and anchor that to the install section above. Speaking of which, wouldn’t it be better to break it up into two sections, “Install snap” and “Install deb”, and then have each version be a subsection? But since the instructions are largely aligned independent of version, maybe just make it one section each with snap install --channel=${x.y} maas and sudo apt-add-repository ppa:maas/${x.y}
It would make the top-of-page index more readable, I think.

  1. Wording in “Create an admin” is a bit confusing

Substitute $PROFILE is the administrative MAAS username you wish to create.

Axe substitute and replace $PROFILE with one of $LOGNAME, $USER or $USERNAME.
The numbering scheme also seems to indicate that each of the three points are different steps which must be undertaken to create an admin, but (2) and (3) appear to just be modifications on the command given in (1). Perhaps they should be notes or added to the explanation of $PROFILE?

  1. Nit on user SSH key location:

Copy your entire public key from .ssh/id_rsa.pub

Maybe make it ~/.ssh/id_{scheme}.pub

The init command is not correct. At least not for the .deb install. I haven’t tried the others.

$ sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"
usage: maas [-h] COMMAND ...

options:
  -h, --help      show this help message and exit

drill down:
  COMMAND
    login         Log in to a remote API, and remember its description and credentials.
    logout        Log out of a remote API, purging any stored credentials.
    list          List remote APIs that have been logged-in to.
    refresh       Refresh the API descriptions of all profiles.
    init          Initialize controller.
    apikey        Used to manage a user's API keys. Shows existing keys unless --generate or
                  --delete is passed.
    configauth    Configure external authentication.
    config-tls    Configure MAAS Region TLS.
    config-vault  Configure MAAS Region Vault integration.
    createadmin   Create a MAAS administrator account.
    changepassword
                  Change a MAAS user's password.

https://maas.io/

sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"
usage: maas [-h] COMMAND ...

options:
  -h, --help      show this help message and exit

drill down:
  COMMAND
    login         Log in to a remote API, and remember its description and credentials.
    logout        Log out of a remote API, purging any stored credentials.
    list          List remote APIs that have been logged-in to.
    refresh       Refresh the API descriptions of all profiles.
    init          Initialize controller.
    apikey        Used to manage a user's API keys. Shows existing keys unless --generate or
                  --delete is passed.
    configauth    Configure external authentication.
    config-tls    Configure MAAS Region TLS.
    config-vault  Configure MAAS Region Vault integration.
    createadmin   Create a MAAS administrator account.
    changepassword
                  Change a MAAS user's password.

https://maas.io/

unrecognized arguments: region+rack --database-uri postgres://<redacted>

1 Like