Custom iPXE scripts

A custom iPXE script replaces the image list with whatever installer or live system you point it at. When a server in the PXE boot mode 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. All three iPXE calls, reading the script included, need the organization.baremetal.update permission.

1. Store the script

Set iPXE script stores 1 to 65,536 characters and replaces any script stored before. 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/baremetal/{serviceId}/ipxe \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "script": "#!ipxe\nchain --autofree http://boot.netboot.xyz"
}
'

The call answers 200 with the stored script. 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

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

A new server can carry its script from the start. An order item or Create bare metal service that sends bootMode PXE with an ipxeScript boots that script once, as soon as provisioning has set up the server's network, so steps 1 and 2 are already done for it.

2. Boot from the network

While the boot mode is PXE, the server's native VLAN is our provisioning network, and every network attached to the server arrives tagged, including one attached as native. The server's internet access network arrives on VLAN 10, and every other network on its own localVlanId; each network in the server's interfaces shows the tag it gets in this mode as provisioningVlanId. 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 without configuring a VLAN.

Set boot mode to PXE:

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

The switch change runs after the response. The call answers 202 with the change's status (APPLYING) and since, or 204 when the server was already in that mode. While a deployment or test is running it answers 409 OPERATION_IN_PROGRESS, and while another network change is applying, 409 NETWORK_CHANGE_IN_PROGRESS with a Retry-After of 10 seconds.

Send Get service status until networkChange is null, which means the switches carry the new layout; FAILED there means the change could not be applied. Then restart the server with a power 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": "FORCE_RESTART"
}
'

A console session shows the script running.

3. Return to the local disk

While the boot mode is PXE, every power command that starts the server boots it from the network and runs the script again. A reboot started inside the operating system may not: some management controllers drop the network boot setting after one boot, and the server then follows its own boot order. Once the installer has written the disk, set the mode back:

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

Once the mode is back to LOCAL_DISK, networks attached as native are untagged again. Configure the installed system for that layout, not for the tagged one the installer sees.

Delete iPXE script clears the stored script when you no longer need it, and answers 204. 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, and wait for networkChange to clear: a deployment requested while the change applies answers 409 NETWORK_CHANGE_IN_PROGRESS. With a script stored, a server in PXE mode can boot your script in place of the installer the deployment needs.