Install over the network with iPXE

This guide describes how to install Clear Linux* OS using PXE over the network.


PXE is an industry standard that describes client-server interaction with network-boot software and uses the DHCP and TFTP protocols. This guide shows one method of using the PXE environment to install Clear Linux OS.

The PXE extension called iPXE adds support for additional protocols such as HTTP, iSCSI, AoE, and FCoE. iPXE enables network booting on computers with no built-in PXE support.

To install Clear Linux OS through iPXE, you must create a PXE client. Figure 1 depicts the flow of information between a PXE server and a PXE client.

PXE information flow

Figure 1: PXE information flow.


The Clear Linux OS image that boots through the PXE process automatically erases all data and partitions on the PXE client system and creates 3 new partitions to install onto.


Before booting with iPXE, make the following preparations.

Your PXE client system must meet the requirements to run Clear Linux OS and have a boot order where the network boot option is prioritized before the disk boot option. To determine if your PXE client system meets the minimum requirements for Clear Linux OS, review the Check processor and EFI firmware compatibility.

Connect the PXE server and PXE clients to a switch on a private network, as shown in figure 2.

Network topology

Figure 2: Network topology.

Your PXE server must have:

  • Ethernet/LAN boot option.
  • At least two network adapters.
  • Connection to a public network.
  • Secure boot option disabled.


You must disable the secure boot option in the BIOS because the UEFI binaries used to boot Clear Linux OS are not signed.


To set up Clear Linux OS using iPXE automatically, use the script included with ICIS. For additional instructions on the script, refer to the guide on the ister-cloud-init-svc GitHub* repository.

To set up Clear Linux OS manually, perform the steps below.

  1. Define the variables used for iPXE boot configuration.

  2. Log in and get root privilege.

    sudo -s
  3. Add the pxe-server bundle to your Clear Linux OS system. The bundle contains all files needed to run a PXE server.

    sudo swupd bundle-add pxe-server
  4. Download the latest network-bootable release of Clear Linux OS and extract the files.

    sudo mkdir -p $ipxe_root
    sudo curl -o /tmp/clear-pxe.tar.xz \$(curl \
    sudo tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root
    sudo ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux


    Ensure that the initial ramdisk file is named initrd and the kernel file is named linux, which is a symbolic link to the actual kernel file.

  5. Create an iPXE boot script with the following contents. During an iPXE boot, the iPXE boot script directs the PXE client to download the files to boot and install Clear Linux OS. Use the names previously given to the initial ramdisk and kernel files.

    sudo cat > $ipxe_root/ipxe_boot_script.ipxe << EOF
    kernel linux quiet init=/usr/lib/systemd/systemd-bootchart \
    initcall_debug tsc=reliable no_timer_check noreplace-smp rw \
    initrd initrd
  6. The pxe-server bundle contains a lightweight web-server known as nginx. Create a configuration file for nginx to serve Clear Linux OS to PXE clients with the following contents:

    sudo mkdir -p /etc/nginx/conf.d
    sudo cat > /etc/nginx/conf.d/$ipxe_app_name.conf << EOF
    server {
      listen $ipxe_port;
      server_name localhost;
      location /$ipxe_app_name/ {
        root $web_root;
        autoindex on;
    sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf


    Create a separate nginx configuration file to serve network-bootable images on a non-standard port number. This action saves existing nginx configurations.

  7. Start nginx and enable the startup on boot option.

    sudo systemctl start nginx
    sudo systemctl enable nginx
  8. The pxe-server bundle contains a lightweight DNS server which conflicts with the DNS stub listener provided in systemd-resolved. Disable the DNS stub listener and temporarily stop systemd-resolved.

    sudo mkdir -p /etc/systemd
    sudo cat > /etc/systemd/resolved.conf << EOF
    sudo systemctl stop systemd-resolved
  9. Assign a static IP address to the network adapter for the private network and restart systemd-networkd with the following commands:

    sudo mkdir -p /etc/systemd/network
    sudo cat > /etc/systemd/network/ << EOF
    sudo systemctl restart systemd-networkd
  10. Configure NAT to route traffic from the private network to the public network. This action makes the PXE server act as a router. To make these changes persistent during reboots, save the changes to the firewall with the following commands:

    sudo iptables -t nat -F POSTROUTING
    sudo iptables -t nat -A POSTROUTING -o $external_iface -j MASQUERADE
    sudo systemctl enable iptables-save.service
    sudo systemctl restart iptables-save.service
    sudo systemctl enable iptables-restore.service
    sudo systemctl restart iptables-restore.service


    The firewall masks packets to make them appear as coming from the PXE server and hides PXE clients from the public network.

  11. Configure the kernel to forward network packets to different interfaces. Otherwise, NAT will not work.

    sudo mkdir -p /etc/sysctl.d
    sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf
    sudo echo 1 > /proc/sys/net/ipv4/ip_forward
  12. The pxe-server bundle contains iPXE firmware images that allow computers without an iPXE implementation to perform an iPXE boot. Create a TFTP hosting directory and populate the directory with the iPXE firmware images with the following commands:

    sudo mkdir -p $tftp_root
    sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe
  13. The pxe-server bundle contains a lightweight TFTP, DNS, and DHCP server known as dnsmasq. Create a configuration file for dnsmasq to listen on a dedicated IP address for those functions. PXE clients on the private network will use this IP address.

    sudo cat > /etc/dnsmasq.conf << EOF
  14. Add the options to serve iPXE firmware images to PXE clients over TFTP to the dnsmasq configuration file.

    sudo cat >> /etc/dnsmasq.conf << EOF
  15. Add the options to host a DHCP server for PXE clients to the dnsmasq configuration file.

    sudo cat >> /etc/dnsmasq.conf << EOF

    The configuration provides the following important functions:

    • Directs PXE clients without an iPXE implementation to the TFTP server to acquire architecture-specific iPXE firmware images that allow them to perform an iPXE boot.
    • Activates only on the network adapter that has an IP address on the defined subnet.
    • Directs PXE clients to the DNS server.
    • Directs PXE clients to the PXE server for routing via NAT.
    • Divides the private network into two pools of IP addresses. One pool is for network boot and one pool is used after boot. Each pool has their own lease times.
  16. Create a file for dnsmasq to record the IP addresses it provides to PXE clients.

    sudo mkdir -p /var/db
    sudo touch /var/db/dnsmasq.leases
  17. Start dnsmasq and enable startup on boot.

    sudo systemctl enable dnsmasq
    sudo systemctl restart dnsmasq
  18. Start systemd-resolved.

    sudo systemctl start systemd-resolved


    systemd-resolved dynamically updates the list of DNS servers for the private network if you use the dnsmasq DNS server. The setup creates a pass-through DNS server that relies on the DNS servers listed in /etc/resolv.conf.

  19. Power on the PXE client and watch the client boot and install Clear Linux OS.

    After booting, Clear Linux OS automatically partitions the hard drive, installs itself, updates to the latest version, and reboots.

Congratulations! You have successfully installed and configured a PXE server that enables PXE clients to boot and install Clear Linux OS over the network.