Non-snap MAAS installs

Snap is the preferred method of installing MAAS. Fully-confined snap installs begin with version 2.7.0. Nevertheless, you may prefer to install MAAS from packages or from an ISO. This page explains how to install via either method.

Install MAAS from packages

This section covers the obsoleted use of deb/APT packages to install MAAS. With the advent of MAAS 2.7.0, installation via snap is the recommended method to acquire MAAS. You may want to consider an installation within LXD containers. These containers allow MAAS nodes to also run as local containers and are ideal for testing and experimenting with MAAS.


There are three packages to consider when installing MAAS:

  • maas-region-controller - region API server, database, DNS, HTTP proxy, and web UI
  • maas-rack-controller - rack controller and DHCP
  • maas - a metapackage that installs both the above packages to provide a complete MAAS environment

Each of the above packages has its dependencies. That is, each will bring in other MAAS packages not listed above. You can see the full list of MAAS packages with the command:

apt-cache search maas

As an example, running this command might produce output that looks like this:

The ‘maas’ metapackage is the recommended way to install MAAS. See the Introduction for more detail on colocating all services on a single host. Note that high availability with MAAS involves installing multiple region/rack controllers. See MAAS HA for more information on this topic.

Package repositories

While MAAS is available in the normal Ubuntu archives, the available packages may be lagging non-archive, but still stable, versions. For example, you can check the available versions of MAAS by typing:

apt-cache madison maas

which produces output similar to this:

You can install a newer stable version via PPAs listed on the MAAS launchpad, including:

For example, to add the 2.7 PPA, type:

sudo apt-add-repository -yu ppa:maas/2.7

which produces output similar to:

If you check available versions again, you will see that the new repository is now available:

Installation scenarios

The recommended way to set up an initial MAAS environment is to put everything on one machine:

sudo apt install maas

Executing this command leads you to a list of dependent packages to be installed, and a summary prompt that lets you choose whether to continue with the install:

Choosing “Y” proceeds with a standard apt package install.

Distributed environment

For a more distributed environment, you can place the region controller on one machine:

sudo apt install maas-region-controller

and the rack controller (see Rack controller for details) on another:

sudo apt install maas-rack-controller
sudo maas-rack register

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

Creating a MAAS user

Finally, you will need to create a MAAS administrator user to access the web UI:

sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS

For example, the process might go like this:

The username can be anything. You will also be prompted to supply a password for the user. The command option --password=$PASSWORD can be used to specify one but, depending on your environment, this may pose a security risk.

At this time, MAAS does not make use of the email address. However, it may do so in the future.

Finally, the createadmin option asks for an SSH key:


If you have an SSH key associated with your launchpad or github accounts, you can enter the username here to include the key. For launchpad, just enter lp:username, and for github, enter gp:username at the prompt. In both cases, the actual username has to be supplied after the lp: or gh: prefix.

If you don't have a key associated with either of these services, you will have an opportunity to paste your public key into the MAAS SSH key list, after you've started MAAS for the first time as part of the welcome screens.

Once all this is done, you’re ready to access MAAS from the web UI and begin your Configuration journey.

Installing MAAS from an ISO

The Ubuntu Server ISO offers to have the server-to-be-installed provide a complete MAAS environment or a single rack controller. This page is based on Ubuntu 16.04.1 LTS.

server install menu

Choosing option Install MAAS Region Controller will actually install an entire MAAS environment. That is, it is equivalent to installing the ‘maas’ metapackage. The wording of this menu option will change in a future printing of the ISO.

Choosing option Install MAAS Rack Controller will install a rack controller and register it with an existing region controller. Therefore, an existing region controller is a requirement for this option to succeed.

Using the ISO to install a rack controller is typically used to install an extra rack controller since the recommended starting design is to co-locate the rack controller with the region controller.

Each of these two options will add extra dialog boxes to the generic Ubuntu Server install procedure. This page covers these extra dialogues only. See the Ubuntu Server Guide for details on installing Ubuntu Server.

Region controller

After having chosen to install a region controller, three consecutive dialog boxes will appear in order to do the following:

  • Install a MAAS environment
  • Set a username for the MAAS administrator
  • Set a password for the MAAS administrator
Walkthrough of MAAS environment installation

Confirm the installation of a MAAS environment. ![regiond install dialog 1](upload://p4Teim0slXoWe2sA3H91IQ5finP.png)

Provide the name of the initial MAAS administrator. It can be anything but in this example 'admin' was chosen. This account is distinct from the system account that will be created later as part of the generic Ubuntu Server install. ![regiond install dialog 2](upload://wpFwaSW07q6E8I6DzTiV6iCAhZe.png)

Complete the creation of the MAAS administrator account by supplying a password. ![regiond install dialog 3](upload://zDmXxCSap5aPSZTYeF6lnghGmRf.png)

During one step of the generic Server install you will be asked whether a proxy is needed for the server itself. This is separate from the proxy that MAAS provides to its nodes (see Proxy).

Rack controller

After having chosen to install a rack controller, three consecutive dialog boxes will appear in order to do the following:

  • Install a rack controller
  • Input the location (URL) of the region API server
  • Input the shared secret required for rack controller registration

For nodes on an IPv6 subnet, the URL must use a hostname instead of an IP address and it must resolve to both IPv4 and IPv6 addresses, both on the rack controller and on the nodes.

Walkthrough of rack controller installation

Confirm the installation of a rack controller. ![rackd install dialog 1](upload://1Zne8D6COFQtZkdFy6I57pJfUGD.png)

Point the new rack controller at an existing region API server so it can register with it. ![rackd install dialog 2](upload://6vsqHBmfF7fIUD8tA2Kk5wEI2td.png)

Provide the secret required for registering the rack controller. It is found on the region API server. ![rackd install dialog 3](upload://gm2efls5beeIVMBEX40gbxJgBUg.png)

The final dialog will not confirm whether registration was successful. Once Ubuntu Server is fully installed and rebooted you should inspect /var/log/maas/rackd.log for any possible error messages. Alternatively, you may verify that the rack controller shows up in the web UI. You can always register the rack controller manually (after the server has rebooted) if a mistake was made. See MAAS CLI - install a rack controller.

You can choose to display the typed secret (necessary for registering the rack controller) in cleartext. This can help prevent mis-typing and thus avoiding a failed registration.

An SSH server is not installed on the rack controller by default. Near the end of the generic Server install there will be the opportunity to install optional software. You may install an SSH server at this time.

Next steps

Once you have installed your MAAS environment (region + rack controller) and any possible extra rack controllers(s), you are ready to begin your Configuration journey.

1 Like