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. The schema also lists PENDING, which is never returned.

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.

Hardware readings

Three read-only calls report what the controller measures:

• Get PSU health lists each power supply with its status, lineInputVoltage and powerInputWatts.
• Get thermals returns temperatures and fans.
• Get power metrics 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.

KVM console

A KVM session opens the server's screen and keyboard in your browser, on a server whose hardware.capabilities includes KVM. 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 (at least 1).

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 response holds the url to open and a forwardId. It also carries an ipmiUsername and ipmiPassword for the console's login page, except on Dell iDRAC9 and iDRAC10 and Supermicro Gen12 machines, where both are null. List KVM sessions shows the open ones; to close one before its timeout, pass its id to Close KVM session as forward_id:

curl --request DELETE \
  --url 'https://api.serverside.com/v1/services/baremetal/{serviceId}/ikvm?forward_id={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 includes VIRTUAL_MEDIA; Supermicro Gen11, ASRock and Dell iDRAC8 machines answer a mount with 400 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 21,474,836,480 bytes, 20 GiB). 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 stored object matches the declared size; the ISO's ready flag in List ISOs turns true at the same moment.

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; Delete ISO frees a place.

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.

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, always in the first slot. List virtual media mounts shows it with its deviceIndex and expiry, and Eject virtual media detaches it early; the call ignores the index in its path.