This guide describes how to install Clear Linux* using PXE.

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.

Caution

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.

Prerequisites

Before booting with iPXE, make the following preparations.

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 client must have a boot order where the network boot option is prioritized before the disk boot option.

Your PXE server must have:

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

Note

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

Configuration

To set up Clear Linux OS using iPXE automatically, use the configure-ipxe.sh script included with ICIS. For additional instructions on the script, refer to the guide on the ICIS GitHub repository.

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

  1. Define the variables used for iPXE boot configuration.

    ipxe_app_name=ipxe
    ipxe_port=50000
    web_root=/var/www
    ipxe_root=$web_root/$ipxe_app_name
    tftp_root=/srv/tftp
    external_iface=eno1
    internal_iface=eno2
    pxe_subnet=192.168.1
    pxe_internal_ip=$pxe_subnet.1
    pxe_subnet_mask_ip=255.255.255.0
    pxe_subnet_bitmask=16
    
  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 \
      https://download.clearlinux.org/current/clear-$(curl \
      https://download.clearlinux.org/latest)-pxe.tar.xz
    sudo tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root
    sudo ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux
    

    Note

    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
    sudo!ipxe
    kernel linux quiet init=/usr/lib/systemd/systemd-bootchart \
    initcall_debug tsc=reliable no_timer_check noreplace-smp rw \
    initrd=initrd
    initrd initrd
    boot
    EOF
    
  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;
      }
    }
    EOF
    
    sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
    

    Note

    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
    [Resolve]
    DNSStubListener=no
    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/70-internal-static.network << EOF
    [Match]
    Name=$internal_iface
    [Network]
    DHCP=no
    Address=$pxe_internal_ip/$pxe_subnet_bitmask
    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
    

    Note

    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
    listen-address=$pxe_internal_ip
    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
    enable-tftp
    tftp-root=$tftp_root
    EOF
    
  15. Add the options to host a DHCP server for PXE clients to the dnsmasq configuration file.

    sudo cat >> /etc/dnsmasq.conf << EOF
    dhcp-leasefile=/var/db/dnsmasq.leases
    
    dhcp-authoritative
    dhcp-option=option:router,$pxe_internal_ip
    dhcp-option=option:dns-server,$pxe_internal_ip
    
    dhcp-match=set:pxeclient,60,PXEClient*
    dhcp-range=tag:pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,15m
    dhcp-range=tag:!pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,6h
    
    dhcp-match=set:ipxeboot,175
    dhcp-boot=tag:ipxeboot,http://$pxe_internal_ip:$ipxe_port/$ipxe_app_name/ipxe_boot_script.ipxe
    dhcp-boot=tag:!ipxeboot,undionly.kpxe,$pxe_internal_ip
    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
    

    Note

    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.