3. Setting up the SUT for Testing

Before you can begin testing, you must install Ubuntu on the SUT and perform some certification-specific configuration tasks on the SUT. Most of the work of these tasks is performed with the help of MAAS, as described in the following sections.

3.1. Installing Ubuntu on the System

Server certification requires that the SUT be installable via MAAS. Therefore, the following procedure assumes the presence of a properly-configured MAAS server. Certification Environment Setup Guide describes how to set up a MAAS server for certification testing purposes. This document describes use of MAAS 3.1.

Once the SUT and MAAS server are both connected to the network, you can install Ubuntu on the SUT as follows:

  1. Power on the SUT and allow it to PXE-boot.

    • The SUT should boot the MAAS enlistment image and then power off.

    • You should see the SUT appear as a newly-enlisted computer in your MAAS server’s node list. (You may need to refresh your browser to see the new entry.)

    • MAAS 2.6 and later may attempt to commission the node immediately after enlisting it, thus skipping the next two steps. If this does not happen or if you want to change the node’s name, you can perform the next two steps manually after the commissioning attempt.

  2. Check and verify the following items in the MAAS server’s node details page:

    • If desired, change the node name for the SUT.

    • Check the SUT’s power type and ensure it’s set correctly (IPMI, AMT, etc.). If the SUT has no BMC, you can set it to Manual.

    • Note that manual power control is acceptable only on low-end servers that lack BMCs. If MAAS fails to detect a BMC that is present or if MAAS cannot control a BMC that is present, please consult the Canonical Server Certification Team.

  3. Commission the node by clicking Take Action followed by Commission and then Start Commissioning for Machine.

    • On some systems, it is necessary to remove the smartctl-validate option under Testing Scripts before clicking Commission Machine.

    • If the SUT has a BMC, the computer should power up, pass more information about itself to the MAAS server, and then power down again.

    • If the SUT does not have a BMC, you should manually power on the SUT after clicking the Start Commissioning for Machine button. The SUT should power up, pass more information about itself to the MAAS server, and then power down again.

    • Some servers provide an option called “minimum password change interval,” or something similar, in their BMCs’ web-based interfaces, that prevents BMC passwords from being changed very frequently. MAAS will attempt to change the password upon commissioning, though, and if this is done immediately after enlisting the node, it will fail. If the BMC configuration commissioning step fails, you may need to set this minimum password change interval to 0 or otherwise disable this feature, then try commissioning again. Alternatively, checking the “Skip configuring supported BMC controllers with a MAAS generated username and password” option when commissioning the node may work around this problem.

  4. Check and, if necessary, adjust the following node details:

    • On the Network tab, ensure that all the node’s interfaces are active. (By default, MAAS activates only the first network interface on most computers.) If an interface is identified as Unconfigured, click the down arrow in the Actions column, select Edit Physical, and set IP Mode to Auto Assign, DHCP, or Static Assign. (The first two cause MAAS to assign an IP address to the node itself, either by maintaining its own list of static IP addresses or by using DHCP. The Static Assign option requires you to set the IP address yourself. These three options are described in more detail in Certification Environment Setup Guide.) When you’ve made this change, click Save Interface.

    • On the Storage tab, look under Available Disks and Partitions for disks that have not been configured. If any are available, click the down arrow in the Actions column and select Add Partition. You can then set a Filesystem (specify ext4) and Mount Point (something under /mnt works well, such as /mnt/sdb for the /dev/sdb disk). Click Add Partition when you’ve set these options. Repeat this step for any additional disks.

      • If MAAS complains that there’s insufficient free space on the device, try manually reducing the partition’s size by a small amount. Usually rounding down to the nearest whole number works around this problem.

  5. On the MAAS server, verify that the SUT’s Status is listed as Ready in the node list or on the node’s details page. You may need to refresh the page to see the status update.

  6. Click Take Action followed by Deploy. Options to select the OS version to deploy should appear.

  7. Select the Ubuntu release you want to deploy:

    • Choose the Ubuntu version you wish to deploy from the list of available Ubuntu releases. The options will appear similar to 24.04 LTS “Noble Numbat” in the middle drop-down box.

    • Choose the kernel you wish to deploy. The available kernels are in the dropdown box below the Ubuntu version. For recent versions of Ubuntu, they will be named similar to noble (ga-24.04).

      • When deploying the SUT for testing, you should always start out with the original GA kernel. For 24.04 LTS, the noble (ga-24.04) option is appropriate. If the system is not deployable or fails certification using the GA kernel, you will then need to re-deploy the SUT choosing the correct HWE kernel option (if available). Note that an HWE kernel option becomes available only starting with the second point release for an LTS version, such as 20.04.2 or 22.04.2.

      • Do not choose any of the edge or lowlatency kernel options for official Certification testing.

    Appendix C - Testing Point Releases, elaborates on the procedures for testing different kernels and point releases.

  8. Click Deploy Machine to begin deployment.

    • If the SUT has a BMC, it should power up and install Ubuntu. This process can take several minutes.

    • If the SUT does not have a BMC, you should power it on manually after clicking Deploy Machine. The SUT should then boot and install Ubuntu. This process can take several minutes.

If MAAS has problems in any of the preceding steps, you should first check Appendix E - Troubleshooting for suggestions. If that doesn’t help, the SUT might not pass certification. For instance, certification requires that MAAS be able to detect the SUT and, in most cases, set its power type information automatically. If you have problems with any of these steps, contact the Canonical Server Certification Team to learn how to proceed; you might have run into a simple misconfiguration, or the server might need enablement work.

If MAAS is fully configured as described in the Certification Environment Setup Guide document, it should deploy the Server Test Suite automatically. If MAAS doesn’t deploy the Server Test Suite properly, you can do so manually, as described in Appendix A - Installing the Server Test Suite Manually.

3.2. Configuring DCPMM Devices for Testing

Starting with Cascade Lake, Intel servers have included support for Intel Optane DCPMM devices. These are RAM devices that use the standard DIMM form factor and are populated alongside standard DIMMs. These special devices can function in one of three different modes, described below.

  • Memory Mode is a configuration where the DCPMMs are dedicated completely to the traditional volatile RAM role, like any other standard memory DIMM. In this mode, the certification suite will exercise the DCPMMs using the Memory test cases.

  • AppDirect Mode is a configuration where the DCPMMs are presented to the installed OS as persistent storage devices. AppDirect allows for four different storage modes, three of which are currently tested using the Disk test cases:

    • fsdax – Filesystem-DAX mode is the default mode of a namespace when specifying ndctl create-namespace with no options. It creates a block device (/dev/pmemX[.Y]) that supports the DAX capabilities of Linux filesystems (XFS and ext4 to date). DAX enables workloads or working-sets that would exceed the capacity of the page cache to scale up to the capacity of persistent memory. When in doubt, pick this mode.

    • sector – Use this mode to host legacy filesystems that do not checksum metadata or applications that are not prepared for torn sectors after a crash. Expected usage for this mode is for small boot volumes. This mode is compatible with other operating systems.

    • raw – Raw mode is effectively just a memory disk that does not support DAX. Typically this indicates a namespace that was created by tooling or another operating system that did not know how to create a Linux fsdax or devdax mode namespace. This mode is compatible with other operating systems, but again, does not support DAX operation.

    • devdax – Device-DAX mode enables similar mmap(2) DAX mapping capabilities as Filesystem-DAX. However, instead of a block device that can support a DAX-enabled filesystem, this mode emits a single character device file (/dev/daxX.Y). Use this mode to assign persistent memory to a virtual machine, register persistent memory for RDMA, or when gigantic mappings are needed. As of this writing, devdax is not yet supported by tests in Checkbox

  • Mixed Mode enables configuring a mix of both Memory and AppDirect spaces using either the system configuration tools (e.g. Setup/BIOS) or userspace tools after installation, which requires a reboot afterwards. If using userspace tools, you will need to use ipmctl for the initial configuration. ipmctl is available via the Universe repo in 20.04 LTS and later. Using ipmctl you should allocate at least 25% of the DCPMM space to Memory Mode and the remainder as AppDirect Mode.

This guide provides one path to configuration using Mixed Mode to reduce the amount of retests necessary to complete certification. Some OEMs may support operation of DCPMMs in Memory or AppDirect only. If that applies to your SUT, you will need to configure each mode separately and run retests to ensure both modes have been tested.

Once initial configuration is done using ipmctl, you will need to use ndctl, which is available from 18.04 LTS onward in the Universe repo, to do the final configuration.

For this step, you should create a fsdax device, a sector device, and a raw device of more or less equal size.

Once you have configured this, you will need to reboot the SUT to ensure the configuration is performed. Once you have rebooted the server, you will need to add a partition table and a partition to each AppDirect device, and format them appropriately using a supported filesystem (such as ext4).

From this point onward, the Server Test Suite will treat the AppDirect devices as any other block device and test them accordingly using the various Disk test cases.

3.3. Performing Final Pre-Testing SUT Configuration

Once the SUT is deployed, you should be able to log into it using SSH from the MAAS server. Check the node details page to learn its primary IP address. (Using a hostname will also work if DNS is properly configured, but this can be fragile.) The username on the node is ubuntu, and no password should be required when logging in from the MAAS server or from any other computer and account whose SSH key you’ve registered with the MAAS server.

You may need to perform a few additional minor tasks before running the Certification Suite, and keep some other factors in mind as you continue to access the SUT:

  • If you want to log in at the console or from another computer, the password is ubuntu, assuming the certification preseed files are used on the MAAS server. If you’re using a “generic” MAAS installation, you must set the password manually. Testing at the console has certain advantages (described shortly).

  • You should not install updates to the SUT unless they are absolutely necessary to pass certification. In that case, the Canonical Certification Team will make the determination of what updates should be applied.

  • You should verify your SUT’s kernel version by typing uname -r. Ubuntu 20.04 GA ships with a 5.4.0-series kernel and Ubuntu 22.04 ships with a 5.15-series kernel. Note that, although updated kernels ship with most point-release versions, if you use the standard MAAS images, lsb_release -a will show that you have the latest point-release version even if you’re using the GA kernel. It’s the kernel version that’s important for testing purposes, as elaborated on in Appendix C - Testing Point Releases.

  • If any network interfaces are not configured, you should configure them:

    • The best way is to release the node in MAAS, adjust the network configuration as described in Installing Ubuntu on the System, and re-deploy the node. If the interfaces don’t show up in MAAS, then you should re-commission the node.

    • If MAAS doesn’t detect an interface, or if it requires configuration MAAS can’t handle, you can reconfigure the network in the deployed installation: Edit /etc/netplan/50-cloud-init.yaml and activate the changes with sudo netplan apply. (NetPlan configuration is described in more detail at https://wiki.ubuntu.com/Netplan/Design.)

  • All disk devices (HDDs, SSDs, NVMes, and DCPMMs) must be partitioned and mounted prior to testing. Each disk beyond the first one should ideally be configured with a single partition that spans the entire disk and that uses the ext4 filesystem.

    • As with network interfaces, the easiest way to do this is via MAAS before deployment.

    • If necessary, you can manually partition the disk (using gdisk, fdisk, parted, or similar tools), create filesystems on them (using mkfs or related tools), and mount them (with the mount command or /etc/fstab file).

  • If the SUT has DCPMMs installed, you should configure them prior to running the test suite. Note: This document assumes that the SUT will support Mixed Mode operation. If the SUT only supports a single operating mode at a time, you will need to configure DCPMMs in one mode, run tests, then re-configure the DCPMMs into the remaining mode and run the appropriate tests separately.

  • A MAAS installation configured for certification testing should provision the SUT with the Server Test Suite and related packages. If you’re using a more “generic” MAAS setup, you’ll have to install the certification software yourself, as described in Appendix A - Installing the Server Test Suite Manually.

  • If the SUT includes an nVidia GPGPU that is to be tested, please refer to Appendix G - Setting Up and Testing a GPGPU.