4. 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.

4.1. Verify Network Configuration¶

When you run the script, it first verifies your network setup:

$ 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.

4.2. Configure PostgreSQL account¶

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.

4.3. Configure MAAS administration account¶

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:

4.4. Enable Network Address Translation (NAT)¶

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.

4.5. Set Up Archive Mirroring (Optional)¶

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

4.6. Download Cloud Images (Optional)¶

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.

4.7. Configure Repository URLs¶

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:

4.8. Set Up Certification PPAs¶

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

4.9. Setup Completion¶

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

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

4.9.1. Automatic Configuration Changes¶

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.