Custom iPXE scripts

A custom iPXE script replaces the image list with whatever installer or live system you point it at. When a server boots from the network, the provisioning system looks up the booting port's MAC address and serves the script stored on that service, so running one takes the stored script, the PXE boot mode and a restart.

1. Store the script

Set iPXE script stores up to 65,536 characters. The script starts with the #!ipxe line, as every iPXE script does, and goes in the body as one JSON string with \n between its lines:

curl --request PUT \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/ipxe \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "script": "#!ipxe\nchain --autofree http://boot.netboot.xyz"
}
'

This example chains to netboot.xyz, a public menu of installers. An unattended install instead loads a kernel and an initrd with the arguments your installer needs:

#!ipxe
kernel http://mirror.example.com/debian/linux auto=true priority=critical url=http://config.example.com/preseed.cfg
initrd http://mirror.example.com/debian/initrd.gz
boot

While the server boots from the network, its untagged port carries our provisioning network and your own networks move to tagged VLANs; the cloud console warns of this as a native network change. The provisioning network gives the server an IPv4 address over DHCP and reaches the internet, so the script and the installer it starts can fetch from public mirrors.

Get iPXE script returns the stored script, null when there is none.

2. Boot from the network

Set boot mode to PXE, then restart the server with a power command:

curl --request PUT \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/boot-mode \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bootMode": "PXE"
}
'

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": "FORCE_RESTART"
}
'

The boot-mode call can answer 202 Accepted: the change is then still being applied when the response arrives. A KVM session shows the script running.

3. Return to the local disk

While the boot mode is PXE, every restart boots from the network and runs the script again. Once the installer has written the disk, set the mode back:

curl --request PUT \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/boot-mode \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bootMode": "LOCAL_DISK"
}
'

Delete iPXE script clears the stored script when you no longer need it. A server left in PXE mode with no script stored boots our installer image instead, which powers the server off.

Set the mode back to LOCAL_DISK before starting a deployment from the image list as well. With a script stored, a server in PXE mode can boot your script in place of the installer the deployment needs.