Skip to content

Custom iPXE

Equinix Metalâ„¢ supports passing custom iPXE scripts during provisioning, which allows you to install a custom operating system manually. When you provision a server, Equinix Metal first loads a custom iPXE build that will serve up the chain-loaded iPXE script URL that you specify.

Provisioning with Custom iPXE

To provision an On Demand server with custom iPXE using the Equinix Metal console, select Custom iPXE from the options under Select an Operating System. If you have your iPXE script hosted at a publicly accessible http(s) location, put the URL to your script in the text field.

Toggle the switch to set your server to persistently boot from iPXE if you need to. Should the server fail during iPXE boot, you can edit your iPXE URL and reboot the server to try again.

Alternatively, you can leave the field blank and pass the contents of your iPXE script into User Data field (under Optional Settings) with the #!ipxe hashbang.


chain -ar

Click Deploy Now to provision your server.

Provisioning Custom iPXE in the API

If you are using the Equinix Metal API to provision servers, you can use Custom iPXE by passing the URL in to the ipxe_script_url field in the body of your request.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"{id}/devices" \
-d '{
    "facility": "<facility_code>",
    "plan": "<server_type>",
    "operating_system": "<os_code>",
    "always_pxe": true,
    "ipxe_script_url": ""

Initial Boot

After serving up iPXE via DHCP, the device will be marked as active in our API and portal. Since the server is sitting on the boot loader and it has no SSH access, use the Equinix Metal Out-of-Band Console to access the server

ssh {server-uuid}@sos.{facility-code}

If you would like to interact with your device via S.O.S. to perform a manual install and are not using, our x86 servers require console=ttyS1,115200n8, and our aarch64 servers require console=ttyAMA0,115200.

DHCP is available during a Custom iPXE device's entire life, so you can get network configuration via DHCP and then setup networking statically in the OS by discovering the IP address information from the metadata service. From the host server, run curl

If something is wrong and you are unable to access your server, use the Edit Instance Details in the server Overview. You can change your iPXE behavior on boot, edit your iPXE script, and then reboot the server with the new configuration.


If you're using to manually install your operating system, connect to the Equinix Metal Out-of-Band Console for the menu of OS options.


      Boot from local hdd                                               (283)
      Linux Network Installs
      Live CDs
      BSD Installs
      Unix Network Installs
      Architecture: x86_64 (64bit)
      iPXE shell
      Network card info
      PCI Device List
   Signature Checks: [ enabled: true ]

Information about the operating systems that are available through is in their GitHub Readme.

If you want to install an operating system that is not listed, and it's distributed with an ISO, you can install it by selecting the iPXE shell option and entering the commands:

kernel iso raw
initrd http://url/to/iso

Be aware that the docs mention that it is possible (likely) that installation will fail. If it fails during initramfs trying to load the CD device, update the install media to look for install media on the memdisk. More information about this issue can be found in a article.

packet-cli with

packet-cli device create \
  --hostname netboot-custom-ipxe \
  --plan c3.small.x86 \
  --facility any \
  --operating-system custom_ipxe \
  --project-id "$METAL_PROJECT" \
chain -ar'

Persisting PXE

When provisioning the Custom iPXE kicks off, the next boot option is to PXE on first boot. By default, this PXE process only happens once on the first boot. To set your device to continuously boot to iPXE first, use the toggle under Custom iPXE Settings or when provisioning, or from Server Actions or Edit Instance Details after provisioning.

If true, PXE will persist as the first boot option past initial provisioning reboots. This is great for testing your iPXE provisioning script and lays the foundation for future, "always-pxe-based OS's" on Equinix Metal.