iPXE Boot

iPXE Boot is a solution based on Preboot Execution Environment (PXE) technology. It allows a server to connect to network images during startup and execute predefined instructions. Here is how it works: you prepare your iPXE script, which will run either during server creation or reinstallation, or when the server boots up. There are several ways to activate the service — you can learn about each of them in the Getting started section below. Technically, iPXE Boot is implemented as an additional feature for dedicated servers. You can check which locations support iPXE Boot by performing the List locations request.

An iPXE script is a text instruction with iPXE commands to be executed during server boot. An iPXE script has to start with a #!ipxe line. More in the iPXE documentation.

#!ipxe
dhcp
set base-url http://boot.example.com
kernel ${base-url}/vmlinuz initrd=initrd.img quiet
initrd ${base-url}/initrd.img
boot

An iPXE configuration (ipxe_config) is a parameter to pass the content of an iPXE script as a string. This is how the script above looks as a string parameter in the iPXE configuration, where line breaks are replaced with \n characters.

#!ipxe \n dhcp \n set base-url http://boot.example.com \n kernel ${base-url}/vmlinuz initrd=initrd.img quiet \n initrd ${base-url}/initrd.img \n boot

An image URL is a link to reach a necessary image located somewhere on the Internet. Thus, you can pass other operating system images via URL within an iPXE configuration.

A boot mode is an option to boot a server:

• Persistent iPXE Boot — a server always loads via iPXE as long as the iPXE Boot feature is active.
• Default Boot — a regular way to load a server via BIOS/UEFI.

Getting started

There are three ways to activate the iPXE Boot feature:

• Order-based — the feature is activated during a server order setup if conditions are met.
• Reinstall-based — the feature is activated during an OS reinstall if conditions are met.
• Standalone — the feature is activated when a server is in its normal operational status.

Order-based activation

1. Create a dedicated server using a Create a dedicated server request with the following parameters:
   • operating_system_id: null (a server should be ordered without OS)
   • features: private_ipxe_boot or public_ipxe_boot
   • ipxe_config (a string as shown in the iPXE configuration example)
   • ssh_key_fingerprints (if necessary)
   • user_data (if necessary)
2. During creation, the server will boot over the network and execute instructions from the iPXE configuration.
3. Once it's completed, the server will stay in iPXE Boot mode as long as the feature is active.

Reinstall-based activation

1. Use a Activate private iPXE Boot feature or Activate public iPXE Boot feature request to activate the feature.
2. Reinstall an operating system using a Reinstall OS for a dedicated server request with the following parameters:
   • operating_system_id: null (a server should be ordered without OS)
   • ipxe_config (a string as shown in the iPXE configuration example)
   • ssh_key_fingerprints (if necessary)
   • user_data (if necessary)
3. During reinstallation, the server will boot over the network and execute instructions from the iPXE configuration.
4. Once it's completed, the server will stay in iPXE Boot mode as long as the feature is active.

Standalone activation

The iPXE Boot feature has to be disabled.

1. Send an Update a dedicated server request to update a dedicated server, specifying the ipxe_config parameter.
2. Use a Activate private iPXE Boot feature or Activate public iPXE Boot feature request to activate the feature.
3. Manually reboot the server so that instructions from the iPXE configuration will be applied.

Limitations

The general limitations include the following:

• Available in some locations (list locations to see availability of the feature).
• Only one feature can be activated at a time: private or public iPXE Boot.
• Available only when no OS is selected (provisioning/reinstall without OS).
• Unavailable during creation or reinstall in process.
• Maximum iPXE configuration size is 64KB.
• Incompatible with L2 Segments, Firewall, and rescue mode.

Additionally, each type has its own limitations:

• Private iPXE Boot is incompatible with the No private IP address feature.
• Public iPXE Boot is incompatible with the No public network and No public IP address features.

Use cases

The following examples show how to activate and use iPXE Boot in three common scenarios. The API requests and iPXE scripts below are examples — replace all values such as server IDs, hostnames, URLs, and credentials with your own.

Creating a server with Public iPXE Boot (Alpine LTS)

You can activate Public iPXE Boot during server ordering by including the feature and an iPXE script in the creation request. The server boots via iPXE immediately after provisioning — no reinstall or manual reboot is needed.

This example uses Alpine LTS loaded from a public HTTP image server.

iPXE script used in this example:

#!ipxe
set url http://example.com/pxe-test-images
set flavor lts
set bootif 01-${external_iface1_mac}

kernel ${url}/vmlinuz-${flavor} console=tty0 modules=loop,squashfs quiet nomodeset alpine_repo=https://dl-cdn.alpinelinux.org/alpine/v3.16/main modloop=${url}/modloop-${flavor} ip=dhcp BOOTIF=${bootif}
initrd ${url}/initramfs-${flavor}
boot

1. Send a Create a dedicated server request as shown in the example below. Include "features": ["public_ipxe_boot"], "operating_system_id": null, and your iPXE script as the ipxe_config string.

curl -s -X POST \
  -H "Authorization: Bearer <PAPI token>" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": 46,
    "server_model_id": 15615,
    "uplink_models": {
      "private": { "id": 10202 },
      "public": { "id": 10199, "bandwidth_model_id": 13834 }
    },
    "ram_size": 128,
    "drives": {
      "slots": [
        { "position": 0, "drive_model_id": 10308 }
      ],
      "layout": [
        {
          "slot_positions": [0],
          "ignore": true
        }
      ]
    },
    "operating_system_id": null,
    "features": ["public_ipxe_boot"],
    "ipxe_config": "#!ipxe\nset url http://example.com/pxe-test-images\nset flavor lts\nset bootif 01-${external_iface1_mac}\n\nkernel ${url}/vmlinuz-${flavor} console=tty0 modules=loop,squashfs quiet nomodeset alpine_repo=https://dl-cdn.alpinelinux.org/alpine/v3.16/main modloop=${url}/modloop-${flavor} ip=dhcp BOOTIF=${bootif}\ninitrd ${url}/initramfs-${flavor}\nboot",
    "ipv6": false,
    "hosts": [
      {
        "hostname": "test-ipxe.example.com"
      }
    ]
  }' \
  "https://api.servers.com/v1/hosts/dedicated_servers" | jq .

2. Wait for the server to be provisioned. During this time, the server boots from the network and executes the iPXE script.
3. Once provisioning is complete, the server stays in iPXE Boot mode as long as the public_ipxe_boot feature is active.

Activating Private iPXE Boot via OS reinstall (Ubuntu 24)

You can activate Private iPXE Boot on an existing server by running a reinstall without an OS. This is useful when you want to switch a server to iPXE Boot without re-ordering it. This example boots Ubuntu 24 from a private HTTP image server. The iPXE script shows an interactive menu with options for Ubuntu 24 and an iPXE shell.

iPXE script used in this example:

#!ipxe
set bootif 01-${internal_iface1_mac}

:menu
menu iPXE Boot Menu
item ubuntu_24 Ubuntu 24
item shell    iPXE Shell
choose --default ubuntu_24 --timeout 5000 target && goto ${target}

:ubuntu_24
kernel http://example.com/test-ipxe-private/vmlinuz ip=dhcp boot=casper netboot=url BOOTIF=${bootif} autoinstall url=http://example.com/test-ipxe-private/ubuntu-24.04.3-live-server-amd64.iso
initrd http://example.com/test-ipxe-private/initrd
boot

:shell
shell

1. Activate the private_ipxe_boot feature with an Activate private iPXE Boot feature request as shown in the example below. Replace ex4Mp1E with your server ID.

curl -s -X POST \
  -H "Authorization: Bearer <PAPI token>" \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E/features/private_ipxe_boot/activate" | jq .

2. Send a Reinstall OS for a dedicated server request as shown in the example below. Set operating_system_id to null and include your iPXE script as the ipxe_config string.

curl -s -X POST \
  -H "Authorization: Bearer <PAPI token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "test-ipxe.example.com",
    "operating_system_id": null,
    "ipxe_config": "#!ipxe\nset bootif 01-${internal_iface1_mac}\n\n:menu\nmenu iPXE Boot Menu\nitem ubuntu_24 Ubuntu 24\nitem shell iPXE Shell\nchoose --default ubuntu_24 --timeout 5000 target && goto ${target}\n\n:ubuntu_24\nkernel http://example.com/test-ipxe-private/vmlinuz ip=dhcp boot=casper netboot=url BOOTIF=${bootif} autoinstall url=http://example.com/test-ipxe-private/ubuntu-24.04.3-live-server-amd64.iso\ninitrd http://example.com/test-ipxe-private/initrd\nboot\n\n:shell\nshell",
    "drives": {
      "layout": [
        {
          "slot_positions": [0],
          "ignore": true
        }
      ]
    }
  }' \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E/reinstall" | jq .

3. Check the server status with a Get a dedicated server request as shown below and wait until operational_status returns to normal.

curl -s \
  -H "Authorization: Bearer <PAPI token>" \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E" | jq '{id, title, status, operational_status}'

4. Once reinstall is complete, the server stays in iPXE Boot mode as long as the private_ipxe_boot feature is active.

Updating the iPXE script on a running server (Ubuntu 24)

You can update the iPXE script on a server without re-ordering or reinstalling it. This is the standalone activation flow: update the ipxe_config, then activate the feature, and reboot.

This example updates an existing server to use Private iPXE Boot with the Ubuntu 24 script.

1. Deactivate the currently active iPXE Boot feature with a Deactivate private iPXE Boot feature request as shown in the example below.

curl -s -X POST \
  -H "Authorization: Bearer <PAPI token>" \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E/features/private_ipxe_boot/deactivate" | jq .

2. Update the server's ipxe_config with an Update a dedicated server request as shown in the example below.

curl -s -X PUT \
  -H "Authorization: Bearer <PAPI token>" \
  -H "Content-Type: application/json" \
  -d '{"ipxe_config": "#!ipxe\nset bootif 01-${internal_iface1_mac}\n\n:menu\nmenu iPXE Boot Menu\nitem ubuntu_24 Ubuntu 24\nitem shell iPXE Shell\nchoose --default ubuntu_24 --timeout 5000 target && goto ${target}\n\n:ubuntu_24\nkernel http://example.com/test-ipxe-private/vmlinuz ip=dhcp boot=casper netboot=url BOOTIF=${bootif} autoinstall url=http://example.com/test-ipxe-private/ubuntu-24.04.3-live-server-amd64.iso\ninitrd http://example.com/test-ipxe-private/initrd\nboot\n\n:shell\nshell"}' \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E" | jq .

3. Activate the private_ipxe_boot feature with an Activate private iPXE Boot feature request as shown in the example below.

curl -s -X POST \
  -H "Authorization: Bearer <PAPI token>" \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E/features/private_ipxe_boot/activate" | jq .

4. Reboot the server with a Powercycle a dedicated server request as shown in the example below. The server will boot using the new iPXE script.

curl -s -X POST \
  -H "Authorization: Bearer <PAPI token>" \
  "https://api.servers.com/v1/hosts/dedicated_servers/ex4Mp1E/reboot" | jq .