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

Console

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.

When you click Deploy Now to provision your server, it will provision from your iPXE URL.

CLI

metal device create \
--hostname netboot-custom-ipxe \
--plan c3.small.x86 \
--metro sv \
--operating-system custom_ipxe \
--project-id "$METAL_PROJECT" \
--ipxe-script-url "https://boot.netboot.xyz/"

API

If you are using the Equinix Metal API to provision servers, you can use Custom iPXE by passing in "custom_ipxe" for the "operating_system" and 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>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "metro": "<metro_code>",
    "plan": "<server_type>",
    "operating_system": "custom_ipxe",
    "always_pxe": true,
    "ipxe_script_url": "https://boot.netboot.xyz/"
}'

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.

Note: if you are using the OOB console to perform a manual install and are not using netboot.xyz, 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 https://metadata.platformequinix.com/metadata.

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.

Using netboot.xyz Example

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

                                  netboot.xyz

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

Information about the operating systems that are available through netboot.xyz 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 https://boot.netboot.xyz/memdisk iso raw
initrd http://url/to/iso
boot

Be aware that the netboot.xyz 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 reversengineered.com article.

metal CLI with Netboot.xyz

metal device create \
  --hostname netboot-custom-ipxe \
  --plan c3.small.x86 \
  --metro sv \
  --operating-system custom_ipxe \
  --project-id "$METAL_PROJECT" \
  --userdata='#!ipxe
chain -ar https://boot.netboot.xyz'

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.