How to do a fresh install of MAAS

Docs
#1

MAAS is relatively easy to install and configure. Let’s give it a try.

Note that support for PostgreSQL version 12 is deprecated for MAAS version 3.4, and will be discontinued in MAAS 3.5. We recommend upgrading to PostgreSQL version 14 before installing MAAS 3.4.

To install MAAS 3.4 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Enter the following command:

sudo snap install --channel=latest/edge maas
  1. Enter your account password.

At this point, the snap will download and install from the 3.4 channel.

Note that support for PostgreSQL version 12 is deprecated for MAAS version 3.4, and will be discontinued in MAAS 3.5. We recommend upgrading to PostgreSQL version 14 before installing MAAS 3.4.

To install MAAS 3.4 from packages:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Add the MAAS 3.4 PPA to your apt repository paths:

sudo apt-add-repository ppa:maas/3.4-next
  1. Update your apt repository lists:
sudo apt update
  1. Install MAAS with the following command:
sudo apt-get -y install maas
  1. Choose “Y” if asked about whether to continue with the install.

Note that support for PostgreSQL version 12 is deprecated for MAAS version 3.3, and will be discontinued in MAAS 3.5. We recommend upgrading to PostgreSQL version 14 before installing MAAS 3.3.

To install MAAS 3.3 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Enter the following command:

sudo snap install --channel=3.3 maas
  1. Enter your account password.

At this point, the snap will download and install from the 3.3 channel.

Note that support for PostgreSQL version 12 is deprecated for MAAS version 3.3, and will be discontinued in MAAS 3.5. We recommend upgrading to PostgreSQL version 14 before installing MAAS 3.3.

To install MAAS 3.3 from packages:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Add the MAAS 3.3 PPA to your apt repository paths:

sudo apt-add-repository ppa:maas/3.3
  1. Update your apt repository lists:
sudo apt update
  1. Install MAAS with the following command:
sudo apt-get -y install maas
  1. Choose “Y” if asked about whether to continue with the install.

To install MAAS 3.2 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Enter the following command:

sudo snap install --channel=3.2 maas
  1. Enter your account password.

At this point, the snap will download and install from the 3.2 channel.

To install MAAS 3.2 from packages:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Add the MAAS 3.2 PPA to your apt repository paths:

sudo apt-add-repository ppa:maas/3.2
  1. Update your apt repository lists:
sudo apt update
  1. Install MAAS with the following command:
sudo apt-get -y install maas
  1. Choose “Y” if asked about whether to continue with the install.

To install MAAS 3.1 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Install the 3.2 snap:

sudo snap install --channel=3.1 maas
  1. Enter your account password.

The snap will download and install from the 3.1 channel.

To install MAAS 3.1 from packages:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Add the MAAS 3.1 PPA to your apt repository paths:

sudo apt-add-repository ppa:maas/3.1
  1. Update your apt repository lists:
sudo apt update
  1. Install MAAS with the following command:
sudo apt-get -y install maas
  1. Choose “Y” if asked about whether to continue with the install.

To install MAAS 3.0 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Enter the following command:

sudo snap install --channel=3.0 maas
  1. Enter your user password.

The snap will download and install from the 3.0 channel.

To install MAAS 3.0 from packages:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Add the MAAS 3.0 PPA to your apt repository paths:

sudo apt-add-repository ppa:maas/3.0
  1. Update your apt repository lists:
sudo apt update
  1. Install MAAS with the following command:
sudo apt-get -y install maas
  1. Choose “Y” if asked about whether to continue with the install.

To install MAAS 2.9 from a snap:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Enter the following command:

sudo snap install --channel=2.9 maas
  1. Enter your user password.

The snap will download and install from the 2.9 stable channel.

To install MAAS 2.9 from packages:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

  2. Add the MAAS 2.9 PPA to your apt repository paths:

sudo apt-add-repository ppa:maas/2.9
  1. Update your apt repository lists:
sudo apt update
  1. Install MAAS with the following command:
sudo apt-get -y install maas
  1. Choose “Y” if asked about whether to continue with the install.

Some installation notes

When installing MAAS on Ubuntu, there can be conflicts between the existing NTP client, systemd-timesyncd, and the NTP client/server provided by MAAS, chrony. This can lead to time synchronization issues, especially if MAAS is configured with different upstream NTP servers than the ones used by systemd-timesyncd. To avoid conflicts, users can manually disable and stop systemd-timesyncd using the following command:

sudo systemctl disable --now systemd-timesyncd

Also note that support for PostgreSQL 12 has been deprecated in MAAS 3.3 and will be discontinued in MAAS 3.5.

How to initialise MAAS for a test or POC

To initialise the MAAS snap in a test/POC configuration, simply use the --help flag with maas init and follow the instructions.

How to initialise MAAS for production

To install MAAS in a production configuration:

  1. Install PostgreSQL on any machine where you want to keep the database with the following commands:
sudo apt update -y
sudo apt install -y postgresql
  1. Create desired values for the following variables (replace them in the commands below):
$MAAS_DBUSER = ___________
$MAAS_DBPASS = ___________
$MAAS_DBNAME = ___________
$HOSTNAME = _________

Note that for most situations, you can use localhost for $HOSTNAME.

  1. Create a suitable PostgreSQL user:
sudo -i -u postgres psql -c "CREATE USER \"$MAAS_DBUSER\" WITH ENCRYPTED PASSWORD '$MAAS_DBPASS'"
  1. Create the MAAS database:
sudo -i -u postgres createdb -O "$MAAS_DBUSER" "$MAAS_DBNAME"
  1. Edit /etc/postgresql/14/main/pg_hba.conf and add a line for the newly created database:
host    $MAAS_DBNAME    $MAAS_DBUSER    0/0     md5
  1. Initialise MAAS via the following command:
sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"

How to create a distributed environment

To run MAAS region and rack controllers on separate machines:

  1. Check the MAAS installation requirements to make sure that your hardware will support MAAS.

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

sudo apt-add-repository ppa:maas/3.3
  1. Update your apt repository lists on both region and rack hosts:
sudo apt update
  1. Install the MAAS region controller on the target region host:
sudo apt install maas-region-controller
  1. Install the MAAS rack controller on the target rack host:
sudo apt install maas-rack-controller
  1. Register the rack controller with the region controller by running the following command on the rack host:
sudo maas-rack register

These two steps will lead you through two similar apt install sequences.

How to create a MAAS admin user

To create a MAAS administrative user:

  1. Create a MAAS administrator user to access the web UI:
sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS

Subtitute $PROFILE is the administrative MAAS username you wish to create. $EMAIL_ADDRESS is an email address you may type in at random (currently, MAAS does not use this email address). The createadmin option will cause MAAS to ask for an SSH key.

  1. To use an SSH key associated with your launchpad accounts, enter lp:$USERNAME (substitute your LP username for $USERNAME).

  2. Alternatively, to use an SSH key associated with your github account, enter gh:$USERNAME (substitute your github username for $USERNAME)

How to check the status of MAAS services

To check the status of running services, enter:

sudo maas status

Typical output looks like this:

bind9                            RUNNING   pid 7999, uptime 0:09:17
dhcpd                            STOPPED   Not started
dhcpd6                           STOPPED   Not started
ntp                              RUNNING   pid 8598, uptime 0:05:42
postgresql                       RUNNING   pid 8001, uptime 0:09:17
proxy                            STOPPED   Not started
rackd                            RUNNING   pid 8000, uptime 0:09:17
regiond:regiond-0                RUNNING   pid 8003, uptime 0:09:17
regiond:regiond-1                RUNNING   pid 8008, uptime 0:09:17
regiond:regiond-2                RUNNING   pid 8005, uptime 0:09:17
regiond:regiond-3                RUNNING   pid 8015, uptime 0:09:17
tgt                              RUNNING   pid 8040, uptime 0:09:15

Your mileage may vary.

How to re-initialise MAAS

To switch a machine from from rack to region:

sudo maas init region

How to list additional MAAS initialisation options

The init command can takes optional arguments. To list them, as well as read a brief description of each, you can enter:

sudo maas init --help

How to configure MAAS

To configure MAAS for first-time use:

  1. Access MAAS at this address, where $API_HOST is the hostname or IP address of the region API server, which was set during installation:
http://${API_HOST}:5240/MAAS

  1. Log in at the prompts, with the login information you created when initialising MAAS.

  2. On the first welcome screen, set the DNS forwarder to a suitable value, e.g., 8.8.8.8. This could be your own internal DNS server, if you have one.

  3. Select an Ubuntu image to import; you may be required to select at least one LTS version.

  4. Click Continue; a screen labelled, “SSH keys for admin:” appears.

  5. In the Source drop-down, select “Launchpad,” “Github,” or “Upload.”

  6. If you want to upload your SSH public key from Launchpad, you would enter the following, where <username> is your Launchpad username:

lp:<username>
  1. If you want to upload your github public SSH key, you would enter the following, where <username> is your GitHub username:
gh:<username>

  1. If you want to use your existing public key from your home directory, select Upload.

  2. Copy your entire public key from .ssh/id_rsa.pub (or wherever you may have stored the key).

  3. Paste the public key into the block labelled “Public key.”

  4. Press the “Import” button to import this key.

  5. You should see a message that MAAS has been successfully set up. Click Go to the Dashboard to proceed.

  6. Select Subnets from the top menu.

  7. Choose the VLAN on which you want to enable DHCP.

  8. Select Enable DHCP.

You should now be able to add, commission, and deploy machines.

Once you’ve successfully installed MAAS (regardless of method), you can login to the MAAS CLI via the following process:

  1. Generate the API-key for the login you’re going to use, replacing $PROFILE with whatever username you set during the createadmin part of the install process.
sudo maas apikey --username=$PROFILE > api-key-file
  1. Login with the following command, substituting $MAAS_URL with the URL that was returned to you when you initialised MAAS, for example, 192.168.43.251:5240/MAAS. :
maas login $PROFILE $MAAS_URL < api-key-file
  1. Set upstream DNS (8.8.8.8 is always a reliable value):
maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8"
  1. Add a public SSH key to a MAAS user account:
maas $PROFILE sshkeys create "key=$SSH_KEY"
  1. See what images you may have already downloaded:
maas $PROFILE boot-resources read | jq -r '.[] | "\(.name)\t\(.architecture)"'
  1. Selecting it for download (e.g., “trusty” in this example):
maas $PROFILE boot-source-selections create 1 os="ubuntu" release="trusty" arches="amd64" subarches="*"  labels="*"
  1. Import your selected images:
maas admin boot-resources import
  1. Identify a valid fabric ID for DHCP (returns "fabric_id": $FABRIC_ID,):
maas $PROFILE subnet read $SUBNET_CIDR | grep fabric_id
  1. Find the name of the primary rack controller:
maas $PROFILE rack-controllers read | grep hostname | cut -d '"' -f 4
  1. reate an IP range for DHCP (in this case, a dynamic range):
maas $PROFILE ipranges create type=dynamic start_ip=$START_IP end_ip=$END_IP
  1. Use this collected information to turn on DHCP:
maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True primary_rack=$RACK_CONTR_HOSTNAME

You should now be able to add, commission, and deploy machines.

MAAS documentation
How to enable high availability (snap/3.0/UI)
How to get started with MAAS
What is new with MAAS 2.9
How-to guides
How to enable high availability (deb/3.1/UI)
How to enable high availability (snap/3.1/CLI)
How to enable high availability (deb/3.0/UI)
How to enable high availability (deb/3.0/CLI)
How to enable high availability (snap/3.0/CLI)
How to enable high availability (deb/2.9/UI)
How to enable high availability (deb/2.9/CLI)
How to enable high availability (snap/2.9/UI)
How to enable high availability (snap/2.9/CLI)
How to enable high availability
How to enable high availability (deb/3.1/CLI)
What is new with MAAS
Installation requirements
MAAS Documentation
Controller high availability
What is new with MAAS 3.3
#2

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

1 Like
#3

thanks for reading so closely. kudos for catching this.

#4

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

#5

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

#6

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

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

1 Like
#8

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

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

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.

#11

heh. there’s a doc for that!

1 Like
#12

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?

#14

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.

#15

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!

#16

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.

#17

image

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