The Hivelocity Bare Metal Cloud supports custom iPXE scripts to install a custom operating system at time of provisioning. By providing a publicly accessible iPXE script when you provision a server, Hivelocity will load your custom iPXE build for that server.

Provisioning with Custom iPXE

You can provision any server with custom iPXE from the bare-metal-device API by selecting the Custom iPXE option as your operating system. You then have the two choices for how to provide your iPXE script

• Self hosted: Serving your script from a publically accessible URL and providing the link at provision time.
• Provided at Runtime: Providing the contents of your iPXE script directly at provision time.

You can use Custom iPXE by passing the URL in to the custom_ipxe_script_url field in the body of your request to /bare-metal-devices.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
    -d '{ \
        "productId": 576, \
        "locationName": "NYC1", \
        "osName": "CentOS 7.x", \
        "hostname": "your.hostname.com", \
        "period": "hourly" \
        "custom_ipxe_script_url": "http://boot.yourcompany.com/ipxe-script"
    }' \
https://core.hivelocity.net/api/v2/bare-metal-devices

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
    -d '{ \
        "productId": 576, \
        "locationName": "NYC1", \
        "osName": "Custom iPXE", \
        "hostname": "your.hostname.com", \
        "period": "monthly" \
        "custom_ipxe_script_url": "#!ipxe\nkernel http://pxe-http.hivelocity.net/sysresqcd9/sysresccd/boot/x86_64/vmlinuz nofirewall ip=dhcp archisobasedir=sysresccd archiso_http_srv=http://pxe-http.hivelocity.net/sysresqcd9/ setkmap=us ar_nodel ar_source=http://pxe-http.hivelocity.net/example_autorun/finish_provision \"hv_sps_metadata_url={metadata_url}\"\ninitrd http://pxe-http.hivelocity.net/sysresqcd9/sysresccd/boot/x86_64/sysresccd.img\nboot"
    }' \
https://core.hivelocity.net/api/v2/bare-metal-devices

🚧

Be sure to call the finish url from the Hivelocity Metadata in your iPXE script

In order to access your device after provisioning you must include execute the provisioning finished request provided by the Hivelocity metadata in your iPXE script. How to do this is documented further down in the metadata section.

📘

Blocked IPXE scripts will not execute forever

If your IPXE script calls out to external resources, or is blocking in some way, our system will kill your IPXE deployment after long periods of inactivity. This will cause your device to drop into it's default boot order item.

So make sure your IPXE script doesn't block indefinitely.

Debugging iPXE scripts

On initial boot, the server is running the bootloader and has no SSH access. If you wish to access your device during provisioning you will need to connect to the IPMI Console.

If you experience errors with your script, or are unable to access your server, the easiest method to retest your script is to run a reload with your corrected iPXE script. See the reloading section below for details.

📘

Hourly billing starts a provisioning

Hourly billing periods begin the moment the server provisions, rather than when the operating system is done installing. This means that you will be billed for the time it takes for your IPXE script to execute. Therefore, It is recommended you test your scripts before performing large-scale deployments.

Reloading

If you're prototyping or troubleshooting your iPXE script, you'll probably want to frequently reboot and test your script. We allow reloads to be triggered during provisioning due to this common scenario. To reload, power off the device then perform a reload. This is done with a request to the PUT /bare-metal-device endpoint. The server will reboot and use the newly provided iPXE script. As long as an iPXE script is provided the device will provision using it, regardless if it has changed or not.

View this recipe for an example:

Metadata

All custom iPXE scripts used on the Hivelocity platform must include the Hivelocity metadata URL. This url is needed to complete the provisioning and make your server accessible. You can also use this url to request information about the device, its IPs, ports, and more to further configure your OS.

The url is injected via string interpolation after your submit your script for provisioning. The injected variables are list below:

🚧

Note the difference between iPXE variables and Hivelocity-provided variables!

Variables that start with $ are iPXE settings that iPXE itself injects at boot time. For a reference of all iPXE-provided variables, refer to the iPXE documentation
Variables without $ like {metadata} are injected before handing over your script to iPXE.
In the event the {var} form conflicts with your iPXE provisioning flow, ${metadata_url} is
also provided as an iPXE variable.

Typically, you will want to store the metadata_url in the kernel arguments of your iPXE script using the placeholder {metadata_url}.

For example:

...
kernel http://some.website/vmlinuz nofirewall ip=dhcp hv_url={metadata_url}
...

This makes the metadata URL available in /proc/cmdline for the rest of your provision where you will want to make a GET request to that url.

Getting metadata

When kickstarting your image you will want to make a GET request to the injected metadata_url. Here is an example:

#! /bin/sh
echo ">> Grabbing Hivelocity metadata"
metadata_url=$(grep -oP 'hv_url=\K([^\s"]+)' /proc/cmdline)
curl "$metadata_url" -o metadata.json

This endpoint will return the following data about your device. You can use this information to further configure your OS as necessary:

{
  "osName": "Custom iPXE",
  "finishHook": {
    "url": "https://core.hivelocity.net/api/v2/sps/finish?buildId=ABC123&deviceId=123456",
    "method": "POST",
    "curl": "curl -XPOST https://core.hivelocity.net/api/v2/sps/finish?buildId=ABC123&deviceId=123456"
  },
  "interfaces": {
    "public": {
      "subnet": "12.34.56.248/29",
      "gateway": "12.34.56.249",
      "netmask": "255.255.255.248",
      "full": "12.34.56.250/29",
      "ip": "12.34.56.250",
      "network": "12.34.56.248"
    }
  },
  "productName": "E-2278G 3.4GHz Coffee Lake",
  "productId": 576,
  "hostname": "your.hostname.com",
  "is_bonded": false
}

Finishing provisioning

Once you have retrieved the custom metadata above, to finish provisioning make a POST request to the finishHook. The curl command is provided to you for convenience. For example:

curl -X POST <https://core.hivelocity.net/api/v2/sps/finish?buildID=ABC123&deviceId=123456>
Calling this url will immediately make your device available for access. If you forget to call this url, or it fails, your device will become available 3 hours after the start of provisioning.