managed-systems

Managed systems of an IBM HMC, by its REST API

Returns, for each IBM Power server a Hardware Management Console (HMC) manages, its state as the HMC sees it and its attention LED, read from the HMC REST API with an account. Three watches are offered, each one set on the probe. It is the first probe to put on an HMC; serviceable-events says what an attention LED is lit for.

Versions

Written for the HMC REST API (Web Services API, schema V1_1_0 and later) as IBM documents it for the HMC of POWER9 (HMC V9) and Power10 (HMC V10): the Logon resource and the ManagedSystem resource, whose quick properties State, SystemName and PhysicalSystemAttentionLEDState are the elements read. Hence the common level, under the folder hmc of the product.

How it works

The collector opens a session once, then reads the list of the managed systems:

1. PUT https://<host:address>/rest/api/web/Logon, of type application/vnd.ibm.powervm.web+xml; type=LogonRequest, the body IBM documents:

<LogonRequest xmlns="http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/" schemaVersion="V1_1_0">
  <Metadata><Atom/></Metadata>
  <UserID kb="CUR" kxe="false">…</UserID>
  <Password kb="CUR" kxe="false">…</Password>
</LogonRequest>

The HMC answers a LogonResponse whose X-API-Session is the session.

2. GET https://<host:address>/rest/api/uom/ManagedSystem, the session in the header X-API-Session. The HMC answers an Atom feed, one entry per managed system:

<entry><id>…UUID…</id><content type="application/vnd.ibm.powervm.uom+xml; type=ManagedSystem">
  <ManagedSystem:ManagedSystem …>
    <PhysicalSystemAttentionLEDState kb="ROO" kxe="false">false</PhysicalSystemAttentionLEDState>
    <State kb="ROR" kxe="false">operating</State>
    <SystemName kb="CUR" kxe="false">p10-a</SystemName>

• A system is named by its SystemName; two systems of one name each keep their own, the second carrying its UUID (p10-a #…).
• state is the HMC's, as it writes it: operating for a server running; any other value (powered off, in error, no connection to its service processor…) is returned as written.
• attention-led is true or false: the server lights its attention LED when it logs a problem that needs service.
• A code 401 or 403 at the logon stops the collector misconfigured (the account is refused); any other code but 200 stops it unreachable. No system at all stops it misconfigured: the account sees only the systems its resource role is set on.

The session

IBM asks that each session opened by Logon be closed by its DELETE once done, and an IBM support note (node 1115679, "HMC REST API sessions") tells of an HMC that held thousands of sessions never closed, used up its memory and refused the REST API until it was restarted; the same note advises to keep and reuse one session. A probe runs every few minutes: opening and closing a session at every run would load the HMC for nothing, and a run cut short would leave one behind. So the collector keeps one session per probe, from one run to the next:

• The session is kept in the cache of the probe, encrypted on the poller (it is a secret: the answer that carried it had the password in its body). Each run that reads with it keeps it seven more days.
• A session the HMC no longer knows (it expired, the HMC restarted) is refused, 401 or 403. The collector then closes it, DELETE https://<host:address>/rest/api/web/Logon with that session in X-API-Session, whatever the HMC answers, opens a new one and reads again, once. A second refusal stops the collector misconfigured: the account may not read the list.
• When the poller stops, the session stays open on the HMC, as it would between two runs; the cache crosses a restart of the poller, and the next run takes it back if the HMC still knows it.
• When the probe is deleted, or when the poller does not run it for seven days, its cache is erased with the session in it: that session can no longer be closed by the collector, and stays on the HMC until the HMC drops it.
• Each probe of an HMC keeps its own session: five probes, five sessions.

The password comes from protocol:http:password, a secret variable: it only goes, written by xml.escape, in the body of the logon. The session only goes in the header X-API-Session, and in the cache. The logon and its DELETE are the only requests that are not a GET: they open and close the session, and change nothing on the managed systems.

Prerequisites

• The HMC's address as the host's address, reachable from the poller in HTTPS (443, the port of the HMC REST API). Its certificate follows the TLS profile of the probe: the HMC's self-signed certificate is trusted by pinning its fingerprint (protocol:http:fingerprint), by adding its authority under protocol:tls:authorities, or by trusting the first fingerprint in the tab "Security".
• An HMC account in protocol:http:user and protocol:http:password, of the task role hmcviewer (Viewer: it views the HMC and the systems, and changes nothing), the narrowest of the predefined roles, with a resource role that covers the managed systems to watch (the predefined resource role gives all of them).

Outputs

Watches

• A server kept in standby or powered off on purpose has its state added to not-operating's list, or the watch unchecked, on its probe.

Limits

• The address is written into the URL as is: an IPv6 address must be given as a name.
• The values of State other than operating are not listed in IBM's public documentation: the collector returns them as written, and not-operating raises on any of them.
• Each value is read as the HMC writes it, with its attributes kb and kxe; a value written without attributes would stop the collector misconfigured, never return a wrong value.
• How long the HMC keeps an idle session is not in IBM's documentation; the support note speaks of a few weeks.
• IBM's documentation gives 403 for a session the HMC does not know; IBM's client library, pypowervm, logs on again on 401. The collector takes both for a refused session.
• Not checked against an HMC: the routes are those of IBM's documentation of the HMC REST APIs (Logon, ManagedSystem, HTTP Status Codes, Request Headers). The layout of the feed (entry, content, ManagedSystem:ManagedSystem, the attributes kb and kxe), the value operating and the answer 204 to an empty feed are read in the responses of an HMC that IBM's own client library, pypowervm, publishes for its tests.