Custom iPXE booting

For advanced usage, you can boot any image by providing your own iPXE script.

When you request a server and want to boot a custom image into memory, you can use the custom iPXE boot option.

Prerequisites:

• you must have knowledge of the [bare metal] iPXE boot mechanism

• you must host your own iPXE script

• you must host your own PXE boot images or point to boot images hosted on the internet

• you must ensure your server can access the images you point to

The iPXE boot process

When your server boots up during the delivery process, it will go through its iPXE boot stage. This will load a configuration file - the iPXE script - which tells the server what image to boot.

Within the iPXE script you can point to your kernel and initrd images, to be downloaded from a location on the internet.

#!ipxe
set bootimage_url https://example.org
kernel ${bootimage_url}/custom_os.vmlinuz ${os_parameters}
initrd ${bootimage_url}/custom_os.initrd
boot

The exact names of these images depend on which OS you want to boot into memory.

Booting PXE images is not to be confused with booting a VM image or iso, which are a different type of image.

The kernel parameter takes the URL to the kernel image and kernel parameters. In the case of Linux, there are a lot of parameters you can utilize to instruct the kernel how to boot. Normally you only need a few. It's best to check the documentation of the OS you are booting for which to use.

It is often best to pass the net.ifnames=0 kernel parameter, to use legacy network interface names, e.g. eth0, eth1.

iPXE network variables

Custom iPXE booting will occur in your own VLAN and network space. i3D does not provide a DHCP server in your VLAN, so unless you host your own DHCP server, you must pass a static network configuration to your OS when booting.

Within your custom iPXE script, you can use your server's public network configuration for the initial boot phase of the OS. We provide a number of iPXE variables to use for this purpose:

IPXE_BOOT_HOSTNAME = hostname.example.com
IPXE_BOOT_DNS1 = 5.200.5.5
IPXE_BOOT_DNS2 = 5.200.5.200
IPXE_BOOT_IF = eth0
IPXE_BOOT_IF_LOGICAL_NAME = eno1
IPXE_BOOT_IF_MAC = aa:bb:cc:dd:ee:ff
IPXE_BOOT_IP = 1.2.3.4
IPXE_BOOT_GATEWAY = 1.2.3.1
IPXE_BOOT_NETMASK = 255.255.255.0
IPXE_BOOT_CIDR = /24
IPXE_BOOT_LINUX_IP_CONFIG = ip=1.2.3.4::1.2.3.1:255.255.255.0:hostname.example.com:eth0:none:5.200.5.5:5.200.5.200

The variable IPXE_BOOT_LINUX_IP_CONFIG is a convenience one which can be used for basic network configuration of a Linux OS. It contains the IP, Netmask, Gateway, Host name, Interface and DNS. you can of course construct your own using the individual variables.

Example custom iPXE script

This example will boot a Flatcar Linux image with the network configured:

#!ipxe

set bootimage_url https://lts.release.flatcar-linux.net/amd64-usr/current
set os_parameters initrd=flatcar_production_pxe_image.cpio.gz flatcar.first_boot=1 ignition.config.url=https://example.org/ignition-configuration.ign flatcar.autologin net.ifnames=0 ${IPXE_BOOT_LINUX_IP_CONFIG}

kernel ${bootimage_url}/flatcar_production_pxe.vmlinuz ${os_parameters}
initrd ${bootimage_url}/flatcar_production_pxe_image.cpio.gz

boot

We use the ${IPXE_BOOT_LINUX_IP_CONFIG} variable to configure the network of Flatcar during its initial boot phase. Note the parameter net.ifnames=0 to instruct Linux to use classic interface names, e.g. eth0, eth1. During that phase, the ignition.confiug.url file will be downloaded which contains further directives on how to configure Flatcar. The details of which are outside of the scope of this document though.

You must host this file somewhere so we can download it during the iPXE boot phase. You can provide the url to the iPXE script when requesting a server. See below.

Requesting a server with a custom iPXE script

When you request a new FlexMetal server via the API, you can select the custom-ipxe OS, accompanied by the ipxeScriptUrl property where you provide the URL to your custom iPXE script:

{
  "name": "server.example.org",
  "location": "EU: Rotterdam",
  "instanceType": "bm7.std.8",
  "os": {
    "slug": "custom-ipxe",
    "ipxeScriptUrl": "https://example.org/custom_ipxe.cfg"
  },
  "postInstallScript": "",
  "sshKey": [],
  "tags": [
    "a-tag"
  ]
}

FlexMetal publishes any provided SSH keys and tags in the metadata API, which you can consume from the OS.

Logging into the booted OS depends on the authentication method of the image. It may or may not require a password, you can insert SSH keys in the image itself, or any authentication method the image requires or how you have customized an image of your own.

When requesting a FlexMetal server with the custom-ipxe OS, the delivered state will be set as soon as the iPXE boot script is downloaded. This means that the OS images must still be downloaded and the OS needs to start up and come online.

Configuration of a booted image

Pre-boot configuration

To give the OS that you are booting an initial network configuration, you must pass the network details to your OS' kernel parameters as described in the example above.

OS configuration using Metadata

Once fully booted, your OS must be properly configured. During the initial OS boot phase, your image can request full server configuration settings via the Metadata API.