Skip to content
MatthiesenXYZ MatthiesenXYZ
Docs
Blog

Netboot.xyz - My Journey to Network Booting with Open Source

Powered by Ghost
Adam Matthiesen
Adam Matthiesen
Owner & Operator of Matthiesen.xyz - Also the Core Developer of the Projects we maintain
netbootxyz

Table of Contents
Introduction
Getting Started (Docker, The Easy Way)
Router Config (Default Boot file Options)
Booting other operating systems, Editing the Menu
Sources

Introduction

This post is about my exploration into how to Netboot using Netboot.xyz, but as I quickly realized, Netboot.xyz is not as simple as it first seems. Its based on ipxe.org's codebase and technology. In fact, most of the resources on ipxe.org are directly relevent in Netbootxyz, from menu options and formating, to the way you boot operating systems. The Documentation at the ipxe website helped me learn more about the process of how network booting with ipxe really worked, as well as they provide examples of how to utilize their software. Which the reason I learned about them in the first place was after I first deployed Netboot.xyz for the first time and attempted a network boot, and before netboot.xyz launched there was the website for ipxe.org! My first deployment was using docker, which worked quite well.

Because there are a ton of types of routers, in this post I will not be explaininng how to setup your router for network booting. But a simple google search should be able to help you figure that out, as there are many ways to setup a network boot environment. Including offloading your DHCP server to allow different options outside of some routers functions. Again far out of the scope of this post.

Getting Started (Docker, The Easy Way)

Since I utilize Portainer, I created a docker stack. The Following is my the Docker Compose default script. You could also use this for a docker-compose.yml

docker-compose.yml
1
---
2
version: "2.1"
3
services:
4
  netbootxyz:
5
    image: ghcr.io/netbootxyz/netbootxyz
6
    container_name: netbootxyz
7
    environment:
8
      - MENU_VERSION=2.0.47 # optional
9
    volumes:
10
      - /path/to/config:/config # This is where you want to keep your configs, Highly recomended if you want to edit menus like I did.
11
      - /path/to/assets:/assets # This is for HTML based assets from the webserver hosted from port 8080
12
    ports:
13
      - 3000:3000 #WEB-GUI
14
      - 69:69/udp #TFTP
15
      - 8080:80 #HTTP
16
    restart: unless-stopped

If you want to use the Docker-CLI you can use the code below

docker run -d \
  --name=netbootxyz \
  -e MENU_VERSION=2.0.59             `# optional` \
  -p 3000:3000                       `# sets webapp port` \
  -p 69:69/udp                       `# sets tftp port` \
  -p 8080:80                         `# sets http port` \
  -v /local/path/to/config:/config   `# optional` \
  -v /local/path/to/assets:/assets   `# optional` \
  --restart unless-stopped \
  ghcr.io/netbootxyz/netbootxyz

Router Config (Default Boot file Options)

Do to the nature of Router technology there is no magic instructions that covers all routers. Below are the Boot files as well as an example configuration that will work with routers that support this feature. I use a Unifi UDM-Pro but since that is not the only router technology out there I will not be going through how to configure your router. (There is also plenty of documentation online that can/will help you)

Example Router entry

  • NextServer/TFTP/Netboot: docker-host
  • File: ipxe/netboot.xyz.efi

Default file values

Bootfile Name Description
netboot.xyz.kpxe Legacy DHCP boot image file, uses built-in iPXE NIC drivers
netboot.xyz-undionly.kpxe Legacy DHCP boot image file, use if you have NIC issues
netboot.xyz.efi UEFI boot image file, uses built-in UEFI NIC drivers
netboot.xyz-snp.efi UEFI w/ Simple Network Protocol, attempts to boot all net devices
netboot.xyz-snponly.efi UEFI w/ Simple Network Protocol, only boots from device chained from
netboot.xyz-arm64.efi DHCP EFI boot image file, uses built-in iPXE NIC drivers
netboot.xyz-arm64-snp.efi UEFI w/ Simple Network Protocol, attempts to boot all net devices
netboot.xyz-arm64-snponly.efi UEFI w/ Simple Network Protocol, only boots from device chained from
netboot.xyz-rpi4-snp.efi UEFI for Raspberry Pi 4, attempts to boot all net devices

Booting other operating systems, Editing the Menu

So when I first started trying this i got extremly confused by Netboot.xyz's example by booting WinPE. But Moddern versions of windows installers already include a perfectly usable WinPE that I was able to use, now in some circumstances you may need to build a WinPE with Custom drivers.

Below is my modification of config/menus/menu.ipxe

There is two ways to edit this file... you could log-in to the Web-GUI http://docker-host:3000 or, you could edit the physical /local/path/to/config you linked in the docker startup above. This part REQUIRES you to configure volume binds in order to configure and save between reboots.

Menu Section (Line 43)

menu_line43.ipxe
1
### Installers:
2
item --gap Installers:
3
#item mdt-wim ${space} Windows Deployment x64 (MDT-wim)
4
item win10ltsc ${space} Windows 10 Enterprise LTSC 22h2 x64 (net-iso)
5
item win1062023 ${space} Windows 10 June 2023 x64 (net-iso)
6
### Tools
7
item --gap Tools:
8
item macrium11 ${space} Macrium Reflect Win11 (net-iso)

item selection (Under :verify_sigs)

menu_verify_sigs.ipxe
1
###Installers
2


3
#:mdt-wim
4
#kernel wimboot
5
#initrd http://<IP>:<PORT>/wim-boot/MDT/ipxe/install.bat  install.bat
6
#initrd http://<IP>:<PORT>/wim-boot/MDT/ipxe/winpeshl.ini winpeshl.ini
7
#initrd http://<IP>:<PORT>/wim-boot/MDT/Boot/BCD          BCD
8
#initrd http://<IP>:<PORT>/wim-boot/MDT/Boot/boot.sdi     boot.sdi
9
#initrd http://<IP>:<PORT>/wim-boot/MDT/boot.wim          boot.wim
10
#boot || goto main_menu
11


12
:win10ltsc
13
kernel wimboot
14
initrd http://<IP>:<PORT>/wim-boot/Win10LTSC22h2/ipxe/install.bat  install.bat
15
initrd http://<IP>:<PORT>/wim-boot/Win10LTSC22h2/ipxe/winpeshl.ini winpeshl.ini
16
initrd http://<IP>:<PORT>/wim-boot/Win10LTSC22h2/boot/bcd          BCD
17
initrd http://<IP>:<PORT>/wim-boot/Win10LTSC22h2/boot/boot.sdi     boot.sdi
18
initrd http://<IP>:<PORT>/wim-boot/Win10LTSC22h2/sources/boot.wim  boot.wim
19
boot || goto main_menu
20


21
:win1062023
22
kernel wimboot
23
initrd http://<IP>:<PORT>/wim-boot/Win10_6-2023/ipxe/install.bat  install.bat
24
initrd http://<IP>:<PORT>/wim-boot/Win10_6-2023/ipxe/winpeshl.ini winpeshl.ini
25
initrd http://<IP>:<PORT>/wim-boot/Win10_6-2023/boot/bcd          BCD
26
initrd http://<IP>:<PORT>/wim-boot/Win10_6-2023/boot/boot.sdi     boot.sdi
27
initrd http://<IP>:<PORT>/wim-boot/Win10_6-2023/sources/boot.wim  boot.wim
28
boot || goto main_menu
29


30
###Tools
31


32
:macrium11
33
kernel wimboot
34
initrd http://<IP>:<PORT>/wim-boot/macrium/w11/Boot/BCD          BCD
35
initrd http://<IP>:<PORT>/wim-boot/macrium/w11/Boot/boot.sdi     boot.sdi
36
initrd http://<IP>:<PORT>/wim-boot/macrium/w11/sources/boot.wim  boot.wim
37
boot || goto main_menu

The install.bat files are identical for each directory, containing the following (Username and password depend on your setup. In my case I hosted the files on my NAS.)

install.bat
1
wpeinit
2
net use F: \\<IP>\<SHARE>\wim-boot\<OS Source Files> /user:<User> <Pass>
3
F:\setup.exe

The winpeshl.ini file are also identical for each directoy, containing the following

winpeshl.ini
1
[LaunchApps]
2
"install.bat"

The Files for the Windows Installers are from Offical Windows ISO files. Just extracted to a network storage. Then you copy the boot files listed above to the Assets folder in the docker container.

I Have MDT commented out due to some issues I was having with it, it worked at one point but then suddenly stopped working... It may work for you but it also may not. its just there for reference. As for booting Linux I just left the rest of Netboot.xyz's Menu in tact, and it works perfectly!

Sources