Power and remote access

These calls talk to the server's management controller, so they work while the operating system is down, and the power state and sensor readings come back with the server switched off. The server's own calls sit under /v1/baremetal/{serviceId}; the ISO library is at /v1/assets/isos.

Power

The power state is powerState on Get service status: ON, OFF, UNKNOWN or BMC_RESETTING. UNKNOWN means the management controller did not answer, or the server has none. The schema also lists PENDING, which this call never returns.

Send power command takes a required command:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/power \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "GRACEFUL_RESTART"
}
'

The call answers 204 with no body, and any other command value answers 400 VALIDATION_ERROR. A graceful command depends on the operating system responding to it. A server that stays ON after GRACEFUL_SHUTDOWN has an operating system that did not act on the request, and FORCE_OFF is the next step.

A power command is refused with:

Hardware readings

Three read-only calls report what the controller measures, on a server whose hardware.capabilities list the matching METRICS_* entry; on others they answer 422 OPERATION_NOT_SUPPORTED_PLATFORM:

• Get PSU health (METRICS_PSU) lists each power supply with its lineInputVoltage, powerInputWatts and status.
• Get thermals (METRICS_THERMALS) returns temperatures, each a readingCelsius with its critical thresholds, and fans, each a reading in its readingUnits.
• Get power metrics (METRICS_POWER) gives the present draw as powerConsumedWatts, and under powerMetrics the minimum, maximum and average draw over the last intervalInMin minutes.

Every status in the first two is a pair: the component's state, such as ENABLED or ABSENT, and its health, which is OK, WARNING, CRITICAL or UNKNOWN.

If these start timing out, or a console session will not open, Reset BMC restarts the management controller without touching the running server. It answers 204, and powerState reads BMC_RESETTING until the controller is back. Meanwhile power commands, operations, console sessions and virtual media answer 409 BMC_RESET_IN_PROGRESS.

Console sessions

A console session opens the server's screen and keyboard in your browser, on a server whose hardware.capabilities include KVM or IPMI; on any other the call answers 422 OPERATION_NOT_SUPPORTED_PLATFORM. The session is a port forward to the management controller that accepts connections only from the address you name in clientIpAddress, and it closes itself after timeoutSeconds, from 3600 to 86,400 (1 to 24 hours).

Name the public address, IPv4 or IPv6, of the machine you will open the console from. Behind a NAT router that is the router's public address, which a what-is-my-IP site or the router's status page shows. Open console session with it:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/console-sessions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientIpAddress": "<your-ip>",
  "timeoutSeconds": 7200
}
'

The call answers 201 with the url to open, the session's forwardId, startedAt and expiresAt. On a server whose capabilities list IPMI it also carries an ipmiUsername and ipmiPassword for the controller's login page; on one that lists KVM (Dell iDRAC9 and iDRAC10, Supermicro Gen12) both are null. A second request while the first is still being set up answers 409 KVM_SESSION_REQUEST_IN_PROGRESS; retry after Retry-After (10 seconds). A new session from the same address reuses the open one's forwardId, and its expiresAt replaces the earlier one.

List console sessions shows the sessions your organization has open, each with its url, clientIpAddress, timeoutSeconds and expiresAt. To close one before its timeout, pass its forwardId to Close console session; the call answers 204, also for a session that has already closed:

curl --request DELETE \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/console-sessions/{forwardId} \
  --header 'Authorization: Bearer <api-key>'

A session opened from a machine behind a different public address than the one you allowed will not connect. Open a new session with the right address instead of widening the old one.

Virtual media

Virtual media attaches an ISO file to the server as a drive, to boot an installer or a rescue system that the image list does not offer. It works on servers whose hardware.capabilities include VIRTUAL_MEDIA; Supermicro Gen11 and ASRock machines answer a mount with 422 and OPERATION_NOT_SUPPORTED_PLATFORM. The ISO has to be in your library first.

Upload an ISO

Uploading takes three calls, and the file itself goes straight to storage rather than through the API:

1. Start ISO upload with a displayName of 3 to 64 characters and the file's exact sizeBytes (at most 20,971,520,000 bytes, which is 2,000 parts). It answers 201 with the ISO's id, totalParts and one pre-signed uploadUrls entry per part.
2. Split the file into 10 MiB parts (10,485,760 bytes; the last part is whatever remains) and PUT part n to the nth URL. The URLs expire two hours after they are issued.
3. Complete ISO upload. Once the uploaded parts add up to the declared size, it answers 200 with the ISO file, and its isReady turns true there and in List ISOs. Parts that fall short answer 422 ISO_UPLOAD_INCOMPLETE, and a storage outage answers 503 UPSTREAM_UNAVAILABLE.

stat -c %s installer.iso prints the size to send (stat -f %z on macOS):

curl --request POST \
  --url https://api.serverside.com/v1/assets/isos \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "rescue",
  "sizeBytes": 734003200
}
'

With the response saved as upload.json, this shell loop splits the file and sends each part to its URL:

split -b 10485760 -d -a 4 installer.iso part-
i=0
for url in $(jq -r '.data.uploadUrls[]' upload.json); do
  curl -s -X PUT --upload-file "part-$(printf '%04d' $i)" "$url"
  i=$((i + 1))
done

split -d is the GNU form; on macOS use gsplit. Then complete the upload with the ISO's id:

curl --request POST \
  --url https://api.serverside.com/v1/assets/isos/{isoId}/complete-upload \
  --header 'Authorization: Bearer <api-key>'

The number of ISO files an organization may hold is baremetal.maxIsoFiles on Get entitlements, where null means no limit. Uploads that were never completed count towards it, and once the organization holds more files than the limit, a new upload answers 422 ISO_LIMIT_REACHED. Delete ISO frees a place; an ISO that is mounted cannot be deleted (409 ENTITY_IN_USE).

Mount it

Mount virtual media takes the ISO's id as isoFileId and expirySeconds between 1800 and 43,200 (30 minutes to 12 hours). An ISO whose upload has not completed is refused with 422 ISO_UPLOAD_INCOMPLETE.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/virtual-media \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "isoFileId": "<iso-id>",
  "expirySeconds": 3600,
  "isOneTimeBoot": true
}
'

The call answers 201 with the mount's deviceIndex, isoFileId and expiresAt. With isOneTimeBoot set to true, the same call boots the server from the ISO once: it powers a stopped server on, and restarts a running one at once, without asking the operating system to shut down. Watch the installer over a console session. Without it, the ISO is attached as a drive and the boot order stays as it was.

A server holds one mount at a time, and a new mount replaces the last. List virtual media shows it, and List ISOs for a service marks the mounted file with isMounted, mountExpiresAt and deviceIndex. Eject virtual media detaches it before it expires and answers 204; an index with nothing mounted on it ejects the recorded mount.