You can't use MAAS unless you install it
Errors or typos? Topics missing? Hard to read? Let us know!
This page explains how to install MAAS from scratch. If you're already running MAAS, it's probably easier to upgrade.
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:
Check the MAAS installation requirements to make sure that your hardware will support MAAS.
Add the MAAS 3.4 PPA to your apt repository paths:
nohighlight
sudo apt-add-repository ppa:maas/3.4
Update your apt repository lists:
nohighlight
sudo apt update
Install MAAS with the following command:
nohighlight
sudo apt-get -y install maas
Choose "Y" if asked about whether to continue with the install.
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.
Create a distributed environment
To run MAAS region and rack controllers on separate machines:
Check the MAAS installation requirements to make sure that your hardware will support MAAS.
Add the MAAS 3.3 PPA to your apt repository paths on both region and rack target hosts:
nohighlight
sudo apt-add-repository ppa:maas/3.3
Update your apt repository lists on both region and rack hosts:
nohighlight
sudo apt update
Install the MAAS region controller on the target region host:
nohighlight
sudo apt install maas-region-controller
Install the MAAS rack controller on the target rack host:
nohighlight
sudo apt install maas-rack-controller
Register the rack controller with the region controller by running the following command on the rack host:
nohighlight
sudo maas-rack register
These two steps will lead you through two similar apt install sequences.
To create a MAAS administrative user:
Create a MAAS administrator user to access the web UI:
nohighlight
sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS
Substitute $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.
To use an SSH key associated with your launchpad accounts, enter lp:$USERNAME (substitute your LP username for $USERNAME).
Alternatively, to use an SSH key associated with your github account, enter gh:$USERNAME (substitute your github username for $USERNAME)
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.
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
Once you've successfully installed MAAS (regardless of method), you can login to the MAAS CLI via the following process:
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
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
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"
Add a public SSH key to a MAAS user account:
maas $PROFILE sshkeys create "key=$SSH_KEY"
See what images you may have already downloaded:
maas $PROFILE boot-resources read | jq -r '.[] | "\(.name)\t\(.architecture)"'
Select an image(s) for download (e.g., "trusty" in this example):
maas $PROFILE boot-source-selections create 1 os="ubuntu" release="trusty" arches="amd64" subarches="*" labels="*"
Import your selected image(s):
maas admin boot-resources import
Identify a valid fabric ID for DHCP (returns "fabric_id": $FABRIC_ID,):
maas $PROFILE subnet read $SUBNET_CIDR | grep fabric_id
Find the name of the primary rack controller:
maas $PROFILE rack-controllers read | grep hostname | cut -d '"' -f 4
Create 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
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.