Power management reference

To manage a machine, MAAS must be able to power cycle it, usually through the machine’s BMC↗ card. Until you configure the power type, a newly-added machine can’t be enlisted and used by MAAS.

About IPMI cipher suites

We require the user to explicitly set the cipher suite due to the fact that one BMC’s order is different from another, leading to erroneous discovery. You can explicitly select which cipher suite to use when interacting with a BMC. You do this by selecting the cipher suite in power configuration. By default, the cipher suite is 3. This is the least secure suite. It is up to you to select a more secure suite if supported and desired.

Power management reference guide

This article will help you learn:

• How to configure a machine’s power type
• How to configure and use IBM Z with MAAS
• How to use the virsh power type
• Which BMC drivers are supported

In addition, this article provides a complete catalogue of power parameters, by type.

You may also like to try maaspower↗ which is a community project designed to be used with the MAAS webhook driver. It is a pluggable system that accepts MAAS webhooks and can translate them to other external systems. Note: it is not supported by Canonical.

How to configure a machine’s power type

To (re)configure a machine’s power type, first find the machine’s $SYSTEM_ID with the following recipe:

maas admin machines read | jq -r '(["HOSTNAME","SIS'S"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id]) | @tsv' | column -t

Next, use the MAAS CLI command maas machines... to (re)set the machine’s power type, like this:

maas $PROFILE machine update $SYSTEM_ID power_type="$POWER_TYPE"

where $POWER_TYPE can have the following values:

Note the required and optional parameters associated with each power type.

Once you’ve successfully processed the command (as indicated by a stream of JSON, headed by “Success!”), MAAS performs a power check on the machine. A successful power check is a good indication that MAAS can properly communicate with the machine, that is, it should quickly result in a power status of “Power off”. A failed attempt will return errors that should guide you to fix your power_parameters.

Power catalogue

Intel AMT

All parameters are entered as key=value, e.g., power_type=amt. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

American Power Conversion (APC) PDU

All parameters are entered as key=value, e.g., power_type=apc. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Digital Loggers, Inc. PDU

All parameters are entered as key=value, e.g., power_type=dli. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Eaton PDU

All parameters are entered as key=value, e.g., power_type=eaton. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

IBM Hardware Management Console (HMC)

All parameters are entered as key=value, e.g., power_type=hmc. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

LXD VMs

All parameters are entered as key=value, e.g., power_type=lxd. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

IPMI

All parameters are entered as key=value, e.g., power_type=amt. The MAAS CLI will refuse the request with informative errors if required parameters are excluded. Power driver specific parameters should be prefixed with power_parameters_{key}.

Some of the fields for this power type have fixed choices, indicated in the “Choices” column.

Manual power configuration

Manual power configuration means exactly that – manually configured at the unit. The only MAAS CLI parameter is power_type=amt.

HP Moonshot - iLO4 (IPMI)

All parameters are entered as key=value, e.g., power_type=moonshot. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

HP Moonshot - iLO Chassis Manager

All parameters are entered as key=value, e.g., power_type=mscm. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Microsoft OCS - Chassis Manager

All parameters are entered as key=value, e.g., power_type=msftocs. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

OpenStack Nova

All parameters are entered as key=value, e.g., power_type=nova. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

OpenBMC Power Driver

All parameters are entered as key=value, e.g., power_type=openbmc. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Christmann RECS-Box Power Driver

All parameters are entered as key=value, e.g., power_type=recs_box. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Redfish

All parameters are entered as key=value, e.g., power_type=redfish. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

SeaMicro 15000

All parameters are entered as key=value, e.g., power_type=sm15k. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Some of the fields for this power type have fixed choices, indicated in the “Choices” column.

Cisco UCS Manager

All parameters are entered as key=value, e.g., power_type=ucsm. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

virsh - libvirt KVM

All parameters are entered as key=value, e.g., power_type=virsh. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

VMware

All parameters are entered as key=value, e.g., power_type=vmware. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

Facebook’s Wedge

All parameters are entered as key=value, e.g., power_type=amt. The MAAS CLI will refuse the request with informative errors if required parameters are excluded.

How to use the virsh power type

Consider a machine backed by a KVM, accessed via virsh. You can create a corresponding MAAS machine and set its power parameters with a command like this one:

maas admin machines create \
architecture=amd64 \
mac_addresses=52:54:00:15:36:f2 \
power_type=virsh \
power_parameters_power_id=f677a842-571c-4e65-adc9-11e2cf92d363 \
power_parameters_power_address=qemu+ssh://stormrider@192.168.123.1/system \
power_parameters_power_pass=xxxxxxxx

If successful, this will return:

Success.

Machine-readable output follows this announcement. The JSON generated by this command is shown in the detail block.

{
    "storage": 0.0,
    "tag_names": [],
    "special_filesystems": [],
    "memory": 0,
    "boot_disk": null,
    "virtualblockdevice_set": [],
    "hardware_info": {
        "system_vendor": "Unknown",
        "system_product": "Unknown",
        "system_family": "Unknown",
        "system_version": "Unknown",
        "system_sku": "Unknown",
        "system_serial": "Unknown",
        "cpu_model": "Unknown",
        "mainboard_vendor": "Unknown",
        "mainboard_product": "Unknown",
        "mainboard_serial": "Unknown",
        "mainboard_version": "Unknown",
        "mainboard_firmware_vendor": "Unknown",
        "mainboard_firmware_date": "Unknown",
        "mainboard_firmware_version": "Unknown",
        "chassis_vendor": "Unknown",
        "chassis_type": "Unknown",
        "chassis_serial": "Unknown",
        "chassis_version": "Unknown"
    },
    "address_ttl": null,
    "memory_test_status": -1,
    "other_test_status_name": "Unknown",
    "osystem": "",
    "status_message": "Commissioning",
    "netboot": true,
    "physicalblockdevice_set": [],
    "node_type": 0,
    "cpu_test_status": -1,
    "memory_test_status_name": "Unknown",
    "bcaches": [],
    "storage_test_status": 0,
    "system_id": "bhxws3",
    "status": 1,
    "commissioning_status": 0,
    "power_type": "virsh",
    "locked": false,
    "numanode_set": [
        {
            "index": 0,
            "memory": 0,
            "cores": []
        }
    ],
    "bios_boot_method": null,
    "fqdn": "ace-swan.maas",
    "node_type_name": "Machine",
    "hostname": "ace-swan",
    "volume_groups": [],
    "testing_status": 0,
    "network_test_status": -1,
    "other_test_status": -1,
    "interface_test_status": -1,
    "hwe_kernel": null,
    "blockdevice_set": [],
    "testing_status_name": "Pending",
    "power_state": "unknown",
    "min_hwe_kernel": "",
    "owner": "admin",
    "distro_series": "",
    "storage_test_status_name": "Pending",
    "cpu_speed": 0,
    "swap_size": null,
    "cpu_test_status_name": "Unknown",
    "hardware_uuid": null,
    "architecture": "amd64/generic",
    "pool": {
        "name": "default",
        "description": "Default pool",
        "id": 0,
        "resource_uri": "/MAAS/api/2.0/resourcepool/0/"
    },
    "cache_sets": [],
    "pod": null,
    "iscsiblockdevice_set": [],
    "disable_ipv4": false,
    "status_action": "",
    "boot_interface": {
        "name": "eth0",
        "id": 10,
        "product": null,
        "system_id": "bhxws3",
        "effective_mtu": 1500,
        "children": [],
        "link_connected": true,
        "enabled": true,
        "interface_speed": 0,
        "numa_node": 0,
        "firmware_version": null,
        "parents": [],
        "discovered": null,
        "params": "",
        "links": [],
        "sriov_max_vf": 0,
        "tags": [],
        "type": "physical",
        "vlan": null,
        "vendor": null,
        "link_speed": 0,
        "mac_address": "52:54:00:15:36:f2",
        "resource_uri": "/MAAS/api/2.0/nodes/bhxws3/interfaces/10/"
    },
    "cpu_count": 0,
    "domain": {
        "authoritative": true,
        "ttl": null,
        "resource_record_count": 0,
        "name": "maas",
        "is_default": true,
        "id": 0,
        "resource_uri": "/MAAS/api/2.0/domains/0/"
    },
    "current_testing_result_id": 7,
    "default_gateways": {
        "ipv4": {
            "gateway_ip": null,
            "link_id": null
        },
        "ipv6": {
            "gateway_ip": null,
            "link_id": null
        }
    },
    "interface_set": [
        {
            "name": "eth0",
            "id": 10,
            "product": null,
            "system_id": "bhxws3",
            "effective_mtu": 1500,
            "children": [],
            "link_connected": true,
            "enabled": true,
            "interface_speed": 0,
            "numa_node": 0,
            "firmware_version": null,
            "parents": [],
            "discovered": null,
            "params": "",
            "links": [],
            "sriov_max_vf": 0,
            "tags": [],
            "type": "physical",
            "vlan": null,
            "vendor": null,
            "link_speed": 0,
            "mac_address": "52:54:00:15:36:f2",
            "resource_uri": "/MAAS/api/2.0/nodes/bhxws3/interfaces/10/"
        }
    ],
    "status_name": "Commissioning",
    "commissioning_status_name": "Pending",
    "owner_data": {},
    "ip_addresses": [],
    "raids": [],
    "network_test_status_name": "Unknown",
    "description": "",
    "current_commissioning_result_id": 6,
    "interface_test_status_name": "Unknown",
    "current_installation_result_id": null,
    "zone": {
        "name": "default",
        "description": "",
        "id": 1,
        "resource_uri": "/MAAS/api/2.0/zones/default/"
    },
    "resource_uri": "/MAAS/api/2.0/machines/bhxws3/"
}

Which BMC drivers are supported

MAAS supports many types of BMC hardware, though not all the drivers have the same capabilities. See the below table for a feature comparison of the BMC drivers currently supported by MAAS.

* The ‘Facebook’s Wedge’ OpenBMC power driver is considered experimental at this time.

How to configure and use IBM Z with MAAS

The IBM Z or LinuxONE system can host MAAS controllers and is able to deploy predefined logical partitions (LPARs) KVM host(s), and virtual machines, if the mainframe is set up properly for MAAS.

The basic architecture is similar to this:

Networking would be structured like this:

Note that net-booting the KVM guests (through the two bridges) can be problematic. There are two options:

1. Adding VNIC characteristics to enable “learning” on the network interface that’s the base for bridge “br2.” This is the recommended approach.

2. Enable full promiscuous bridge port mode at the network interface that’s the base for bridge “br2.” This approach is not recommended because it has some built-in limitations.

MAAS will automatically configure option 1 for you, in case an LPAR is deployed as KVM host (the bridge names may differ).

In order to achieve this configuration, there are a number of steps that must be executed; specifically, you must know how to:

• Evaluate IBM Z requirements
• Login to the IBM Z
• Set up a suitable partition for MAAS
• Set up networking for MAAS
• Set up storage for MAAS
• Set the partition boot parameters
• Set up your IBM Z virtual machines for enlistment

The MAAS controller does not necessarily need to run on an LPAR on the IBM Z system itself, but can also run on a different system outside. But since the MAAS controller requires a network connection to the hardware management console (HMC), it is recommended to keep it co-located and (for security reasons) as close as possible to the HMC and run it in a dedicated LPAR.

Such a MAAS controller LPAR should have at least two SMT hardware threads (one IFL), since it runs several services (bind, rack-, region-controller and more), 16 GB RAM and 100 GB disk space - recommended is to use the double amount of these resources.

The resources of the LPARs to deploy on (‘machines’ in terms of MAAS) depending on the use case. LPARs that are deployed as KVM host would of course require significantly more resources to be able to host KVM guest on top.

There are several constraints on the definition and setup of the ‘machine’ LPARs - please see below.

Evaluate IBM Z requirements

The system requirements to host MAAS and its virtual machines on the IBM Z platform are as follows:

• IBM z14 GA2 (or newer) or IBM LinuxONE III (or newer)
• HMC running in DPM mode (mandatory, traditional mode is not supported!)
• HMC firmware level H39 - (HMC at H40 and SE at S55)
• HMCs Rest-API enabled
• python-zhmcclient (0.29 or later) running on the MAAS controller system, connected to the HMC
• HMC user ID for the zhmcclient access to the HMC API (must have permissions for the “Manage Web Services API Logs” role and “Manage Web Services API Logs” role)
• I/O auto-configuration enabled for the ‘machine’ LPARs
• zFCP (SCSI) disk storage (only, no DASD support), recommended are two disks, one defined as type ‘boot,’ the second as type ‘data’
• a dedicated storage group per ‘machine’ LPAR; these must include the dedicated zFCP storage for this particular managed LPAR only (‘boot’ and ‘data’ for LPAR n) - but no additional shared storage!
• qeth network devices (Hipersockets or OSA, recommended); at least one qeth NIC, recommended two (or more)
• Ubuntu Server 20.04 installed on a dedicated system (LPAR or PC), that acts as MAAS Controller
• one or more LPARs as ‘machines’ (aka MAAS deployment targets)

Be aware that these are minimum system requirements.

Access the HMC and login to the IBM Z

To login to the HMC, you must have at least “system programmer” privileges. Gaining that level of access is beyond the scope of this document. Once you are sure that you have the necessary access, you first need to navigate to the Hardware Management Console (HMC) application in your Web browser:

Click on the “Log on…” link, which will bring you to a login screen:

Upon successfully logging on, you will land on the Welcome Screen:

Select the “Tasks Index” on the left-hand navigation:

From here, you will be able to access the commands needed to prepare your IBM Z to host MAAS.

Set up a suitable IBM Z partition for a MAAS machine

In order to prevent MAAS from taking over the entire system, you must assign both the controller and the ‘machines’ / KVM hosts to specific partitions, with suitable limitations. To set up suitable IBM Z partitions for hosting MAAS, you must choose “Partition Details” from the “Tasks Index,” which will bring you to a screen like this one:

You must then choose the “target object” (in this case we’ve chosen TA05) to be operated upon:

Click “OK,” and you’ll arrive at a screen similar to the one below:

Make sure you’re on the “Partitions” tab, and select the desired object (“TA05…”):

Right-click on the selected object and select “Partition Details:”

On the “General” tab, edit the partition details to suit your proposed MAAS deployment:

Next, you will set up the networking details for this partition, as shown in the following section.

Set up IBM Z networking for a MAAS machine

To properly enable networking within the IBMZ partitions, you must change to the “Network” tab under “Partition Details:”

Click on the NIC of interest to bring up the “NIC Details” screen:

Confirm that the parameters on this screen are consistent with your planned MAAS deployment, then bring up the network adapter(either OSA or Hipersockets) by selecting it:

Ensure that all settings on the “General” tab conform to your planned MAAS deployment; then select the “Network Interface Cards” tab on the left-hand navigation:

Again, ensure that the parameters associated with the networking arrangement are consistent with your planned MAAS deployment.

Next, you will set up the storage layout for your MAAS partition(s).

Set up IBM Z storage for a MAAS machine

To set up suitable storage for a MAAS deployment, you should bring up the “Partition Details” for your chosen MAAS partition and select the “Storage” tab from the left-hand navigation:

Choose the “VOLUMES” sub-tab, and lick on the hyperlinked partition name to bring up the storage configuration tab:

Click on “GET DETAILS” for the Boot Volume in the Volume list to bring up the “Configuration details” screen:

Ensure that the Boot Volume is configured appropriately for your planned MAAS deployment, then click “Done.” Then return to the storage configuration tab and choose the Data Volume, and tune it to the appropriate parameters.

Next, choose the “ADAPTERS” sub-tab to bring up information on the storage adapters:

Set any necessary parameters to conform to your planned MAAS deployment.

Set the partition boot parameters

Return to the “Partition Details” screen and select the “Boot” tab in the left-hand navigation:

Change any settings as necessary to support your planned MAAS deployment.

Set up your IBM Z virtual machine for enlistment

To cause IBM Z KVM partition guests to enlist, it’s necessary to manually put in the BMC information for each guest. MAAS can then detect the guest, enlist it, and boot it as necessary.