# How to Use Custom iPXE Install

Cherry Servers provides a wide selection of preconfigured operating system templates, but we understand that there are situations where you may need to deploy an operating system or boot environment that is not available through the standard deployment options. 

Whether you want to install a newer Linux distribution, boot a recovery environment, run hardware diagnostics, or use your own installation workflow, the custom iPXE install feature provides a flexible way to do so. 

Instead of deploying a predefined operating system image, custom iPXE install temporarily boots your dedicated server using an iPXE environment, allowing it to retrieve boot instructions from one of the built-in templates or a custom iPXE script that you provide. This makes it possible to install virtually any operating system or bootable environment that supports network installation.

In this tutorial, you will learn how to configure and use the custom iPXE install feature through the Client Portal, although this guide uses the built-in netboot.xyz template as an example, the same workflow can be used with the other available templates or your own custom iPXE configuration.

## Key Points to Consider:

- Custom iPXE Install is supported on all Cherry Servers dedicated servers, except for Outlet servers, where this feature is not available.
- Built in deployment templates automatically generate an iPXE configuration, which can be customized before starting the deployment.
- This tutorial uses the built-in netboot.xyz template as an example, but you can also use one of the other available templates or provide your own custom iPXE script.
- If you are using a custom iPXE script, ensure it is accessible over HTTP or HTTPS. Please note that some HTTPS certificates may not be recognized by the iPXE firmware.
- During deployment, your server temporarily boots up using an iPXE image, once the operating system installer starts, the temporary boot media is automatically removed.
- Custom iPXE Install is currently available as a beta feature and may receive additional functionality or improvements over time.
- Custom iPXE Install is intended for deploying operating systems that are not available through the standard Cherry Servers deployment templates, as well as recovery environments, diagnostics tools, and custom installation media.

## Instructions to Install Custom OS with iPXE

### Step 1: Select the custom iPXE install deployment method

Custom iPXE install can be used in two different scenarios: when deploying a new dedicated server, or when rebuilding an existing one, both options leads to the same Custom iPXE install configuration page, so the remaining steps in this tutorial apply to either workflow.

1. Use custom iPXE install during a new server deployment
   If you are deploying a new dedicated server, proceed through the server order flow until you reach the operating system selection step. Instead of selecting one of the standard operating system templates, choose "Custom iPXE install", this option allows the new server to boot from an iPXE based installer instead of using a preconfigured operating system image.
   ![](https://www.cherryservers.com/v3/assets/documentation/how-to/ipxe-install/fig1.png)
    _Fig. 1. Selecting Custom iPXE install as the operating system deployment method for a new dedicated server._

2. Use custom iPXE install during a server rebuild

   If you already have a dedicated server and want to reinstall it with a custom operating system, open the server tab in the Cherry Servers Client Portal and start the rebuild process. During the operating system selection step, choose Custom iPXE install, this will let you replace the current operating system with another installer, recovery environment, or any other custom iPXE workflow.
   ![](https://www.cherryservers.com/v3/assets/documentation/how-to/ipxe-install/fig2.png)
    _Fig. 2. Selecting Custom iPXE install as the operating system image during the server rebuild process._

Once Custom iPXE install is selected, you can proceed with configuring the iPXE template or custom script in the next step.

### Step 2: Choose a deployment template

After selecting Custom iPXE Install, the next step is to choose how your server will boot. The "Templates" dropdown provides several deployment options, each designed for a different installation scenario. Depending on the selected template, your server will either boot directly into a specific operating system installer or load another boot environment, such as netboot.xyz.

1. Click the "Templates" dropdown and select the deployment option that best suits your requirements.

   ![](https://www.cherryservers.com/v3/assets/documentation/how-to/ipxe-install/fig3.png)

   _Fig. 3. Available deployment templates for the Custom iPXE Install feature, including built-in operating system installers, netboot.xyz, and Custom chain URL._

2. The available templates behave as follows:

| Template | Description |
|----------|-------------|
| **Netboot** | Boots into the **netboot.xyz** menu, providing access to a large collection of operating system installers, recovery environments, and diagnostic tools. For a complete list of supported operating systems and utilities, refer to the [official netboot.xyz documentation](https://netboot.xyz/docs/). |
| **Ubuntu 24.04** | Boots directly into the Ubuntu 24.04 installer. |
| **Debian 13** | Boots directly into the Debian 13 installer. |
| **AlmaLinux 10** | Boots directly into the AlmaLinux 10 installer. |
| **Alpine Linux 3.20** | Boots directly into the Alpine Linux installer. |
| **Custom chain URL** | Boots using a custom iPXE script hosted at a user defined URL. This option is intended for advanced deployments where you want to maintain your own boot configuration. |

### Step 3: Review and customize the generated iPXE script

After selecting a deployment template, the "Instructions" section is automatically populated with the corresponding iPXE configuration. This script contains the instructions that will be executed when your server boots using the selected template.

1. Review the generated iPXE script to verify that it matches your deployment requirements.

   ![](https://www.cherryservers.com/v3/assets/documentation/how-to/ipxe-install/fig4.png)

   _Fig. 4. The Instructions section displays the generated iPXE configuration for the selected deployment template._

2. If necessary, modify the generated script before starting the deployment. Built in templates can be used without any modifications, however, you are free to customize the generated iPXE configuration to suit your own deployment requirements. This is particularly useful when you need to change boot parameters, kernel arguments, or reference a different installation source.

3. The generated templates also make use of predefined variables, such as `${IP_ADDRESS}`, `${GATEWAY}`, `${NETMASK}`, and `${IFACE}`. These variables are automatically replaced with your servers network configuration during deployment, eliminating the need to manually configure basic networking.

> **Note:** If you selected **Custom chain URL** in the previous step, instead of using one of the built in templates, you can specify the URL of your own iPXE script. The script must be accessible over **HTTP** or **HTTPS**. Please note that some HTTPS certificates may not be recognized by the iPXE firmware. If you experience issues loading the script over HTTPS, try using HTTP instead.

### Step 4: Start the deployment

Once you have reviewed and, if necessary, customized the generated iPXE configuration, you are ready to start the deployment.

1. Click "Pay & Deploy" when provisioning a new server or "Rebuild" if you are reinstalling an existing server.

2. After the deployment starts, your server will automatically reboot and temporarily boot using a dedicated iPXE image. During this process, the generated iPXE configuration is executed, allowing the server to continue with the selected deployment method. Depending on the template you selected, the server will either:
   - boot directly into the corresponding operating system installer;
   - load the netboot.xyz menu, where you can choose from a wide range of operating systems and utilities;
   - execute your custom iPXE Chain URL.

3. Once the selected installer or boot environment has been loaded, open the server console and continue the installation by following the on screen instructions. If you need help accessing the remote console, refer to our [Access the Server Console](https://www.cherryservers.com/knowledge/docs/getting-started/access-the-server-console) guide.

> **Note:** The temporary iPXE boot image is automatically detached 5 minutes after the deployment begins. Once the operating system installer has started, the installation continues normally from the selected installation source without requiring any further interaction from the Client Portal.

## Troubleshooting

If you encounter any issues while using Custom iPXE install, refer to the table below for solutions to the most common problems:

| Issue | Resolution |
|--------|------------|
| **The server does not boot into the selected environment** | Verify that you selected the correct deployment template. If you are using a **Custom chain URL**, ensure that the URL is reachable and points to a valid iPXE script. |
| **The custom iPXE script cannot be loaded** | Ensure that your iPXE script is accessible over **HTTP** or **HTTPS**. If the script fails to load over HTTPS, the certificate may not be recognized by the iPXE firmware, in this case, try using HTTP. |
| **The deployment does not start** | Verify that the server has no other deployment or maintenance tasks in progress. |

If any of the problems persists after completing the recommended checks, please contact **Cherry Servers support** at **support@cherryservers.com** for further assistance.

## Summary

The Custom iPXE install feature provides a flexible way to deploy operating systems, recovery environments, and custom boot environments that are not available through our standard deployment templates. By selecting one of the available deployment templates or providing your own custom iPXE configuration, you can easily provision or rebuild your dedicated server while maintaining full control over the installation process.