Power and remote access

These calls talk to the server's management controller, so they work while the operating system is down, and power-state and sensor calls work with the server switched off. Their paths all start with /v1/services/baremetal/{serviceId}.

Power

Get power status returns one of ON, OFF, UNKNOWN or BMC_RESETTING as data. 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 command:

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

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 status, lineInputVoltage and powerInputWatts.
• Get thermals (METRICS_THERMALS) returns temperatures and fans.
• 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.

If these start timing out, or a KVM session will not open, Reset BMC restarts the management controller without touching the running server. Power status reads BMC_RESETTING until it is back, and power commands meanwhile answer 409 BMC_RESET_IN_PROGRESS.

KVM console

A KVM 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 timeoutHours, from 1 to 24.

Name the public IPv4 address 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. Create KVM session with it:

curl --request POST \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/ikvm \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientIpAddress": "<your-ipv4>",
  "timeoutHours": 2
}
'

The call answers 201 with the url to open, a forwardId and the session's 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).

List KVM sessions shows the open ones, each with its sessionUrl and expiresAt. To close one before its timeout, pass its id to Close KVM session as forwardId; the call answers 204, also for a session that has already closed:

curl --request DELETE \
  --url 'https://api.serverside.com/v1/services/baremetal/{serviceId}/ikvm?forwardId={forwardId}' \
  --header 'X-API-KEY: <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). The response has 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. It answers true once the uploaded parts add up to the declared size, and the ISO's ready flag in List ISOs turns true at the same moment. Parts that fall short answer 422 ISO_UPLOAD_INCOMPLETE.

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/iso/upload \
  --header 'X-API-KEY: <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/iso/upload/{isoId}/complete \
  --header 'X-API-KEY: <api-key>'

An organization holding more than ten ISOs cannot start another upload (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 fileId, expirySeconds between 1800 and 43,200 (30 minutes to 12 hours), and bootOnce, to boot from the ISO on the next start only. An ISO whose upload has not completed is refused with 422 ISO_UPLOAD_INCOMPLETE.

curl --request POST \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/virtual-media/mount \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fileId": "<iso-id>",
  "expirySeconds": 3600,
  "bootOnce": true
}
'

Then restart the server with a power command and watch the installer over the KVM console.

A server holds one mount at a time, and a new mount replaces the last. List virtual media mounts shows it with its deviceIndex and expiry, and Eject virtual media detaches it early; any index in its path ejects the mount.