3. Installing and Configuring MAAS

Installing MAAS on the computer is quite straightforward; you simply use APT. With MAAS installed, you can run the setup-certlab script to configure MAAS for use in an Ubuntu certification environment.

3.1. Installing MAAS

Follow the procedure below to set up MAAS for certification testing. General guidelines for MAAS installation and setup can be found at https://maas.io/docs/tutorial-bootstrapping-maas.

1. Install the MAAS snap:

   $ sudo snap install maas
   

   Beginning with Ubuntu 20.04, MAAS is installed via a snap by default, rather than the Debian packages used in earlier versions of Ubuntu. This document assumes MAAS installation via a snap. Use of an older version of Ubuntu is no longer supported.

2. Several scripts and configuration files are available in the maas-cert-server package in the hardware certification PPA. You can install the scripts and configuration files as follows:

   $ sudo apt-add-repository ppa:checkbox-dev/stable
   $ sudo apt install maas-cert-server
   

3. Verify that MAAS is installed:

   $ snap info maas | grep installed
   

   The output should specify the installed MAAS version, which is 3.4.1 at the time of this writing.

4. Edit the /etc/maas-cert-server/config file to be sure that the variables it contains are correct. Specifically:

   • INTERNAL_NET must point to your internal network device (eth0 in the below examples).

   • EXTERNAL_NET must point to your external network device (eth1 in the below examples).

   • Do not adjust other values without consulting with the Server Certification Team.

   • Note that there must not be spaces surrounding the equal signs (=) in the assignments!

5. Optionally create a /var/snap/maas/current/iperf.conf file to identify your iperf3 server(s). This file should consist of a single line that contains a comma-delimited list of IP addresses, each identifying a different iperf3 server. If this file is absent, SUTs will configure themselves to use their network gateways (normally the MAAS server) as the iperf3 target. If /etc/maas-cert-server/iperf.conf is present, though, MAAS will tell SUTs to use the specified system(s) instead. You might use this feature if your iperf3 server is not the SUTs’ network gateway or if you have multiple iperf3 servers. The SUTs will attempt to use each iperf3 target in series until the network test passes or until the list is exhausted. This setting can be overridden on SUTs by editing the /etc/xdg/canonical-certification.conf file on the SUT. See Appendix B: Network Testing Options for more on advanced network testing configurations.

3.2. Running the Setup Script

This section describes setting up MAAS directly on the MAAS server computer’s hardware. If you prefer to run MAAS within a LXD container for added flexibility, consult Appendix D: Installing MAAS in a LXD Container.

The MAAS configuration script is called setup-certlab, and was installed as part of the maas-cert-server package. Running this script will set up the MAAS server with reasonable defaults for certification work; however, the script will also ask you a few questions along the way:

$ sudo setup-certlab

***************************************************************************
* Identified networks:
*   INTERNAL: 172.24.124.1 on eth0
*   EXTERNAL: 192.168.1.27 on eth1
*
* Is this correct (Y/n)?

Be sure your network assignments are correct at this point! If the script complains about a problem, such as an inability to identify an IP address or a default route being present on your internal network, go back and review both your network settings and the contents of your /etc/maas-cert-server/config file to identify the cause and correct the problem.

If you approve the settings, the script will display additional messages as it begins to configure the MAAS server. Some of these messages are the output of the programs it calls. For the most part this output can be ignored, but if a problem occurs, be sure to report it in detail, including the script’s output.

Note that at all prompts for a “Y/N” response, the default value is capitalized; if you press Enter, that default will be used.

If you’ve installed MAAS via snaps, the next question acquires a password for a PostgresQL database (with the name maas) upon which MAAS relies:

***************************************************************************
* We must set up a PostgresQL account (called 'maas') with a password that
* you supply.
*
* Please enter a password for this account:
* Please re-enter the password for verification:

MAAS records this password and uses it itself, so ideally you won’t need it; but you may need it if you must perform manual database maintenance, so it’s best to remember the password.

The script will now ask for a password for the MAAS administrative account, which will have the same name as your default login name. Note that this account is distinct from the PostgresQL account created earlier.

***************************************************************************
* A MAAS administrative account with a name of ubuntu is being
* created.
*
* Please enter a password for this account:
* Please re-enter the password for verification:

In most cases, you should enable NAT on your MAAS server; however, if official policy at the site where the server will be used forbids the use of NAT, you may opt to leave it disabled:

***************************************************************************
* NAT enables this computer to connect the nodes it controls to the Internet
* for direct downloads of package updates and to submit certification results
* to C3.
*
* You can configure this computer to automatically start NAT. The following
* commands can start or stop NAT:
*  sudo systemctl enable certification-nat -- Start NAT on the next reboot
*  sudo systemctl disable certification-nat -- Stop NAT on the next reboot
*  sudo service certification-nat start -- Start NAT until the next reboot
*  sudo service certification-nat stop -- Stop NAT until the next reboot
*
* Do you want to set up this computer to automatically enable NAT (Y/n)?

The service certification-nat start and service certification-nat stop commands run the startnat.sh and flushnat.sh scripts, respectively. Both of these scripts come with the maas-cert-server package. The systemctl commands set up or remove symbolic links in the systemd configuration directories to enable (or not) NAT when the computer boots. You can check whether NAT is running by typing sudo iptables -L, which should show a pair of ACCEPT rules in the FORWARD chain if NAT is enabled and no such rules if it’s not running; and by typing cat /proc/sys/net/ipv4/ip_forward, which should return 1 if NAT is enabled and 0 if it’s not enabled.

If your work site has poor Internet connectivity or forbids outgoing connections, you must create a local mirror of the Ubuntu archives on your MAAS server. These archives will be stored in the /srv/mirrors/ directory, but creating them takes a long time because of the amount of data to be downloaded – about 200 GiB per release. For comparison, HD video consumes 1-8 GiB per hour – usually on the low end of that range for video streaming services. As should be clear, the result will be significant network demand that will degrade a low-end connection for hours, and possibly exceed your monthly bandwidth allocation. The download will occur in the background, though, so you can continue with MAAS setup as the download proceeds. If you want to defer creating a mirror, you should respond N to the following prompt, then re-launch setup-certlab with the \-\-mirror-archives (or -m) option later. In any event, you make your selection at the following prompt:

***************************************************************************
* Mirroring an archive site is necessary if you'll be doing testing while
* disconnected from the Internet, and is desirable if your test site has
* poor Internet connectivity. Performing the mirroring operation takes
* time and disk space, though -- about 150 GiB per release mirrored.
* To defer this task, respond 'N' to the following question.
*
* Do you want to mirror an archive site for local use (y/N)? Y

If you opt to mirror the archive, the script will ask you to verify the upstream mirror site:

* Identified upstream archive is:
*  http://us.archive.ubuntu.com/ubuntu/
*
* Is this correct (Y/n)? y

If you respond n to this question, the script asks you to specify another archive site. The script then asks you which Ubuntu releases to mirror:

* Do you want to mirror bionic (Y/n)? n
* Do you want to mirror focal (Y/n)? y
* Do you want to mirror jammy (Y/n)? y
* Do you want to mirror kinetic (Y/n)? n

The list of releases changes as new versions become available and as old ones drop out of supported status. When the mirror process is done, you’ll be asked if you want to configure the computer to automatically update its mirror every day, by modifying the /etc/cron.d/apt-mirror file. If you do not opt for automatic daily updates, you can update your mirror at any time by typing sudo apt-mirror.

* Set up cron to keep your mirror up-to-date (Y/n)? y
* Cron should update your mirror every morning at 4 AM.
* You can adjust /etc/cron.d/apt-mirror manually, if you like.

Note that setup-certlab configures the system to mirror AMD64, i386, and source repositories because all three are required by the default MAAS configuration. If you want to tweak the mirror configuration, you can do so by editing the /etc/apt/mirror.list file – but do so after finishing with the setup-certlab script, and then type sudo apt-mirror to pull in any new directories you’ve specified. You can also configure the computer to use its own local mirror, if you like:

* Adjust this computer to use the local mirror (Y/n)? y

The script then gives you the option to retrieve images used for virtualization testing. If your site has good Internet connectivity, you may not need these images; but it’s not a bad idea to have them on hand just in case. Although downloading the cloud images isn’t nearly as time-consuming as mirroring the archives, it can take long enough that you may want to defer this action. You can download the cloud images later by launching setup-certlab with the \-\-download-virtualization-image (or -d) option.

***************************************************************************
* An Ubuntu cloud image is required for virtualization tests. Having such
* an image on your MAAS server can be convenient, but downloading it can
* take a while (each image is about 250MiB). This process will import cloud
* images for whatever releases and architectures you specify. If you select
* 'Y', logs will be stored at /home/ubuntu/.maas-cert-server/cloudimg-*-dl-*.log;
* monitor them if you suspect download problems.
*
* To defer this task, respond 'N' to the following question.
*
* Do you want to set up a local cloud image mirror for the virtualization
* tests (Y/n)?

If you respond Y to this question, the script proceeds to ask you what Ubuntu versions and architectures to download:

* Cloud Mirror does not exist. Creating.
* Do you want to get images for bionic release (y/N)? n
* Do you want to get images for focal release (Y/n)? y
* Do you want to get images for jammy release (y/N)? y
* Do you want to get images for kinetic release (y/N)? n
*
* Do you want to get images for amd64 architecture (Y/n)? y
* Do you want to get images for i386 architecture (y/N)? n
* Do you want to get images for arm64 architecture (y/N)? n
* Do you want to get images for armhf architecture (y/N)? n
* Do you want to get images for ppc64el architecture (y/N)? n
* Do you want to get images for s390x architecture (y/N)? n
* Downloading cloud images.  This may take some time.
*
* Downloading image for focal on amd64 in the background....

These downloads proceed in the background, with logs stored in ~/.maas-cert-server, so you can check there if you suspect problems. To monitor the downloads, use top or ps to look for instances of wget.

You can customize the site that MAAS tells nodes to use for their repositories. If you mirrored a repository, the script points nodes to itself (via its internal IP address); but if you did not mirror a repository, the script should point your nodes to the same site used by the MAAS server itself. In either case, you can press the Enter key to accept the default or enter a new value:

***************************************************************************
* MAAS tells nodes to look to an Ubuntu repository on the Internet. You
* can customize that site by entering it here, or leave this field blank
* to use the default value of http://172.24.124.1/ubuntu.
*
* Type your repository's URL, or press the Enter key:

The script configures personal package archives (PPAs), in which the latest certification software is stored. You’ll want to configure PPAs for whatever architectures you intend to test:

***************************************************************************
* Now we will set up the PPAs necessary for installing the certification
* tools when deploying the SUT.
*
* Do you want to set PPAs for amd64 architecture (Y/n)? Y
* Do you want to set PPAs for i386 architecture (y/N)? n
* Do you want to set PPAs for arm64 architecture (y/N)? n
* Do you want to set PPAs for armhf architecture (y/N)? n
* Do you want to set PPAs for ppc64el architecture (y/N)? n
*
* Adding PPAs for the following architectures: amd64
*
* Hardware Certification Stable PPA
* Firmware Test Suite Stable PPA
* Hardware Certification Development PPA (Disabled by default)
*
* PPA Setup Complete

Finally, the script announces it’s finished its work:

***************************************************************************
* The setup-certlab script has finished!

In addition to setting the options for which it prompts, setup-certlab adjusts some other details of which you should be aware:

• SSH keys are generated for your user account and added to the MAAS server. These keys enable you to log in to nodes that MAAS deploys from your regular account on the MAAS server.

• Any keys in your ~/.ssh/authorized_keys file on the MAAS server computer are also added to the MAAS setup. Again, this simplifies login.

• The MAAS computer’s SSH client configuration is relaxed so that changed host keys do not block outgoing connections. This change is insecure, but is a practical necessity because your internal network’s nodes will be redeployed regularly. You should keep this setting in mind and minimize your use of this computer to SSH to external sites.

• MAAS is configured to tell nodes to install the Canonical Certification Suite whenever they’re deployed. This detail increases deployment time compared to a generic MAAS installation.

• The default storage layout setting is changed from “LVM” to “flat.” Some certification tests assume a flat layout.

3.3. Setting up MAAS

At this point, MAAS should be installed and configured; however, it’s worth verifying the most important options in the MAAS web UI. You may also want to modify a few settings. To do so, follow these steps:

1. Verify you can access the MAAS web UI:

   • Launch a browser and point it to http://172.24.124.1:5240/MAAS (changing the IP address as necessary).

   • You should be able to access the server on either its internal or external network address, although at this point, the only computer on the internal network may be the MAAS computer itself.

   • If you provide the computer with a hostname in DNS or /etc/hosts, you should be able to access it via that name, as well.

   • You should see a login prompt.

2. Log in to the web UI using your regular username and the password you gave to the setup script.

3. Once you log in, MAAS presents a screen in which you can set a few options, as shown below. Review these settings, changing any as necessary, and click Save and Continue at the bottom of the page. (If in doubt, leave the settings as-is; you can change them later, if necessary.)

   

4. MAAS now shows a list of OS images, as shown below. This page will probably show Ubuntu 22.04 for AMD64 already synced or importing. You probably don’t need to do anything with this page right now, and you can come back to it later; however, if you know you must test with an unusual architecture or something other than 22.04, you may want to import additional images immediately:

   1. Select additional Ubuntu releases using the radio buttons, and for each release, pick the architectures you want to import.

   2. Click Update Selection. The image download process will begin immediately.

   3. When you’re done making changes, scroll down and click Continue.

   

5. You now see an information page with the message “MAAS has been successfully set up.”. Click Finish Setup button to complete the setup.

6. You can now import additional SSH keys from GitHub or Launchpad, or upload them individually. Once you’ve imported all the keys you need, scroll down and select Finish Setup.

3.4. Checking the MAAS Configuration

After the initial setup, MAAS shows a page summarizing computers it has discovered on the network. You can review this information, but you shouldn’t need to do anything on this page.

To review and adjust common MAAS configuration settings:

1. In the left panel, click Settings -> Network -> DNS to review your DNS settings here. The default for Enable DNSSEC Validation of Upstream Zones is Automatic, which must sometimes be adjusted. Some private DNS servers are misconfigured and will cause problems. Changing this setting to No may be required in such cases. (Alternatively, configuring the upstream DNS server to support DNSSEC should fix the problem.) If you change this option, be sure to click Save.

   

2. Select Settings -> Network -> Network Discovery. In theory, this feature should passively detect devices and should cause no problems. In practice, it sometimes triggers security alerts on the external network. If you run into this problem, change this setting and click Save.

3. You can review other settings in the MAAS Settings page. This page is broken into several subsections, navigated via the list on the left of the page – Configuration, Security, Users, Images, and so on. If you change any settings, be sure to click the associated “Save” button within that section.

4. To review the DHCP options, click Network -> Subnets in the left panel:

   1. Click the subnet range for the internal network (172.24.124.0/22 in this example) to check the details of the subnet:

      

      Your network, of course, may be different from this example, particularly if you have unused network devices, which will show up as additional “fabrics.”

   2. On the page for your internal network, scroll down about halfway to view the Utilisation and Reserved Ranges sections. At this point, about half the addresses will be classified as “used” because setup-certlab set them aside as reserved or as managed by DHCP. The “available” addresses are those that do not belong to either of these categories; MAAS assigns them to nodes that are deployed using its standard settings. (See Appendix C: MAAS Network Ranges for details of how MAAS manages its network addresses.)

      

   3. If the various ranges (reserved, dynamic, or the implicit available addresses) are not appropriate, you can edit them as follows:

      • Click the edit icon near the right side of the page in the row for the range you want to delete or modify. You can then change the start and end addresses, and then click Save to save your changes.

      • If you want to completely delete the range, click the trash can icon instead of the edit icon. To function properly, MAAS must have at least a small reserved range (for the MAAS server itself, at a minimum) and a dynamic range (to support enlisting, commissioning, and deploying nodes).

   4. You can optionally reserve additional ranges by using the Reserve Range button, which provides two sub-options: for machines not managed by MAAS (using the Reserve Range sub-option) or for DHCP addresses (using the Reserve Dynamic Range sub-option).