# netboot.xyz — Full Documentation > netboot.xyz lets you PXE boot various operating system installers and utilities from a single tool over the network using iPXE. Boot Linux, BSD, Windows, and dozens of live CDs from one lightweight menu — no physical media required. This file concatenates the full text of the netboot.xyz documentation for AI/LLM use. The curated index is at https://netboot.xyz/llms.txt. --- # Introduction Source: https://netboot.xyz/docs [netboot.xyz](https://netboot.xyz) lets you [PXE](https://en.wikipedia.org/wiki/Preboot_Execution_Environment) boot various operating system installers or utilities from a single tool over the network. This lets you use one media for many types of operating systems or tools. The [iPXE](https://ipxe.org/) project is used to provide a user friendly menu from within the BIOS that lets you easily choose the operating system you want along with any specific types of versions or bootable flags. You can remote attach the ISO to servers, set it up as a rescue option in Grub, or even set up your home network to boot to it by default so that it's always available. Try it below — this is a live, interactive demo of the iPXE menu. Click it, then navigate with the arrow keys, Enter to select and Esc to go back. The boot sequence is simulated; nothing is actually downloaded or booted. ## Menu Overview ### Linux Network Installs Menu For Operating System projects that provide a network bootable installer, this is a lightweight method for installation as it retrieves a minimal set of installer kernels and then installs packages as needed. This is typically the faster method of OS installation as it provides just enough installer to get you running and then downloads only the packages needed. You can also leverage built in tools for doing rescue boots too. ### Live CD/Distro Menu Many Operating System projects provide their software as an ISO only or provide a Live CD/DVD that you can download and boot into memory without modifying the storage of the machine. Typically you then have the option to do an install from the live system. These are typically heavier weight installs and can take a lot of bandwidth to install. iPXE generally does not boot the ISOs directly that well. In order for us to make it easy to consume those types of images, we monitor new version updates from upstream, retrieve the releases, extract them, and re-release them with modifications to the initrd as needed to make them iPXE friendly. We then can load the smaller size kernel directly into memory for a better and more consistent experience. ### Utilities Menu The Utilities menu provides access to tools and utilities for tools like disk cloning, drive wiping, or other rescue type of tooling. You can also select other netboot.xyz endpoints to test menus that may be in development. ## Supported Architectures netboot.xyz supports x86 (both 32-bit and 64-bit) as well as arm64 architectures. Both Legacy and UEFI BIOS modes are supported. The menus identify the platform loaded and enable menu options based on the architecture loaded. ## Getting Started - [Quick Start](./quick-start.md) — download a bootloader and get booting in minutes - [Boot from USB](./booting/usb.md) — write a netboot.xyz image to a USB drive - [Boot from TFTP](./booting/tftp.md) — set up PXE booting on your local network - [Self Hosting](./selfhosting.md) — run your own netboot.xyz server with Docker or Ansible - [FAQ](./faq.md) — common questions answered --- # Boot from iPXE Source: https://netboot.xyz/docs/booting/ipxe ### NIC with Embedded iPXE If you've already compiled your own iPXE, you can load up the netboot.xyz menu easily by entering CTRL-B when prompted, setting DHCP and then chainloading iPXE: ```bash dhcp chain --autofree https://boot.netboot.xyz ``` If you don't have DHCP on your network, you can manually set your network information: ```bash set net0/ip set net0/netmask set net0/gateway set dns ifopen net0 chain --autofree https://boot.netboot.xyz ``` Some iPXE builds do not support HTTPS connections. If you get an "Operation not supported" error message, run this instead: ```bash chain --autofree http://boot.netboot.xyz ``` ### KVM On VPSes that use KVM, you can usually connect to the VPS via VNC, reboot it, press escape while rebooting to get a boot menu, then select the iPXE option. Once iPXE has started, press Ctrl-B and follow the instructions above. --- # Boot from ISO Source: https://netboot.xyz/docs/booting/iso ### Burning a CD/DVD To create a bootable CD-ROM/DVD, burn the ISO image [netboot.xyz.iso](https://boot.netboot.xyz/ipxe/netboot.xyz.iso) to a blank CD-ROM/DVD. Insert the media into the server, set the proper boot order and boot up. ### Virtual Machine Software You can also use these ISOs to boot any sort of VM in Citrix XenServer, Proxmox VE, VMware ESXi, VMware Fusion, VirtualBox. ### Out of Band Virtual Media The netboot.xyz ISO can be attached to remote virtual media of a server like the Dell DRAC or HP iLOs. Because the iPXE boot disk is so light weight, it is great for starting installations where there might be really low bandwidth as it will only stream the files needed for the installation. ### USB Bootable Virtual Media If you need to store a collection of ISOs, including netboot.xyz, on a single USB drive, there are some recommended devices that work well with netboot.xyz. You can copy multiple ISOs to the drive and mount them as a Virtual Disk during the boot process. This is useful not only for using netboot.xyz but also for other ISOs like Windows, Proxmox, or other media. It is a great way to have a portable collection of bootable media always ready to go! ![iodd-st400.png](../../static/img/iodd-st400.png) Recommended tools include: * [IODD ST400](https://amzn.to/42vm2By) * [IODD Mini USB 3.0 256-bit Secure Encrypted SSD Drive](https://amzn.to/4haXpOZ) --- # QEMU Source: https://netboot.xyz/docs/booting/qemu ### Overview A quick way to try out netboot.xyz without any modifications to your existing environment is to leverage QEMU. You can start up a virtual machine to evaluate what netboot.xyz is and how it works. You will need the qemu-system package for your appropriate operating system and a window manager installed. In the example below we are using Ubuntu 20.04. ### Install dependencies ```bash # install the qemu-system package sudo apt-get install -y qemu-system ovmf # download the latest combined Legacy and EFI iso wget https://boot.netboot.xyz/ipxe/netboot.xyz.iso ``` If you want to write to a disk, you can set one at this point, or optionally you can boot without a disk if you want to test drive netboot.xyz: ### Create a disk (optional) ```bash qemu-img create -f raw vmdisk 8G # add the following to end of the qemu-system lines below if you want to add a disk to write to: # -drive file=vmdisk,format=raw ``` ### Booting with Legacy PCBIOS ```bash qemu-system-x86_64 -cdrom netboot.xyz.iso -m 4G ``` ### Booting with a UEFI BIOS ```bash qemu-system-x86_64 -bios /usr/share/ovmf/OVMF.fd -cdrom netboot.xyz.iso -m 4G ``` ### Booting on MacOS Apple Silicon (M1) ```bash $ brew install qemu $ qemu-system-aarch64 --version QEMU emulator version 7.1.0 $ qemu-system-aarch64 -cpu host -M virt,accel=hvf -m 4G \ -drive file=/opt/homebrew/share/qemu/edk2-aarch64-code.fd,if=pflash,format=raw,readonly=on \ -kernel netboot.xyz-arm64.efi \ -serial stdio \ -device virtio-gpu-pci \ -device nec-usb-xhci -device usb-kbd ``` :::note At least 4GB of memory is recommended for some of the images that are loaded into RAM. If you experience problems during initrd load, the machine usually just needs more RAM. ::: --- # Boot from TFTP Source: https://netboot.xyz/docs/booting/tftp If you want to utilize netboot.xyz from your home or office network, it's relatively easy to set up. It will allow all of your devices on your network to have netboot.xyz available whenever you need it by just changing the boot order on your device, selecting network boot, or manually selecting the device to boot. ### DHCP Server Setup You will have to tell your DHCP server to provide a "next-server", the address of a TFTP server on your network, and a "filename", the netboot.xyz boot file (you can choose among different architecture systems [here](https://netboot.xyz/downloads/). When your clients boot up, if they are set to network boot, they'll automatically get a valid DHCP address, pull down the netboot.xyz iPXE bootloader and load up the Operating System menu. Example: ``` next-server "1.2.3.4" filename "netboot.xyz.kpxe" ``` If you are using [dnsmasq as your DHCP server](https://wiki.archlinux.org/index.php/dnsmasq#DHCP_server) as well as your TFTP server then setting the next-server option is as simple as adding the following line to `/etc/dnsmasq.conf`: ``` dhcp-option=66,"0.0.0.0" ``` `0.0.0.0` is parsed as the address of the machine running dnsmasq. ### TFTP Server Setup You will need to set up a tftp server to host the iPXE files. There are various types of TFTP servers out there and they all usually work pretty well. You can also use dnsmasq to host the files as well. If you use dnsmasq you can add this configuration to `/etc/dnsmasq.conf`: ``` enable-tftp tftp-root=/var/lib/tftp dhcp-boot=netboot.xyz.kpxe ``` ### Fixing the dnsmasq service If you are running systemd and you can start dnsmasq fine manually but it fails to start at boot you may need to edit the [Unit] section of `/lib/systemd/system/dnsmasq.service` by changing: ``` After=network.target ``` to ``` After=network-online.target ``` ### Regular and Undionly Boot Files If you experiencing issues with the regular [netboot.xyz.kpxe](https://boot.netboot.xyz/ipxe/netboot.xyz.kpxe) bootloader, you can try and use the [netboot.xyz-undionly.kpxe](https://boot.netboot.xyz/ipxe/netboot.xyz-undionly.kpxe) bootloader. The regular bootloader includes common NIC drivers in the iPXE image, while the undionly loader will piggyback off the NIC boot firmware. --- # Booting from a Local UEFI Executable Source: https://netboot.xyz/docs/booting/uefi ## Overview This guide describes how to boot into netboot.xyz using a local UEFI executable. This method involves placing the UEFI executable on the EFI system partition and configuring the UEFI boot manager to boot from it. ## UEFI Boot Manager The UEFI boot manager is responsible for managing the boot process on UEFI-based systems. It uses boot entries stored in NVRAM to determine the boot order and which bootloader to execute. The boot entries are identified by their boot numbers (e.g., Boot0001, Boot0002) and can be managed using the `efibootmgr` tool. ### BootOrder and BootNext Variables The `BootOrder` variable defines the order in which the boot entries are attempted. The `BootNext` variable specifies a single boot entry to be used for the next boot only, after which the system reverts to the `BootOrder`. ## Using `efibootmgr` to Manage UEFI Boot Entries The `efibootmgr` tool allows you to manage UEFI boot entries from within a running operating system. You can use it to create, delete, and modify boot entries, as well as change the boot order. ### Adding a Boot Entry To add a new boot entry for the netboot.xyz UEFI executable, use the following command: ```bash sudo efibootmgr --create --disk /dev/sdX --part Y --label "netboot.xyz" --loader /EFI/netboot.xyz/netboot.xyz.efi ``` Replace `/dev/sdX` with the disk containing the EFI system partition, and `Y` with the partition number of the EFI system partition. ### Changing the Boot Order To change the boot order and make the new boot entry the first in the list, use the following command: ```bash sudo efibootmgr --bootorder XXXX,YYYY,ZZZZ ``` Replace `XXXX` with the boot number of the new netboot.xyz entry, and `YYYY, ZZZZ` with the boot numbers of other entries in the desired order. ## Other Boot Methods ### GRUB You can use GRUB to boot the netboot.xyz UEFI executable by adding a custom menu entry to the GRUB configuration file. Add the following entry to `/etc/grub.d/40_custom`: ```bash menuentry "netboot.xyz" { search --no-floppy --file --set=root /EFI/netboot.xyz/netboot.xyz.efi chainloader /EFI/netboot.xyz/netboot.xyz.efi } ``` After adding the entry, update the GRUB configuration: ```bash sudo update-grub ``` ### systemd-boot To add a boot entry for netboot.xyz in systemd-boot, create a new file in the `/boot/loader/entries/` directory with the following content: ```ini title netboot.xyz efi /EFI/netboot.xyz/netboot.xyz.efi ``` ### rEFInd To add a boot entry for netboot.xyz in rEFInd, create a new file in the `/boot/EFI/refind/` directory with the following content: ```ini menuentry "netboot.xyz" { loader /EFI/netboot.xyz/netboot.xyz.efi } ``` ### UEFI Shell You can also boot the netboot.xyz UEFI executable from the UEFI Shell. To do this, navigate to the directory containing the executable and run the following command: ```shell fsX: cd EFI\netboot.xyz netboot.xyz.efi ``` Replace `fsX:` with the appropriate filesystem identifier for the EFI system partition. ## Vendor-Specific Boot Menu Options Some vendors provide options in the boot menu to select an arbitrary UEFI executable to boot from. Consult your system's documentation for instructions on how to access and use these options. --- # Boot from USB Source: https://netboot.xyz/docs/booting/usb :::danger Backup your important data before writing the USB as it will overwrite anything on the USB key. ::: To boot netboot.xyz from a [USB key](https://amzn.to/3CD0BE5), you will need to write the netboot.xyz image to the key. This enables you to boot into netboot.xyz on any machine that supports USB booting. You can download the `netboot.xyz.img` USB disk image [here](https://boot.netboot.xyz/ipxe/netboot.xyz.img). ## Creating USB Key on Linux Insert a USB key in your computer and find the device name. Then use following command: ```shell cat netboot.xyz.img > /dev/sdX ``` or you can run the following command: ```shell dd if=netboot.xyz.img of=/dev/sdX ``` where sdX is your usb drive. The USB key should be ready to eject once finished. ## Creating USB Key on MacOS __To get the current list of devices, run:__ ```shell diskutil list ``` __Insert the flash media and run once again to determine the device node assigned to your flash media (e.g. /dev/disk2):__ ```shell diskutil list ``` __Run the following, replacing N with the disk number from the last command (in the previous example, N would be 2):__ ```shell diskutil unmountDisk /dev/diskN ``` __Now write the disk image to the flash media by running:__ ```shell sudo dd if=netboot.xyz.img of=/dev/rdiskN bs=1m ``` * Using /dev/rdisk instead of /dev/disk may be faster * If you see the error dd: Invalid number '1m', you are using GNU dd. Use the same command but replace bs=1m with bs=1M * If you see the error dd: /dev/diskN: Resource busy, make sure the disk is not in use. Start the 'Disk Utility.app' and unmount (don't eject) the drive __Now run and remove your flash media when the command completes:__ ```shell diskutil eject /dev/diskN ``` ## Creating USB Key on Windows For creating a USB Key on a Windows device, you can check out [Rufus](https://rufus.akeo.ie/) to install the image file to a USB key. ## Booting from the USB Key Once you've created your key, reboot and set your BIOS to load the USB key first if it's not set for that already. You should see iPXE load up either load up netboot.xyz automatically or you will be prompted to set your networking information up. --- # Boot from VMs Source: https://netboot.xyz/docs/booting/vms ## VMware Fusion These instructions are for setting up netboot.xyz in a VM on VMware's Fusion for MacOS. ### Create the VM * Add a new virtual machine. * Select "Install from disc or image". * Click on "Use another disk or disc image...". * Download and select the netboot.xyz [ISO](https://boot.netboot.xyz/ipxe/netboot.xyz.iso). * On the Choose Operating System Screen, select the OS type you are planning on installing. If you plan on testing multiple types of installs, you can just choose a CentOS 64-bit OS. * Click the "Customize Settings" and give the VM a name, like "netboot.xyz". This will create your VM. ### Running the VM _You'll need to adjust the memory settings of the VM to ensure you'll have enough memory to run the OS installers in memory. Typically it's good to bump the memory up to 2GB to 4GB._ * Click the wrench icon and click on Processors & Memory and bump up the memory to the desired amount of memory. * Start the VM up and you should see the netboot.xyz loader. * If you determine you no longer want to boot from netboot.xyz, you can either change the boot order to boot from the hard drive by default or delete the ISO from the VM. ## Proxmox VE These instructions are for setting up netboot.xyz in a VM on Proxmox VE. ### Create the VM * Log in to the Proxmox web interface. * Click on "Create VM" in the top right corner. * Give the VM a name, like "netboot.xyz", and click "Next". * On the OS tab, select "Do not use any media" and click "Next". * On the System tab, select "OVMF (UEFI)" for the BIOS, add an EFI disk, select, the EFI Storage, and uncheck "Pre-Enroll Keys", then click "Next". * On the Hard Disk tab, set the Disk size to a small value (e.g., 4GB) since netboot.xyz does not require much space, and click "Next". * On the CPU tab, allocate the desired number of cores and click "Next". * On the Memory tab, allocate the desired amount of memory (e.g., 2GB to 4GB) and click "Next". * On the Network tab, leave the defaults and click "Next". * On the Confirm tab, review the settings and click "Finish". ### Upload the ISO * Click on the "local" storage in the left sidebar. * Click on the "ISO Images" tab. * Click "Upload" and select the netboot.xyz [ISO](https://boot.netboot.xyz/ipxe/netboot.xyz.iso) file to upload. ### Attach the ISO and Boot * Select the newly created VM from the left sidebar. * Click on the "Hardware" tab. * Click "Add" and select "CD/DVD Drive". * Choose "Use CD/DVD disc image file (iso)" and select the uploaded netboot.xyz ISO. * Click "OK". * Click on the "Options" tab. * Double-click "Boot Order" and ensure the CD/DVD drive is set to boot first. * Start the VM and you should see the netboot.xyz loader. ## Hyper-V These instructions are for setting up netboot.xyz in a VM on Hyper-V. ### Create the VM * Open Hyper-V Manager. * Click on "New" and select "Virtual Machine". * Click "Next" on the Before You Begin screen. * Give the VM a name, like "netboot.xyz", and click "Next". * Choose "Generation 1" and click "Next". * Allocate the desired amount of memory (e.g., 2GB to 4GB) and click "Next". * Configure the network settings and click "Next". * Choose "Create a virtual hard disk" and set the Disk size to a small value (e.g., 4GB) since netboot.xyz does not require much space, and click "Next". * Choose "Install an operating system from a bootable CD/DVD-ROM" and select the netboot.xyz [ISO](https://boot.netboot.xyz/ipxe/netboot.xyz.iso). * Click "Finish". ### Running the VM * Right-click on the newly created VM and select "Settings". * Adjust the memory settings if needed. * Start the VM and you should see the netboot.xyz loader. * If you determine you no longer want to boot from netboot.xyz, you can either change the boot order to boot from the hard drive by default or remove the ISO from the VM. --- # Build Automation Source: https://netboot.xyz/docs/community/build-automation ```mdx-code-block ``` --- # netboot.xyz changelog Source: https://netboot.xyz/docs/community/changelog ```mdx-code-block ``` --- # Contributing Source: https://netboot.xyz/docs/community/contributing ```mdx-code-block ``` --- # netboot.xyz around the Internet Source: https://netboot.xyz/docs/community/nbxyz-users # netboot.xyz around the Internet ## Hacker News - [Netboot.xyz: your favorite operating systems in one place](https://news.ycombinator.com/item?id=31814288) (2022-06-19) - [Netboot Linux over the internet](https://news.ycombinator.com/item?id=14883590) (2017-07-29) - [Netboot](https://news.ycombinator.com/item?id=10923460) (2016-01-18) ## Podcasts - [LINUX Unplugged - EP 592: Chris' Netboot Nonsense](https://www.jupiterbroadcasting.com/show/linux-unplugged/592/) (2024-12-08) ## Youtube - [TechnoTim: Meet netboot.xyz - Network Boot Any Operating System](https://youtu.be/4btW5x_clpg) (2023-11-11) - [Linus Tech Tips: Download These Handy Tools NOW! Essential USB Tools](https://youtu.be/0EtgwIajVqs?t=426) (2023-07-19) ## Hosting Providers - [1gservers](https://1gservers.com/blog/system-administration/booting-into-netboot-xyz-is-now-supported/) - [ExtraVM](https://extravm.com/billing/knowledgebase/39/Can-I-use-my-own-ISO-on-VPS.html) - [Leaseweb](https://kb.leaseweb.com/products/dedicated-server/installing-servers-using-your-own-pxe-boot-environment/) - [MVPS](https://www.mvps.net/docs/how-to-use-netboot-xyz-iso-to-install-other-operating-systems-on-your-vps/) - [Vultr](https://www.vultr.com/docs/ipxe-boot-feature/) ## Open Source Projects - [JetKVM - Hardware KVM with support for netboot.xyz](https://amzn.to/4sjx5rH) - [Quickemu](https://github.com/quickemu-project/quickemu) - [Tinkerbell](https://tinkerbell.org/examples/netboot-xyz/) - [u-root](https://github.com/u-root/u-root/blob/main/cmds/exp/netbootxyz/netbootxyz.go) And many other places as well. If you find us somewhere on the net, update this page! --- # Custom Menus Source: https://netboot.xyz/docs/docker/custom-menus # Custom Menus The netboot.xyz web interface allows you to create custom iPXE menus that can be integrated into your netboot.xyz environment. This feature enables you to add your own boot options, utilities, or custom configurations without modifying the core netboot.xyz code. ## Prerequisites - Access to the netboot.xyz web interface - Basic understanding of iPXE scripting - Ability to modify configuration files ## Creating a Custom Menu ### Step 1: Enable Custom Menu in Configuration First, you need to modify the `boot.cfg` file to enable custom menu support: ```bash set menu custom-user ``` This setting tells netboot.xyz to include the custom menu option in the main menu. ### Step 2: Create the Custom Menu File 1. Navigate to the netboot.xyz web interface 2. Click on the **Menus** option in the header 3. Create a new file with the filename `custom.ipxe` ### Step 3: Update the Menu Configuration You need to update the `menu.ipxe` file to properly chain to your custom menu: Replace the existing line: ```bash chain custom/custom.ipxe ``` With: ```bash chain custom.ipxe ``` ### Step 4: Configure Your Custom Menu Inside the `custom.ipxe` file you created, add your custom menu configuration. You can structure your menu using standard iPXE syntax. ## Menu Structure Example Here's a basic structure for your custom menu: ```bash #!ipxe ######## CUSTOM MENU ######## :custom_menu menu Custom Boot Options item --gap -- Custom Options: item custom_option1 Custom Option 1 item custom_option2 Custom Option 2 item --gap -- Tools: item custom_tool1 Custom Tool 1 item --gap -- Return: item return Return to Main Menu choose --default return --timeout 10000 custom_target && goto ${custom_target} :custom_option1 # Add your custom boot logic here echo Booting Custom Option 1... # Add your boot commands goto custom_menu :custom_option2 # Add your custom boot logic here echo Booting Custom Option 2... # Add your boot commands goto custom_menu :custom_tool1 # Add your custom tool logic here echo Loading Custom Tool 1... # Add your tool commands goto custom_menu :return exit ``` ## Resources and Examples ### Example Configuration For a complete example of a custom menu configuration, visit: - [netboot.xyz-custom example](https://github.com/netbootxyz/netboot.xyz-custom/blob/master/custom.ipxe.example) ### iPXE Documentation For detailed information about iPXE commands and syntax: - [iPXE Commands Reference](https://ipxe.org/cmd) ### Community Examples You can find additional examples and inspiration from other users' configurations: - [netboot.xyz-custom repository forks](https://github.com/netbootxyz/netboot.xyz-custom/forks) ## Best Practices 1. **Test your menu thoroughly** - Always test your custom menu in a safe environment before deploying to production 2. **Keep it simple** - Start with basic menu items and gradually add complexity 3. **Document your changes** - Comment your iPXE code to make it easier to maintain 4. **Use descriptive names** - Choose clear, descriptive names for your menu items 5. **Handle errors gracefully** - Include error handling in your custom boot logic ## Troubleshooting ### Common Issues - **Menu not appearing**: Ensure `set menu custom-user` is properly set in `boot.cfg` - **File not found**: Verify that `custom.ipxe` exists in the correct location - **Syntax errors**: Check your iPXE syntax using the command reference - **Boot failures**: Test individual boot commands before integrating them into the menu ### Getting Help If you encounter issues with your custom menu: 1. Check the [iPXE documentation](https://ipxe.org/cmd) for command syntax 2. Review the [example configuration](https://github.com/netbootxyz/netboot.xyz-custom/blob/master/custom.ipxe.example) 3. Ask for help in the netboot.xyz community forums or GitHub discussions ## Related Documentation - [Self Hosting](../selfhosting.md) - For information about self-hosted custom options - [FAQ](../faq.md) - For general questions about netboot.xyz - [Quick Start](../quick-start.md) - For getting started with netboot.xyz --- # DHCP Configurations Source: https://netboot.xyz/docs/docker/dhcp The netboot.xyz Docker image requires the usage of a DHCP server in order to function properly. If you have an existing DHCP server, usually you will need to make some small adjustments to make your DHCP server forward requests to the netboot.xyz container. The main settings in your DHCP or router that you will typically need to set are: * `tftp-server` also known as `next-server`, this option tells the client where to look for the boot file * `boot-file-name`, this option tells the client which boot file to load ## Examples The following are some configuration examples for setting up a DHCP server to get started. The main configuration you will need to change are `SERVER_IP_ADDRESS` so that DHCP can direct the client to the server running the netboot.xyz Docker container. Because the Docker image is hosting a dnsmasq TFTP server, the boot files are pulled from it and then it will attempt to load the iPXE configs directly from the host. You can then modify and adjust them to your needs. See [booting from TFTP](https://netboot.xyz/docs/booting/tftp/) for more information. ### Setting up dnsmasq To install dnsmasq as your DHCP server run: ```shell sudo apt install dnsmasq ``` ```shell sudo dnf install dnsmasq ``` Set up your configuration file `/etc/dnsmasq.conf` with the following settings: :::note The following steps are examples and may not be the exact steps you need to take for your environment. Make sure to adjust the configuration to your needs. ::: ```shell # /etc/dnsmasq.conf # Set the DHCP Range and lease time dhcp-range=192.168.1.100,192.168.1.200,255.255.255.0,12h # Set the default gateway dhcp-option=option:router,192.168.1.1 # Set tne DNS servers dhcp-option=option:dns-server,8.8.8.8,8.8.4.4 # Standard PC BIOS dhcp-match=set:bios,60,PXEClient:Arch:00000 dhcp-boot=tag:bios,netboot.xyz.kpxe,,SERVER_IP_ADDRESS # 64-bit x86 EFI dhcp-match=set:efi64,60,PXEClient:Arch:00007 dhcp-boot=tag:efi64,netboot.xyz.efi,,SERVER_IP_ADDRESS # 64-bit x86 EFI (obsolete) dhcp-match=set:efi64-2,60,PXEClient:Arch:00009 dhcp-boot=tag:efi64-2,netboot.xyz.efi,,SERVER_IP_ADDRESS # 64-bit UEFI for arm64 dhcp-match=set:efi64-3,60,PXEClient:Arch:0000B dhcp-match=set:efi64-3,60,PXEClient:Arch:00011 dhcp-boot=tag:efi64-3,netboot.xyz-arm64.efi,,SERVER_IP_ADDRESS ``` A breakdown of the configuration: - `dhcp-range` sets the range of IP addresses and lease times that will be assigned to clients. - `dhcp-option` sets the default gateway and DNS servers. - `dhcp-boot` sets the boot file for different architectures, the `SERVER_IP_ADDRESS` should be replaced with the IP address of the host running the Docker container. - `dhcp-match` sets the match criteria for different architectures. Once the dnsmasq configuration is set, you can enable and start the service: ```shell sudo systemctl enable dnsmasq sudo systemctl start dnsmasq ``` ## netboot.xyz boot file types The following bootfile names can be set as the boot file in the DHCP configuration depending on your needs. They are baked into the Docker image: | 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 Docker Container Overview Source: https://netboot.xyz/docs/docker/ The [netboot.xyz Docker image](https://github.com/netbootxyz/docker-netbootxyz) allows you to easily set up a local instance of netboot.xyz. The container is a small helper application written in node.js. It provides a simple web interface for editing menus on the fly, retrieving the latest menu release of netboot.xyz, and enables mirroring the downloadable assets from Github to your location machine for faster booting of assets. ![netboot.xyz webapp](../../static/img/netboot.xyz-webapp.png) It is a great tool for developing and testing custom changes to the menus. If you have a machine without an optical drive that cannot boot from USB then having a local netboot server provides a way to install an OS. If you are looking to get started with netboot.xyz and don't want to manage iPXE menus, you should use the boot media instead of setting up a container. The container is built upon Alpine Linux and contains several components: * netboot.xyz [webapp](https://github.com/netbootxyz/webapp) * nginx for hosting local assets from the container * dnsmasq for providing TFTP services * syslog for providing tftp activity logs Services are managed in the container by [supervisord](http://supervisord.org/). The container runs under both x86_64 and ARM based architectures. ## How it Works The following diagram details the flow of how netboot.xyz serves content to a client and how it works when the Docker container is used: ```mermaid graph LR A[Client Computer] -->|PXE Boot Request| B{netboot.xyz container?} B -- Yes --> C[netboot.xyz container] C -- Local request --> D[Serve netboot.xyz] C -- Unavailable --> E[boot.netboot.xyz] B -- No --> E E -->|Internet Request| F[boot.netboot.xyz] F --> G[Serve netboot.xyz] G --> H[Client Boots OS] D --> H ``` ```mermaid graph TD A[Client Computer] -->|PXE Boot Request| B{netboot.xyz container?} B -- Yes --> C[netboot.xyz container] C -- Local request --> D[Serve netboot.xyz] C -- Unavailable --> E[boot.netboot.xyz] B -- No --> E E -->|Internet Request| F[boot.netboot.xyz] F --> G[Serve netboot.xyz] G --> H[Client Boots OS] D --> H ``` --- # Container Parameters Source: https://netboot.xyz/docs/docker/parameters Container images are configured using parameters passed at runtime. These parameters are separated by a colon and indicate `:` respectively. For example, `-p 8080:80` would expose port `80` from inside the container to be accessible from the host's IP on port `8080` outside the container. | Parameter | Function | | :-------: | ------- | | `-p 3000` | Web configuration interface. | | `-p 69/udp` | TFTP Port. | | `-p 80` | NGINX server for hosting assets. | | `-e WEB_APP_PORT=3000` | Specify a different port for the web configuration interface to listen on. | | `-e NGINX_PORT=80` | Specify a different port for NGINX service to listen on. | | `-e MENU_VERSION=2.0.84` | Specify a specific version of boot files you want to use from netboot.xyz (unset pulls latest) | | `-e TFTPD_OPTS='--tftp-single-port'` | Specify arguments for the TFTP server (this example makes TFTP send all data over port 69) | | `-v /config` | Storage for boot menu files and web application config | | `-v /assets` | Storage for netboot.xyz bootable assets (live CDs and other files) | --- # Setting up the Container Source: https://netboot.xyz/docs/docker/usage The netboot.xyz Docker image requires an existing DHCP server to be setup and running in order to boot from it. The image does not start a DHCP server service. Please see the DHCP configuration setup near the end of this document for ideas on how to enable your environment to talk to the container. In most cases, you will need to specify the next-server and boot file name in the DHCP configuration. ### Installing Docker If you have not set up Docker on your system, you can follow the instructions below to install it. The following examples are for Debian, Ubuntu, and Red Hat based systems. ```shell # Add Docker's official GPG key: sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Add the repository to Apt sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` ```bash # Add Docker's official GPG key: sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Add the repository to Apt sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` ```bash # Setup Repository sudo dnf -y install dnf-plugins-core sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # Install Docker sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # Start the Docker service sudo systemctl enable --now docker ``` :::note If you are using a different distribution, please refer to the [official Docker documentation](https://docs.docker.com/get-docker/) for installation instructions. ::: ### Pulling the Docker image The netboot.xyz container image is available from the GitHub Container Registry as well as Docker Hub. The image is updated regularly and is the recommended way to get the latest version of the container: ```shell docker pull ghcr.io/netbootxyz/netbootxyz ``` ```shell docker pull netbootxyz/netbootxyz ``` The following snippets are examples of starting up the container. ### Starting up the container with the Docker CLI ```shell docker run -d \ --name=netbootxyz \ -e MENU_VERSION=2.0.84 `# optional` \ -e NGINX_PORT=80 `# optional` \ -e WEB_APP_PORT=3000 `# optional` \ -p 3000:3000 `# sets web configuration interface port, destination should match ${WEB_APP_PORT} variable above.` \ -p 69:69/udp `# sets tftp port` \ -p 8080:80 `# optional, destination should match ${NGINX_PORT} variable above.` \ -v /local/path/to/config:/config `# optional` \ -v /local/path/to/assets:/assets `# optional` \ --restart unless-stopped \ ghcr.io/netbootxyz/netbootxyz ``` **To update the image using Docker CLI:** ```shell docker pull ghcr.io/netbootxyz/netbootxyz # pull the latest image down docker stop netbootxyz # stop the existing container docker rm netbootxyz # remove the image docker run -d ... # previously ran start command ``` Start the container with the same parameters used above. :::note If the same folders are used your settings will remain. If you want to start fresh, you can remove the paths and start over. ::: ### Starting up the container with Docker Compose 1. Copy [docker-compose.yml.example](https://github.com/netbootxyz/docker-netbootxyz/blob/master/docker-compose.yml.example) to docker-compose.yml 1. Edit as needed 1. Run `docker compose up -d netbootxyz` to start containers in the background 1. Run `docker compose logs -f netbootxyz` to view logs **To update the image using Docker Compose:** ```shell docker compose pull netbootxyz # pull the latest image down docker compose up -d netbootxyz # start containers in the background ``` ### Accessing the container services Once the container is started, the following services will be available via browser: | Service | Description | |-----------------------|-----------------------------| | http://localhost:3000 | Web configuration interface | | http://localhost:8080 | Downloaded web assets | :::note If you wish to remove the configuration, you can remove the local configuration folders and upon restart of the container, it will load the default configurations. ::: ### Local Mirror Access If you want to pull the Live Images images down to your own mirror and boot off them you will need to update the `live_endpoint` variable in `local-vars.ipxe` file within the web configuration interface. The [local-vars.ipxe](https://github.com/netbootxyz/netboot.xyz/blob/master/roles/netbootxyz/templates/local-vars.ipxe.j2) is a file that is checked early during the boot [process](https://github.com/netbootxyz/netboot.xyz/blob/master/roles/netbootxyz/templates/disks/netboot.xyz.j2#L99) and will load up variables into netboot.xyz. Using this file, you can set overriddes for variables early in the boot process. By default the `live_endpoint` variable is set to upstream location of `https://github.com/netbootxyz`. If you want to override this, set `live_endpoint` to your deployment IP or domain, e.g. `http://192.168.0.50:8080`. It will then redirect asset download to the local location you set for assets on port `8080` and you can download the assets by using the local assets menu down to your local server. This can result in much faster boot times. --- # Frequently Asked Questions (FAQ) Source: https://netboot.xyz/docs/faq ### What is netboot.xyz? netboot.xyz is a tool that allows you to boot your favorite Operating System's installer or various utilities over the network with minimal overhead and all from a single menu system. It's similar to various netbooting tools of the past like boot.kernel.org with a lot more flexibility. The boot loader is very light weight being under 1MB in size which translates into a very quick time to create a USB key. ### How does netboot.xyz work? netboot.xyz uses an open source tool called iPXE. The bootloader calls to a webserver that hosts that the iPXE source files. The iPXE source files contain menus and logic that understand how the various Linux installers operate. When you select an Operating System, netboot.xyz retrieves the images from the project directory when possible or known and trusted performant mirrors. The location the file is pulled from is always displayed during retrieval. From the very beginning, we have made it a priority to make sure that the source code for the project is open and available for review so that our users can view and understand what is happening. ### What is PXE Booting? PXE stands for **P**re-Boot e**X**ecution **E**nvironment. PXE booting has been used for years to allow for clients to boot from a server over the network. It gives you an oportunity to automate a system inside the BIOS before it boots off its hard drive which opens up the door for running stateless machines without having to use storage in the system. PXE booting is used in many applications but it's most common use is automating the installation of bare metal or a virtual machine. ### Will my favorite distribution work with netboot.xyz? Usually you need three things to boot up an OS over the network, the vmlinuz, the initramfs, and the rootfs. Distributions that support an installer kernel hosted on a mirror are typically the easier ones to implement as they are very lightweight. Distributions that only release ISOs are typically a bit more involved to implement as we have to use memdisk to load it up into memory. From [syslinux - memdisk](https://www.syslinux.org/wiki/index.php/MEMDISK): The majority of Linux based CD images will also fail to work with MEMDISK ISO emulation. Linux distributions require kernel and initrd files to be specified, as soon as these files are loaded the protected mode kernel driver(s) take control and the virtual CD will no longer be accessible. If any other files are required from the CD/DVD they will be missing, resulting in boot error(s). Linux distributions that only require kernel and initrd files function fully via ISO emulation, as no other data needs accessing from the virtual CD/DVD drive once they have been loaded. The boot loader has read all necessary files to memory by using INT 13h, before booting the kernel. To get around these limitations, especially since memdisk is not supported with UEFI, we have built a CI/CD system that consumes the ISOs from upstream projects and prepares the needed files to boot the operating system remotely as a release. In some cases this may involve a small modification to the init scripts in order to tune the network boot flexibility or handle multiple parts for larger operating systems. Those releases are added to the endpoints.yml in the main netboot.xyz repo and are then available for download. You can read more about our build system [here](https://github.com/netbootxyz/build-pipelines/blob/master/README.md). ### My distribution uses ISOs for delivery, how can I see if they work? You can do a quick check by loading up netboot.xyz in a virtual environment baremetal. Make sure you have plenty of RAM as you are loading the ISO into RAM. Then select the iPXE command line and enter the following; ``` kernel https://boot.netboot.xyz/memdisk iso raw initrd http://url/to/iso boot ``` That should load the ISO and if you make it all the way into the installer, great, your OS may work. If it fails during initramfs load trying to load the CD device, then it has the issue of not being able to find the ISO in memory. ### Can I create my own configurations? Yes! You can fork [netboot.xyz-custom](https://github.com/netbootxyz/netboot.xyz-custom) and create your own menu. You can then set your Github user from the Utility menu and your menu will show up in the main menu. If you don't want to set your user every time, you can custom compile the netboot.xyz iPXE code and include your github_user during the compile. This allows you to create your own menu without the maintenance of everything else. ### Does netboot.xyz support Secure Boot? Yes. netboot.xyz provides pre-built Secure Boot compatible images that use a Microsoft-trusted shim to chainload a signed iPXE binary, so you can network boot without disabling Secure Boot in your firmware. See the [Secure Boot](./kb/hardware/secureboot.md) documentation for details on the available images and how to use them. Note that Secure Boot support is currently limited to a subset of distributions (Debian, Devuan, and Kali Linux) for end-to-end installations. Other distributions can be accessed from the netboot.xyz menu but may require Secure Boot to be disabled for the final OS installation step. ### How does netboot.xyz keep OS versions up to date? We have a CI/CD system that monitors upstream projects for new releases. When a new release is detected for releases without hosted installer kernels, it will download the ISO, extract it, and then repackage it with the needed iPXE files to make it bootable. It will then push the release to the netboot.xyz endpoints.yml file and then push the changes to the netboot.xyz repo. The endpoints.yml file is then used by the netboot.xyz iPXE code to display the menu options. Versions change a lot, so automation is key in making the maintenance of the project sustainable. ### What Operating Systems are currently available on netboot.xyz? #### Operating Systems | Name | URL | Installer Kernel | Live OS | |------------|-----------------|------------------|---------------| | AlmaLinux | https://almalinux.org/ | Yes | No | | Alpine Linux | https://alpinelinux.org | Yes | No | | Arch Linux | https://www.archlinux.org | Yes | No | | Backbox | https://www.backbox.org | No | Yes | | BlackArch Linux | https://blackarch.org | Yes | Yes | | Bluestar Linux | https://sourceforge.net/projects/bluestarlinux | No | Yes | | Bodhi Linux | https://www.bodhilinux.com | No | Yes | | CentOS | https://centos.org | Yes | No | | Fedora CoreOS | https://getfedora.org/en/coreos?stream=stable | Yes | No | | Debian | https://debian.org | Yes | Yes| | Deepin | https://www.deepin.org | No | Yes | | Devuan | https://devuan.org | Yes | No | | Elementary OS | https://elementary.io | No | Yes | | EndeavourOS | https://endeavouros.com | No | Yes | | Fatdog64 | https://distro.ibiblio.org/fatdog/web/ | No | Yes | | Fedora | https://fedoraproject.org | Yes | Yes | | Feren OS | https://ferenos.weebly.com/ | Yes | No | | Flatcar Container Linux | https://www.flatcar.org | Yes | No | | FreeBSD | https://freebsd.org | Yes, disk image | No | | FreeDOS | https://www.freedos.org | ISO - Memdisk| No | | Garuda Linux | https://garudalinux.org/ | No | Yes | | Gentoo | https://gentoo.org | Yes | Yes | | Harvester | https://harvesterhci.io | Yes | No | | hrmpf | https://github.com/leahneukirchen/hrmpf/ | No | Yes | | IPFire | https://www.ipfire.org | Yes | No | | K3OS | https://k3os.io/ | Yes | Yes | | Kairos | https://kairos.io/ | Yes | No | | Kali Linux | https://www.kali.org | Yes | Yes | | KDE Neon | https://neon.kde.org | No | Yes | | Kodachi | https://www.digi77.com/linux-kodachi/ | No | Yes | | Linux Lite | https://www.linuxliteos.com | No | Yes | | LXLE | https://lxle.net/ | No | Yes | | Mageia | https://www.mageia.org | Yes | No | | Manjaro | https://manjaro.org | No | Yes | | Mint | https://linuxmint.com | No | Yes | | Microsoft Windows | https://www.microsoft.com | User supplied media | No | | MirOS | http://www.mirbsd.org | Yes | No | | Nitrux | https://nxos.org/ | No | Yes | | NixOS | https://nixos.org | Yes | No | | OpenBSD | https://openbsd.org | Yes | No | | openEuler | https://openeuler.org | Yes | No | | openSUSE | https://opensuse.org | Yes | No | | Oracle Linux | https://www.oracle.com/linux/ | Yes | Installer | | Parrot Security | https://www.parrotsec.org | No | Yes | | Peppermint | https://peppermintos.com | No | Yes | | Pop OS |https://system76.com/pop| No | Yes | | Proxmox Open Source Products | https://www.proxmox.com/ | Yes | No | | Q4OS | https://q4os.org | No | Yes | | Raizo | https://sourceforge.net/projects/live-raizo/ | No | Yes | | Red Hat Enterprise Linux | https://www.redhat.com | User supplied media | No | | Regolith | https://regolith-linux.org | No | Yes | | Rocky Linux | https://rockylinux.org/ | Yes | No | | Septor | https://septor.sourceforge.io | No | Yes | | Slackware | https://www.slackware.com | Yes | No | | SmartOS | https://www.smartos.org/ | Yes | No | | SparkyLinux | https://sparkylinux.org/ | No | Yes | | Tails | https://tails.net | No | Yes | | Talos | https://www.talos.dev/ | Yes | No | | Tiny Core Linux | https://tinycorelinux.net | Yes | Yes | | Ubuntu | https://www.ubuntu.com | Yes | Yes | | VMware | https://www.vmware.com | User supplied media | No | | VMware Photon | https://vmware.github.io/photon/ | Yes | No | | Vanilla OS | https://vanillaos.org | No | Yes | | Voyager | https://voyagerlive.org | No | Yes | | VyOS | https://vyos.io | Yes | No | | Zen Installer | https://sourceforge.net/projects/revenge-installer | Yes | No | | Zorin OS | https://zorin.com | No | Yes | ### Utilities | Name | URL | Type | |------------|-------------------------|------| | 4MLinux | https://4mlinux.com/ | Kernel/Initrd | | Boot Repair CD | https://sourceforge.net/projects/boot-repair-cd/ | LiveCD | | Breakin | https://www.advancedclustering.com/products/software/breakin/ | Kernel/Initrd | | CAINE | https://www.caine-live.net/ | LiveCD | | Clonezilla | https://www.clonezilla.org/ | LiveCD | | DBAN | https://www.dban.org/ | Kernel | | GParted | https://gparted.org | LiveCD | | Grml | https://grml.org | LiveCD | | Kaspersky Rescue Disk | https://support.kaspersky.com/krd18 | LiveCD | | Memtest | https://www.memtest.org/ | Kernel | | MemTest86 Free | https://www.memtest86.com | USB Img | | Redo Rescue | http://redorescue.com/ | LiveCD | | Rescatux | https://www.supergrubdisk.org/rescatux/ | LiveCD | | Rescuezilla | https://rescuezilla.com/ | LiveCD | | ShredOS | https://github.com/PartialVolume/shredos.x86_64 | Kernel | | Super Grub2 Disk | https://www.supergrubdisk.org | ISO - Memdisk | | System Rescue | https://system-rescue.org/ | LiveCD | | Ultimate Boot CD | https://www.ultimatebootcd.com | ISO - Memdisk | | ZFSBootMenu | https://docs.zfsbootmenu.org/ | Kernel | ### Where can I learn more about network booting and iPXE? * [The iPXE Project](https://ipxe.org/) * [NetworkBoot.org](https://networkboot.org/) * [Syslinux Project](https://www.syslinux.org/wiki/index.php?title=The_Syslinux_Project) --- # JetKVM Source: https://netboot.xyz/docs/kb/hardware/jetkvm ## Overview [JetKVM](https://jetkvm.com) is a compact, open-source hardware KVM-over-IP device that lets you remotely control any computer at the BIOS/UEFI level — with full keyboard, video, and mouse access. It streams 1080p video at up to 60 FPS with sub-100ms latency using H.264 encoding over WebRTC, and works even in headless or crashed system scenarios where a normal remote desktop agent would be useless. JetKVM connects directly to a target machine via HDMI and USB, with no software required on the host. Remote access is available through a local web interface or optionally through the open-source JetKVM Cloud. The hardware is fully open source and extensible via an RJ12 port for add-ons like ATX power control and serial console access. You can pick one up on [Amazon](https://amzn.to/4sjx5rH). ## netboot.xyz Support JetKVM has built-in support for netboot.xyz. From the JetKVM web interface you can mount netboot.xyz as a virtual drive, allowing you to boot directly into the netboot.xyz menu on any connected machine without physical media. This makes JetKVM a powerful tool for remote OS provisioning, recovery, and diagnostics — you can network-boot a machine from anywhere and run the full netboot.xyz menu over the remote KVM connection. To get started, load one of the netboot.xyz ISO images as a virtual drive in the JetKVM interface: - [netboot.xyz ISO (Legacy/BIOS)](https://boot.netboot.xyz/ipxe/netboot.xyz.iso) - [netboot.xyz ISO (UEFI)](https://boot.netboot.xyz/ipxe/netboot.xyz-efi.iso) Boot the target machine from the virtual drive and the netboot.xyz menu will load over the network. --- # UEFI Secure Boot Source: https://netboot.xyz/docs/kb/hardware/secureboot ## Overview UEFI Secure Boot is a firmware security feature that restricts the boot process to code signed by trusted keys. Most modern UEFI systems ship with Secure Boot enabled by default. netboot.xyz provides pre-built Secure Boot compatible images so you can network-boot without disabling Secure Boot in your firmware settings. :::note Secure Boot support in netboot.xyz is still limited. Not all distributions and boot methods work when Secure Boot is active. Only Debian-family distributions (Debian, Devuan, Kali) that publish a `debian-installer` netboot tree with a signed shim currently support end-to-end Secure Boot network booting. ::: ## How It Works Standard iPXE binaries are not signed with a key trusted by the Microsoft UEFI Secure Boot Certificate Authority and will therefore be rejected by firmware with Secure Boot enabled. The iPXE project addresses this through a chain of trust: 1. **Shim** — A small, Microsoft-signed bootloader ([ipxe/shim](https://github.com/ipxe/shim)) that acts as the first stage. The shim is signed with the Microsoft third-party UEFI CA and is trusted by default on most systems. This fork of the general-purpose [rhboot/shim](https://github.com/rhboot/shim) is customized to trust the [iPXE Secure Boot CA](https://ipxe.org/secure-boot-ca). 2. **Signed iPXE** — The shim verifies and launches the iPXE binary (`ipxe.efi`), which is signed with the iPXE Secure Boot CA certificate embedded in the shim. 3. **autoexec.ipxe** — Once iPXE is running, it loads the `autoexec.ipxe` boot script that chainloads the netboot.xyz menus. The shim uses a naming convention to locate the iPXE binary: it strips `shim` from its own filename to derive the iPXE filename. For example: | Shim filename | iPXE filename | |----------------------|----------------| | `ipxe-shimx64.efi` | `ipxe.efi` | | `snponly-shimx64.efi`| `snponly.efi` | | `ipxe-shimaa64.efi` | `ipxe.efi` | ## Available Secure Boot Images netboot.xyz builds and publishes Secure Boot images for x86\_64 and ARM64. These are available as release assets at [https://github.com/netbootxyz/netboot.xyz/releases](https://github.com/netbootxyz/netboot.xyz/releases). ### Bootable ISO and USB Images The easiest way to use Secure Boot with netboot.xyz is via the pre-built ISO or USB images. Each image has the signed shim, the signed iPXE binary, and an embedded `autoexec.ipxe` baked in. The `autoexec.ipxe` contains the initial netboot.xyz boot logic that chainloads the full netboot.xyz menu, so the images work out of the box with no additional configuration. These images are published as release assets at [https://github.com/netbootxyz/netboot.xyz/releases](https://github.com/netbootxyz/netboot.xyz/releases): | File | Architecture | Use case | |---|---|---| | `netboot.xyz-sb.iso` | x86\_64 | CD/DVD/Virtual Media | | `netboot.xyz-sb.img` | x86\_64 | USB flash drive | | `netboot.xyz-sb-arm64.iso` | ARM64 | CD/DVD/Virtual Media | | `netboot.xyz-sb-arm64.img` | ARM64 | USB flash drive | Write the `.img` file to a USB drive using a tool like `dd` or [Balena Etcher](https://etcher.balena.io/). The `autoexec.ipxe` embedded in these images is also published as a standalone file in the release assets (`autoexec.ipxe`), so it can be consumed directly — for example, when using the upstream iPXE Secure Boot binaries for network boot and you want to use the same boot script the ISO/USB images use. ### Network Boot (TFTP/HTTP) Because the signed iPXE binaries cannot be recompiled, you must use the pre-built binaries directly from [https://github.com/ipxe/ipxe/releases](https://github.com/ipxe/ipxe/releases) or from the netboot.xyz release tarballs: - `secureboot-x86_64.tar.gz` - `secureboot-arm64.tar.gz` Each archive contains the directory structure expected by iPXE's shim loader: ``` secureboot-x86_64/ ├── autoexec.ipxe ├── ipxe-shim.efi ← configure DHCP to serve this ├── ipxe.efi ├── shimx64.efi ├── snponly-shim.efi └── snponly.efi ``` Configure your DHCP server to hand out the path to the shim binary rather than the iPXE binary directly. For example, with ISC dhcpd: ``` next-server 192.168.0.1; filename "/netboot.xyz/ipxe-shim.efi"; ``` All files from the archive must be present in the same directory on the TFTP/HTTP server, as the shim uses relative paths to locate the corresponding iPXE binary. #### autoexec.ipxe After iPXE loads, it automatically looks for a file named `autoexec.ipxe` in the same directory it was loaded from. If found, it executes it. This is the mechanism netboot.xyz uses to load its menus when booting via the Secure Boot image — an `autoexec.ipxe` is embedded in the netboot.xyz release tarballs that chainloads the netboot.xyz menu. If you are using the upstream iPXE binaries directly from [https://github.com/ipxe/ipxe/releases](https://github.com/ipxe/ipxe/releases), you can place your own `autoexec.ipxe` alongside the shim and iPXE binaries to control what happens after boot. For example, to load the netboot.xyz menu: ```ipxe #!ipxe chain --autofree https://boot.netboot.xyz ``` ## Booting Linux Distributions with Secure Boot When Secure Boot is active, loading a Linux kernel directly from iPXE will fail signature verification. Distributions that ship a signed UEFI shim (e.g. Debian) can be booted by using the iPXE `shim` command, which invokes the distribution's own shim to satisfy Secure Boot policy. Example iPXE script for Debian: ```ipxe #!ipxe set mirror https://mirrors.edge.kernel.org/debian set installer ${mirror}/dists/bookworm/main/installer-amd64/current/images/netboot/debian-installer/amd64 kernel ${installer}/linux initrd ${installer}/initrd.gz shim ${installer}/bootnetx64.efi boot ``` The `shim` command is a no-op when Secure Boot is not active, so it is safe to leave in scripts regardless of the boot environment. :::info The `imgverify` command is not available in the upstream iPXE Secure Boot images, as it requires features that cannot be included in a Secure Boot-signed build. netboot.xyz detects when it is running via a Secure Boot image by checking `${efi/SecureBoot}` and automatically disables signature checking (`sigs_enabled`) at runtime to prevent errors when chaining menus. ::: ## Supported Distributions End-to-end Secure Boot network booting support within netboot.xyz menus is limited to distributions that publish a `bootnetx64.efi` / `bootnetaa64.efi` shim binary as part of their netboot installer tree. Currently, only the three Debian-family distributions that ship a `debian-installer` netboot tree meet this requirement: | Distribution | x86\_64 shim | ARM64 shim | Notes | |---|---|---|---| | Debian | `bootnetx64.efi` | `bootnetaa64.efi` | Supported | | Devuan | `bootnetx64.efi` | `bootnetaa64.efi` | Supported (Debian-identical path structure) | | Kali Linux | `bootnetx64.efi` | `bootnetaa64.efi` | Supported (Debian-derived path structure) | Distributions that do **not** currently support Secure Boot network boot from netboot.xyz: | Distribution | Reason | |---|---| | Fedora | `images/pxeboot/` only provides `vmlinuz` + `initrd.img`; `EFI/BOOT/BOOTX64.EFI` is the ISO bootloader, not a PXE-capable shim | | AlmaLinux / Rocky / CentOS / RHEL / openEuler | Same as Fedora — RHEL family pxeboot path has no shim EFI binary | | openSUSE | `boot/x86_64/loader/` provides `linux` + `initrd` only; no shim binary in the netboot tree | | Ubuntu | Legacy d-i path has no `bootnetx64.efi`; Subiquity path uses netboot.xyz's own live endpoint | | Mageia, Alpine, Arch, Slackware, others | No shim EFI netboot binaries available | Support for additional distributions depends on whether they provide a signed shim binary alongside their netboot kernel and initrd. If you know of a distribution that publishes a signed shim EFI binary as part of its netboot installer tree, please [open an issue](https://github.com/netbootxyz/netboot.xyz/issues) with the mirror path and we will look at adding support. ## Known Limitations The Secure Boot images distributed by netboot.xyz are pre-built and signed by the iPXE project. Because any modification to the binary — including recompiling with different options — would invalidate the signature and break the chain of trust, these images are locked and cannot be customized. This has several practical consequences: - **`imgverify` is unavailable** — The upstream signed iPXE build omits the `imgverify` command. This means netboot.xyz's built-in menu signature verification is disabled automatically when booting via a Secure Boot image (netboot.xyz detects this via `${efi/SecureBoot}` and sets `sigs_enabled` to false at runtime). - **Theming is unavailable** — netboot.xyz's custom theme and branding rely on iPXE features that are not present in the signed build. The Secure Boot image will display a plain iPXE interface rather than the styled netboot.xyz menus. - **Other netboot.xyz features may not work** — Any feature that depends on a custom-compiled iPXE binary (additional protocol support, specific drivers, etc.) will not be available when booting via the Secure Boot image. - **No custom iPXE builds** — You cannot compile your own iPXE binary with additional features and have it trusted by the Secure Boot shim. The shim is built to trust only binaries signed by the iPXE Secure Boot CA, and only the iPXE project can produce those signatures. Use the pre-built binaries as-is and control boot behaviour via `autoexec.ipxe` instead. - **Spurious `Security Policy Violation` on kernel load** — There is a known upstream iPXE behavior where loading the kernel via the `kernel` command will briefly display a `Verification failed: Security Policy Violation` error on screen, even when the `shim` command is used and the boot ultimately succeeds. This is cosmetic — iPXE attempts to verify the kernel directly first, which fails under Secure Boot, and then the `shim` command hands off to the distribution's own shim which succeeds. The boot proceeds normally. This is [being tracked upstream](https://github.com/ipxe/ipxe/issues/1653). ## Further Reading - [iPXE Secure Boot documentation](https://ipxe.org/secboot) - [ipxe/shim on GitHub](https://github.com/ipxe/shim) - [iPXE releases](https://github.com/ipxe/ipxe/releases) --- # PXE Booting on the Steam Deck Source: https://netboot.xyz/docs/kb/hardware/steamdeck ## Overview This is a guide to PXE booting the [Valve Steam Deck](https://amzn.to/4jBYBwv). ## Requirements To get the Steam Deck to PXE boot, you will need: - [USB-C Hub](https://amzn.to/3PRGzc4) that supports Ethernet and USB - USB Keyboard - Hard Wired Ethernet Connect the hub, ethernet, and power up to the Steam Deck. The first thing you will want to do is set the BIOS to allow for PXE booting. ## BIOS Configuration To bring up the Steam Deck Boot Loader menus, shutdown the Steam Deck and: - Hold down `Volume +`, while pressing the power button `on` to access the Boot Manager, Setup Utility and Boot from File Menu. (`Volume -` will bring up just the Boot Manager) - Select Setup Utility to enter into the Setup. - Move down to the Boot Tab on the left and change these settings: - Quick Boot: Disabled - Quiet Boot: Disabled - PXE Boot Capability: UEFI: IPv4 (Can change to what is appropriate for your network) - Add Boot Options: First - Select Exit and Exit Saving Changes. ## PXE Booting The Steam Deck will now reboot and you will now see the Memory test as Quiet Boot has been disabled. If your Hub is connected to the network properly, and you have DHCP on the network, you should see: ```shell >>Start PXE over IPv4... ``` At this point you should be able to PXE boot a UEFI image. Use the: - [netboot.xyz UEFI kernel](https://boot.netboot.xyz/ipxe/netboot.xyz.efi) - Set DHCP [next-server](https://netboot.xyz/docs/booting/tftp) to TFTP server, and filename to the netboot.xyz UEFI image on the DHCP server If you happen to break the Steam Deck when testing Operating Systems or tinkering with it, you can follow the Steam Deck Recovery Instructions [here](https://help.steampowered.com/en/faqs/view/1B71-EDF2-EB6D-2BB3). If you want to set the BIOS back to the default settings, you can load the BIOS back up, select Restore Defaults, and Exit Saving Changes. That will return the Steam Deck back to its original behavior. --- # Installing netboot.xyz on Synology NAS Source: https://netboot.xyz/docs/kb/hardware/synology ## Overview This guide will walk you through the steps to install netboot.xyz onto a [Synology NAS](https://amzn.to/430KH1n) using Container Manager. ## Requirements - [Synology NAS](https://amzn.to/430KH1n) with Container Manager support - Container Manager package installed on the Synology NAS - Internet connection ### Install Container Manager Open the Synology Package Center, search for "Container Manager", and click "Install". ### Download netboot.xyz Container Image Open Container Manager from the main menu, go to the "Registry" tab, and search for `netbootxyz`. Select the `netbootxyz/netboot.xyz` image from the list, click "Download", and choose the latest version. ### Create and Configure the Container Go to the "Image" tab in Container Manager, select the `netbootxyz/netboot.xyz` image, and click "Run". In the "Create Container" wizard, configure the following settings: - **General Settings**: - Container Name: `netbootxyz` - Enable "Auto-restart" - **Advanced Settings**: - **Port Settings**: - Map port `3000/TCP` on the container to a desired port on the NAS, e.g., `3000`. - Map port `80/TCP` on the container to a desired port on the NAS, e.g., `8080` so it doesn't conflict with the UI. - Map port `69/UDP` on the container to a desired port on the NAS, e.g., `69` so it doesn't conflict with the UI. - **Volume**: - Click "Add Folder" and map a folder on your NAS to `/config` in the container. - Click "Add Folder" and map a folder on your NAS to `/assets` in the container. - **Network**: Set the network mode to "Bridge". - **Environment**: - Remove `TFTP_OPTS` if you aren't going to use it. Ensure NGINX port lines up to the port you mapped in the port settings. Ensure `WEB_APP_PORT` lines up to the port you mapped in the port settings. Click "Apply" to create the container. ### Start the Container Go to the "Container" tab in Container Manager, select the `netbootxyz` container, and click "Start". ### Access netboot.xyz Open a web browser and navigate to the IP address of your Synology NAS on port 3000 (e.g., `http://:3000`). You should see the netboot.xyz interface. The asset folder will be mapped to `8080`, or whatever you set it to, so you can access the UI at `http://:8080`. ## Conclusion You have successfully installed netboot.xyz on your Synology NAS using Container Manager. You can now use netboot.xyz to manage and boot various operating systems over the network. --- # USB Keyboard Not Working Source: https://netboot.xyz/docs/kb/hardware/usb-keyboard ## Overview On some systems the netboot.xyz menu loads and displays correctly, but the USB keyboard is completely unresponsive — you cannot navigate the menu or select any entries. This most commonly appears after upgrading from older releases (for example, the menu worked on `2.0.89` but stopped responding on `3.0.1`), and it typically affects multiple keyboards across multiple machines on the same hardware platform. If your keyboard works in your BIOS/UEFI setup screen but not once netboot.xyz loads, this article is for you. ## Cause Starting with iPXE commit [`2161e976`](https://github.com/ipxe/ipxe/commit/2161e976cdf78d0b26687e14f2cdc14008a99c83) ("[build] Include USB drivers in the all-drivers build by default"), the standard iPXE builds include USB NIC drivers so that USB Ethernet adapters can be used for network booting. Attaching iPXE's USB host-controller drivers has an unavoidable side effect on affected hardware: - **On BIOS firmware**, it disables the SMM-based USB legacy support that emulates a PS/2 keyboard. - **On UEFI firmware**, it can disconnect less-compliant vendor USB keyboard drivers (commonly seen on AMI-based firmware, including some BMC/KVM keyboard emulations). In both cases iPXE stops receiving keystrokes and the menu appears frozen. This change first shipped in the netboot.xyz `3.x` images, which is why USB keyboards work on `2.0.89` but not on `3.0.1`. It is a hardware/firmware interaction rather than a netboot.xyz bug — the standard images now trade USB legacy keyboard support for USB NIC support. The same iPXE commit also added the `ipxe-legacy` fallback build target (the existing driver set, with USB NIC drivers excluded) that the legacy images below are built from. The underlying firmware behavior is tracked upstream in [ipxe/ipxe#1643](https://github.com/ipxe/ipxe/issues/1643). ## Solution: Use the Legacy Images netboot.xyz publishes a parallel set of **legacy** bootloaders built without the USB NIC drivers. With those drivers excluded, the BIOS keeps its USB legacy support enabled and your USB keyboard works as expected. The trade-off is that USB Ethernet adapters are not supported by the legacy images — use them only if you are booting over a built-in (PCI/PCIe) network interface. ### Download The legacy images are served alongside the standard images at `boot.netboot.xyz/ipxe/`: | File | Use case | |---|---| | [`netboot.xyz-legacy.img`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.img) | USB flash drive | | [`netboot.xyz-legacy.iso`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.iso) | CD/DVD or virtual media | | [`netboot.xyz-legacy.kpxe`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.kpxe) | BIOS network boot (DHCP/TFTP) | | [`netboot.xyz-legacy.efi`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.efi) | UEFI network boot (DHCP/TFTP) | | [`netboot.xyz-legacy.lkrn`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.lkrn) | Linux kernel (chainload via GRUB/syslinux) | | [`netboot.xyz-legacy.dsk`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.dsk) | Floppy disk image | | [`netboot.xyz-legacy.pdsk`](https://boot.netboot.xyz/ipxe/netboot.xyz-legacy.pdsk) | Padded floppy disk image | ### USB Flash Drive Write `netboot.xyz-legacy.img` to a USB key exactly as you would the standard image: ```shell dd if=netboot.xyz-legacy.img of=/dev/sdX ``` Replace `sdX` with your USB device. See [Boot from USB](../../booting/usb.md) for full platform-specific instructions (Linux, macOS, and Windows). :::danger Writing the image will overwrite everything on the USB key. Back up any important data first. ::: ### ISO / Virtual Media Burn `netboot.xyz-legacy.iso` to a CD/DVD, or attach it as virtual media through a BMC such as a Dell DRAC or HP iLO. See [Boot from ISO](../../booting/iso.md) for details. ### Network Boot If you PXE boot over the network, point your DHCP/TFTP configuration at the legacy bootloader instead of the standard one — `netboot.xyz-legacy.kpxe` for BIOS clients or `netboot.xyz-legacy.efi` for UEFI clients. ## Self-Hosted Deployments The [netboot.xyz Docker container](../../docker/overview.md) downloads the legacy bootloaders automatically. On first start it fetches `netboot.xyz-legacy.kpxe` (BIOS) and `netboot.xyz-legacy.efi` (UEFI) alongside the standard boot files and serves them from its TFTP root, so you can point your DHCP `boot-file-name` at whichever one matches the affected client. If you are running an older image from before this was added, either update to the latest container image or download the binary manually from the [netboot.xyz release assets](https://github.com/netbootxyz/netboot.xyz/releases) (or from `boot.netboot.xyz/ipxe/`) and place it in the container's TFTP root (`/config/menus`). ## Notes - Only switch to the legacy images if you are actually affected by the USB keyboard issue. The standard images remain the right choice for most systems, especially anyone booting through a USB Ethernet adapter. - This behavior is tracked upstream in [netbootxyz/netboot.xyz#1769](https://github.com/netbootxyz/netboot.xyz/issues/1769). --- # Asuswrt-Merlin Source: https://netboot.xyz/docs/kb/networking/asuswrt-merlin This will enable legacy BIOS, and UEFI devices to PXE boot into the [netboot.xyz](https://github.com/netbootxyz/netboot.xyz) menu on Asuswrt-Merlin devices. Assume your AsusWRT-Merlin router is 192.168.1.1; Login to GUI 1. LAN -> DHCP Server -> Basic Config: Set "Enable the DHCP Server" to Yes; IP Pool Starting Address: 192.168.1.2; IP Pool Ending Address: 192.168.1.254 2. Administration -> System -> Service: Set "Enable SSH" to LAN Only 3. Administration -> System -> Persistent JFFS2 partition: Set "Enable JFFS custom scripts and configs" to Yes :::note JFFS is a writeable section of the flash memory (the size will vary between router models, with the newer models having a bit over 60 MB of space available), which will allow you to store small files (such as scripts) inside the router without needing to have a USB disk plugged in. This space will survive reboot (**but it might NOT survive firmware flashing, so back it up first before flashing!**). ::: 4. Reboot the router from the GUI and wait until you can ping 192.168.1.1 5. `ssh username@192.168.1.1` 6. `mkdir /jffs/tftproot` 7. `curl -o /jffs/tftproot/netboot.xyz.kpxe https://boot.netboot.xyz/ipxe/netboot.xyz.kpxe` 8. `curl -o /jffs/tftproot/netboot.xyz.efi https://boot.netboot.xyz/ipxe/netboot.xyz.efi` 9. `touch /jffs/configs/dnsmasq.conf.add` 10. `nano /jffs/configs/dnsmasq.conf.add` and add the following: > enable-tftp > tftp-root=/jffs/tftproot > dhcp-match=set:bios,60,PXEClient:Arch:00000 > dhcp-boot=tag:bios,netboot.xyz.kpxe,,192.168.1.1 > dhcp-match=set:efi32,60,PXEClient:Arch:00002 > dhcp-boot=tag:efi32,netboot.xyz.efi,,192.168.1.1 > dhcp-match=set:efi32-1,60,PXEClient:Arch:00006 > dhcp-boot=tag:efi32-1,netboot.xyz.efi,,192.168.1.1 > dhcp-match=set:efi64,60,PXEClient:Arch:00007 > dhcp-boot=tag:efi64,netboot.xyz.efi,,192.168.1.1 > dhcp-match=set:efi64-1,60,PXEClient:Arch:00008 > dhcp-boot=tag:efi64-1,netboot.xyz.efi,,192.168.1.1 > dhcp-match=set:efi64-2,60,PXEClient:Arch:00009 > dhcp-boot=tag:efi64-2,netboot.xyz.efi,,192.168.1.1 11. `reboot` and wait until you can ping 192.168.1.1 12. from another device confirm that TFTP is working on the router > `tftp 192.168.1.1` > tftp> `get netboot.xyz.kpxe` > Received 368475 bytes in 0.5 seconds 13. Test with an UEFI device and with a legacy BIOS device that PXE booting is working (you might have enable PXE booting in the BIOS and/or in UEFI. For UEFI you usually have to enable UEFI Networking stack). References: * https://programmingflow.com/2015/04/08/boot-any-machine-in-your-home-with-pxe.html * https://netboot.xyz/docs/kb/networking/edgerouter * https://github.com/RMerl/asuswrt-merlin.ng/wiki/Custom-config-files --- # Ubiquiti EdgeRouter Source: https://netboot.xyz/docs/kb/networking/edgerouter This document covers how to setup netboot.xyz, a service that provides iPXE-based installation and live boot of a bunch of operating systems, on a [Ubiquiti EdgeRouter](https://amzn.to/40zL2oL). Thanks go to [Sam Kottler](https://github.com/skottler) for originally writing up this how-to. Improve setup robustness by using the embedded TFTP daemon from dnsmasq by [Yan Grunenberger](https://github.com/ravens) instead of external TFTP package. ### Assumptions I've made a few assumptions throughout this document that will probably be different for your setup: * There is a DHCP pool called `LAN` * The `LAN` pool manages `10.10.2.0/24` ### Configure tftp support in dnsmasq By default, dnsmasq is using in the Edgerouter to provide DNS services. In order to enable it : ```bash sudo mkdir /config/user-data/tftproot sudo chmod ugo+rX /config/user-data/tftproot configure set service dns forwarding options enable-tftp set service dns forwarding options tftp-root=/config/user-data/tftproot commit save ``` ### Setup TFTP components Download the kpxe image for netboot.xyz and set the permissions properly: ```bash sudo curl -o /config/user-data/tftproot/netboot.xyz.kpxe https://boot.netboot.xyz/ipxe/netboot.xyz.kpxe sudo chmod ugo+r /config/user-data/tftproot/netboot.xyz.kpxe ``` At this point you should be able to use a TFTP client from a client in `10.10.2.0/24` to fetch the image: ```bash $ tftp 10.10.2.1 tftp> get netboot.xyz.kpxe Received 354972 bytes in 2.0 seconds ``` ### Configure dhcpd We're gonna configure DHCP on the EdgeRouter to serve the right parameters to clients: ```bash configure set service dhcp-server global-parameters "option client-arch code 93 = unsigned integer 16;" edit service dhcp-server shared-network-name LAN subnet 10.10.2.0/24 set bootfile-server 10.10.2.1 set bootfile-name netboot.xyz.kpxe commit save ``` The configuration for the `LAN` pool should now look something like the following: ```bash skottler@edge1# show service dhcp-server shared-network-name LAN authoritative enable subnet 10.10.2.0/24 { bootfile-name netboot.xyz.kpxe bootfile-server 10.10.2.1 default-router 10.10.2.1 dns-server 10.10.2.1 lease 86400 start 10.10.2.100 { stop 10.10.2.199 } } [edit] ``` That's it! ## The advanced setup with support for Legacy and UEFI ### Using ISC DHCP This section was written by [Skyler Mäntysaari](https://github.com/samip5). This requires that you do not use `set service dhcp-server use-dnsmasq enable`. If you do use that, it will not work. We are going to start by removing the PXE boot related things from dhcp-server options, so the commands for that are something like: ```bash delete service dhcp-server shared-network-name LAN subnet 10.10.2.0/24 bootfile-name netboot.xyz.kpxe delete service dhcp-server shared-network-name LAN subnet 10.10.2.0/24 bootfile-server 10.10.2.1 ``` We are now going to download the efi version of the boot file if it does not exist yet: ``` sudo curl -o /config/user-data/tftproot/netboot.xyz.efi https://boot.netboot.xyz/ipxe/netboot.xyz.efi sudo chmod ugo+r /config/user-data/tftproot/netboot.xyz.efi ``` Next we are going to create a scripts folder for the scripts, in persistent storage (should persist over upgrades): ```bash mkdir --parents /config/user-data/scripts/pxe/ ``` Next we are going to go into configure mode, and include the main pxe config file: ```bash set service dhcp-server global-parameters "deny bootp;" set service dhcp-server global-parameters "include "/config/user-data/scripts/pxe/option-space.conf";" set service dhcp-server shared-network-name LAN subnet 10.10.2.0/24 subnet-parameters "include "/config/user-data/scripts/pxe/pxe.conf";" ``` IT NEEDS to be typed exactly like that, the "" part. The file /config/user-data/scripts/pxe/pxe.conf: ```bash allow booting; next-server 10.10.2.1; if option arch = 00:07 { filename "netboot.xyz.efi"; } elsif option arch = 00:00 { filename "netboot.xyz.kpxe"; } else { filename "netboot.xyz.efi"; } ``` The file /config/user-data/scripts/pxe/option-space.conf: ```bash # Declare the iPXE/gPXE/Etherboot option space option space ipxe; option ipxe-encap-opts code 175 = encapsulate ipxe; # iPXE options, can be set in DHCP response packet option ipxe.priority code 1 = signed integer 8; option ipxe.keep-san code 8 = unsigned integer 8; option ipxe.skip-san-boot code 9 = unsigned integer 8; option ipxe.syslogs code 85 = string; option ipxe.cert code 91 = string; option ipxe.privkey code 92 = string; option ipxe.crosscert code 93 = string; option ipxe.no-pxedhcp code 176 = unsigned integer 8; option ipxe.bus-id code 177 = string; option ipxe.bios-drive code 189 = unsigned integer 8; option ipxe.username code 190 = string; option ipxe.password code 191 = string; option ipxe.reverse-username code 192 = string; option ipxe.reverse-password code 193 = string; option ipxe.version code 235 = string; option iscsi-initiator-iqn code 203 = string; # iPXE feature flags, set in DHCP request packet option ipxe.pxeext code 16 = unsigned integer 8; option ipxe.iscsi code 17 = unsigned integer 8; option ipxe.aoe code 18 = unsigned integer 8; option ipxe.http code 19 = unsigned integer 8; option ipxe.https code 20 = unsigned integer 8; option ipxe.tftp code 21 = unsigned integer 8; option ipxe.ftp code 22 = unsigned integer 8; option ipxe.dns code 23 = unsigned integer 8; option ipxe.bzimage code 24 = unsigned integer 8; option ipxe.multiboot code 25 = unsigned integer 8; option ipxe.slam code 26 = unsigned integer 8; option ipxe.srp code 27 = unsigned integer 8; option ipxe.nbi code 32 = unsigned integer 8; option ipxe.pxe code 33 = unsigned integer 8; option ipxe.elf code 34 = unsigned integer 8; option ipxe.comboot code 35 = unsigned integer 8; option ipxe.efi code 36 = unsigned integer 8; option ipxe.fcoe code 37 = unsigned integer 8; option ipxe.vlan code 38 = unsigned integer 8; option ipxe.menu code 39 = unsigned integer 8; option ipxe.sdi code 40 = unsigned integer 8; option ipxe.nfs code 41 = unsigned integer 8; # Other useful general options # https://www.iana.org/assignments/dhcpv6-parameters/dhcpv6-parameters.xhtml option arch code 93 = unsigned integer 16; ``` After all of that, it should be it! I hope that helps. ### Using dnsmasq This section was written by [Benjamin Reich](https://benjaminreich.de/). This Part is requierd if you using `set service dhcp-server use-dnsmasq enable`. Connect via SSH and replace `SERVERIP` with the actual IP. ```bash configure set service dhcp-server use-dnsmasq enable set service dns forwarding options "dhcp-match=set:bios,60,PXEClient:Arch:00000" set service dns forwarding options "dhcp-boot=tag:bios,netboot.xyz.kpxe,,SERVERIP" set service dns forwarding options "dhcp-match=set:efi32,60,PXEClient:Arch:00002" set service dns forwarding options "dhcp-boot=tag:efi32,netboot.xyz.efi,,SERVERIP" set service dns forwarding options "dhcp-match=set:efi32-1,60,PXEClient:Arch:00006" set service dns forwarding options "dhcp-boot=tag:efi32-1,netboot.xyz.efi,,SERVERIP" set service dns forwarding options "dhcp-match=set:efi64,60,PXEClient:Arch:00007" set service dns forwarding options "dhcp-boot=tag:efi64,netboot.xyz.efi,,SERVERIP" set service dns forwarding options "dhcp-match=set:efi64-1,60,PXEClient:Arch:00008" set service dns forwarding options "dhcp-boot=tag:efi64-1,netboot.xyz.efi,,SERVERIP" set service dns forwarding options "dhcp-match=set:efi64-2,60,PXEClient:Arch:00009" set service dns forwarding options "dhcp-boot=tag:efi64-2,netboot.xyz.efi,,SERVERIP" commit; save ``` --- # Mikrotik RouterOS Source: https://netboot.xyz/docs/kb/networking/mikrotik ### Assumptions - You are running RouterOS 7.12.1 or later - You have a DHCP server, whose name you will substitute in instead of DHCPSERVER - You have a DHCP address pool whose name you will substitute in instead of DHCPPOOL The steps referencing servers and pools can be repeated for as many servers and pools as you need. ### Disable BOOTP support for the server ``` /ip dhcp-server/set DHCPSERVER bootp-support=none ``` ### BIOS Download `netboot.xyz.kpxe` and register it to the TFTP server: ``` /tool fetch url="https://boot.netboot.xyz/ipxe/netboot.xyz.kpxe" /ip tftp add req-filename=netboot.xyz.kpxe real-filename=netboot.xyz.kpxe allow=yes read-only=yes ``` Add a DHCP option for the BIOS bootfile and add it to a BIOS PXE boot option set: ``` /ip dhcp-server option add code=67 name=pxe-bios-netboot.xyz value="'netboot.xyz.kpxe'" /ip dhcp-server/option/sets add name="pxe-bios" options=pxe-bios-netboot.xyz ``` Set the BIOS PXE boot option set as the server's option set. ``` /ip dhcp-server/set DHCPSERVER dhcp-option-set=pxe-bios ``` NOTE: If you have an existing option set, you should skip creating a new option set and should instead add the PXE BIOS bootfile option to your existing option set. ### UEFI Download `netboot.xyz.efi` and register it to the TFTP server: ``` /tool fetch url="https://boot.netboot.xyz/ipxe/netboot.xyz.efi" /ip tftp add req-filename=netboot.xyz.efi real-filename=netboot.xyz.efi allow=yes read-only=yes ``` Add a DHCP option for the UEFI bootfile and add it to a UEFI PXE boot option set: ``` /ip dhcp-server option add code=67 name=pxe-uefi-netboot.xyz value="'netboot.xyz.efi'" /ip dhcp-server/option/sets add name="pxe-uefi" options=pxe-uefi-netboot.xyz ``` Add a DHCP matcher that looks for the 0x0007 (x86-64 UEFI) architecture type and applies the PXE UEFI option set, overriding the default PXE BIOS options: ``` /ip dhcp-server/matcher/add name="pxe-uefi-matcher" server=DHCPSERVER address-pool=DHCPPOOL option-set=pxe-uefi code=93 value="0x0007" ``` --- # TFTP Filename Interpretation Issues with Older PXE Clients Source: https://netboot.xyz/docs/kb/networking/tftp-filename-issues ## Problem Description Older PXE clients (typically 10+ years old) may append extra characters to TFTP filenames, causing "File not found" errors. The issue manifests as Unicode replacement characters (�) or hex bytes (often 0xFF) being added to the end of requested filenames. ## Root Cause This is a UEFI PXE implementation bug related to DHCP filename handling: - **Technical Issue**: UEFI PXE clients incorrectly handle DHCP Option 67 (boot filename) - **Expected Behavior**: Option 67 should be treated as a variable-length field - **Actual Behavior**: Some implementations treat it as a null-terminated string, reading beyond the specified length - **Result**: Extra bytes from the DHCP packet get appended to the TFTP filename request ## Affected Hardware/Software ### Hardware - Jetway J7F4K1G5DS-LF and similar older boards - Lenovo T460 laptops - Z77X-UD3H motherboards with Atheros NICs - Kontron VX3040 Intel CPU boards - Generally affects Intel UNDI PXE-2.1 implementations from ~2000 era ### DHCP Servers **Problematic:** - Kea DHCP - UniFi USG devices (limited configuration options) - pfSense with Kea DHCP **Working Combinations:** - pfSense with deprecated isc-dhcp - Properly configured OpnSense/isc-dhcp setups ## Workarounds and Solutions ### 1. Server-Side File Naming (Recommended) Create boot files with the extra 0xFF byte in the filename: ```bash # Rename files to include the extra byte mv netboot.xyz.kpxe $(echo -en 'netboot.xyz.kpxe\xFF') mv netboot.xyz.efi $(echo -en 'netboot.xyz.efi\xFF') # Or create symlinks (cleaner approach) ln -s netboot.xyz.kpxe $(echo -en 'netboot.xyz.kpxe\xFF') ln -s netboot.xyz.efi $(echo -en 'netboot.xyz.efi\xFF') ``` ### 2. DHCP Configuration Changes For isc-dhcp servers, use the `boot-file-name` directive instead of Option 67: ```bash # In dhcp4 config, use boot-file-name at the top level boot-file-name "netboot.xyz.kpxe"; # Instead of in option-data ``` For pfSense users: Switch from Kea to the deprecated isc-dhcp service in System > Advanced > Networking. ### 3. Remove DHCP boot-filename Option Some users report success by removing the `option bootfile-name` directive entirely, though this may break other clients. ## Technical Details - The issue specifically affects DHCPv4 Option 67 handling - DHCPv6 does not have this problem due to its variable-length field design - RFC 2132 does not guarantee null termination of Option 67 filenames - UEFI 2.6 spec leaves line termination as an implementation detail ## Troubleshooting Steps 1. **Identify the issue**: Look for replacement characters (�) or extra bytes in TFTP server logs 2. **Packet capture**: Use tcpdump to verify extra bytes in TFTP requests 3. **Test workarounds**: Try the server-side filename solution first 4. **DHCP server evaluation**: Consider switching from Kea to isc-dhcp if possible ## Prevention - Use the `boot-file-name` directive in DHCP configuration instead of Option 67 - Test with known problematic hardware before deployment - Document affected clients in your environment ## References - [Issue discussion](https://github.com/netbootxyz/netboot.xyz/issues/1198) - [Technical analysis](https://binaryfury.wann.net/2024/12/pxe-two-tftp-filenames-one-dhcp-offer-plus-weird-filenames/) - UEFI Specification 2.6+ - RFC 2132 (DHCP Options) --- # Cherry Servers Source: https://netboot.xyz/docs/kb/providers/cherryservers [Cherry Servers](https://www.cherryservers.com/) supports iPXE installation on dedicated bare metal servers, including direct support for netboot.xyz. ### How iPXE Works on Cherry Servers Cherry Servers uses a custom iPXE implementation to work around the lack of native iPXE-over-DHCP support in standard MaaS infrastructure. On first boot: 1. A universal iPXE ISO is automatically attached to the server. 2. The server receives network configuration via DHCP. 3. Your selected iPXE script executes from RAM. 4. The OS installation begins. 5. The ISO disconnects automatically after five minutes. iPXE can be selected when deploying a new server, during a server rebuild, and is available on all dedicated bare metal servers (excluding Outlet servers). ### Boot with netboot.xyz Cherry Servers supports netboot.xyz as an iPXE option. When deploying or rebuilding a server, select iPXE as the installation method and set the chain URL to: https://boot.netboot.xyz Once the server boots, open the console in the Cherry Servers portal within five minutes to access the netboot.xyz menu and select your desired OS or tool. Supported systems include Ubuntu, Debian, Rocky Linux, Proxmox, Fedora, Arch Linux, Red Hat Enterprise Linux, Kali Linux, and many others, along with recovery and diagnostic tools such as Clonezilla, GParted, and Memtest86+. ### Further Reading Full iPXE documentation for Cherry Servers is available in their [knowledge base](https://www.cherryservers.com/knowledge/docs/compute/configuration-management/ipxe). --- # DigitalOcean Source: https://netboot.xyz/docs/kb/providers/digitalocean netboot.xyz can be loaded on a [DigitalOcean](https://m.do.co/c/ab4e8f17ba0d) droplet with a little bit of work so that you can then customize the droplet as needed. For this method, we'll use the smallest droplet size running Debian. :::info If you haven't signed up for a DigitalOcean account, please utilize our affiliate link [here](https://m.do.co/c/ab4e8f17ba0d). It will help provide us testing resources for improving this project! ::: ### Create a Droplet For this method, it's recommended to use an apt-based distro like Debian or Ubuntu. Start a droplet with one of those operating systems. Once it is up and running, connect to it via SSH or connect to it with the console button. ### Install GRUB Imageboot and Download ISO We will need to ensure that the GRUB menu pauses long enough for us to select the netboot.xyz option. For that we'll need to remove a timeout file and increase the timeout for GRUB. Adjust the time period as needed for your situation: ```shell # Remove grub timeout configuration rm /etc/default/grub.d/15_timeout.cfg # Increase grub timeout if desired sed -i 's/GRUB_TIMEOUT=5/GRUB_TIMEOUT=60/g' /etc/default/grub # Install grub-imageboot apt update apt install -y grub-imageboot # Download netboot.xyz ISO mkdir /boot/images cd /boot/images wget https://boot.netboot.xyz/ipxe/netboot.xyz.iso # Update GRUB menu to include this ISO update-grub2 # reboot once you are ready, it may be good to load up the recovery console first reboot ``` ### Connect via Recovery Console Under the access section, connect to the Recovery Console. The recovery console is different from the regular console command in that it allows direct access to the droplet as it boots, including access to the GRUB menu. At this point if you are within the timeout window, you should now see the Grub menu with the following option now available: ```bash Bootable ISO image: netboot.xyz ``` ### Set Networking Up Because the droplets use a static IP instead of DHCP, you will need to set up the networking for iPXE to talk to the networking. Upon selecting the netboot.xyz option, press **m** when prompted for the failsafe menu. You will need to set the networking of the instance so that iPXE can get on-line. You can get the networking information from the droplet control panel from the networking tab. Once you have the networking information, select Manual networking configuration: ```bash Set network interface number [0 for net0, defaults to 0]: IP: Subnet mask: Gateway: DNS: ``` Once set, you should connect right into netboot.xyz. If you do a installation, you should be able to reinstall over the existing drive at that point and customize the droplet as you see fit. Keep the networking information handy as you will need to populate that when doing an install. :::info If you run into out of memory issues running an installer, you may need a larger droplet. ::: --- # Google Compute Engine Source: https://netboot.xyz/docs/kb/providers/gce ## Using with netboot.xyz **Experimental, currently doesn't work on any images that utilize memdisk as console output cannot be altered.** *Note: Functionality will be limited as the console is Serial Over Lan. Distros that utilize memdisk may not provide output while other distros that are retrieved via kernel allow for altering of the console settings during load. This includes most of the utility tools. I'll probably look at filtering out options that don't work in the future. Console may work during the install but may stop working on first boot if it's not set during the install.* ### Create a Bucket Set a name for your bucket and select the regional storage class. Upload the netboot.xyz-gce image from this [link](https://boot.netboot.xyz/ipxe/netboot.xyz-gce.tar.gz) to the root of your bucket. ``` gsutil cp $tmp/$image_name.tar.gz gs://$gs_bucket ``` ### Create an image Using the gcloud utility or the Google Cloud Shell, create an image from the iPXE disk you uploaded in the previous step: ``` gcloud compute images create $image_name --source-uri gs://$gs_bucket/$image_name.tar.gz ``` ### Boot an instance Start an instance from the image you created, make sure to enable the serial-port: ``` gcloud compute instances create $instance_name --image $image_name --metadata serial-port-enable=1 ``` ### Connect to the Instance over Serial Console ``` gcloud beta compute connect-to-serial-port $instance_name ``` From here you should see the netboot.xyz menu and that's probably all you'll be able to do at this point. :) ### Configuring the Instance In the event DHCP does not work, you'll need to set the static IP address during install time. You can view this by going into instance details in the console, and clicking on default under network. You'll need to set the internal IP of the instance along with the subnet and gateway on that page. ### Notes Here are some notes on how the iPXE image is created in case you want to play around with vanilla iPXE in GCE. See the iPXE commit [here](https://github.com/ipxe/ipxe/commit/de85336abb7861e4ea4df2e296eb33d179c7c9bd) for more info of GCE support in iPXE. To create a usable image for GCE: ``` make bin/ipxe.usb CONFIG=cloud EMBED=$tmp/main.ipxe cp -f bin/ipxe.usb $tmp/disk.raw ( cd $tmp; tar Sczvf $image_name.tar.gz disk.raw ) ``` To get the installers to work to output serial, when the GCE disk is detected, the console on the kernel command line is set to: ``` console=ttyS0,115200n8 ``` ## Using without netboot.xyz (standard iPXE) When building your script, you will want it to look something like this: ``` #!ipxe echo Google Compute Engine - iPXE boot via metadata ifstat || dhcp || route || chain -ar http://metadata.google.internal/computeMetadata/v1/instance/attributes/ipxeboot ``` Then when provisioning your instance, you can specify your custom iPXE script file: ``` # Create shared boot image make bin/ipxe.usb CONFIG=cloud EMBED=config/cloud/gce.ipxe # Configure per-instance boot script gcloud compute instances add-metadata \ --metadata-from-file ipxeboot=boot.ipxe ``` This lets your custom compiled iPXE boot and then immediately chain to your custom iPXE script. --- # Linode Source: https://netboot.xyz/docs/kb/providers/linode netboot.xyz can be loaded on a [Linode](https://linode.com) instance so that you can then customize the Linode as needed. For this method, we'll use the smallest Linode size running Debian. ### Create a Linode For this method, it's recommended to use an apt-based distro like Debian or Ubuntu. Start a Linode with one of those operating systems. Once it is up and running, connect to it via SSH or connect to it with the console button. ### Install GRUB Imageboot and Download ISO We will need to ensure that the GRUB menu pauses long enough for us to select the netboot.xyz option. For that we'll need to remove a timeout file and increase the timeout for GRUB. Adjust the time period as needed for your situation: ```shell # Increase grub timeout if desired sed -i 's/GRUB_TIMEOUT=5/GRUB_TIMEOUT=60/g' /etc/default/grub # Install grub-imageboot apt update apt install -y grub-imageboot # Download netboot.xyz ISO mkdir /boot/images cd /boot/images wget https://boot.netboot.xyz/ipxe/netboot.xyz.iso # Update GRUB menu to include this ISO update-grub2 # reboot once you are ready, it may be good to load up the recovery console first reboot ``` ### Launch LISH Console Under the Linode settings click ..., and select Launch LISH Console. For interraction with the GRUB Menu and netboot.xyz menus, you will need to click the Weblish tab. For interacting with an installer or other tool, you may need to use the Glish tab (Graphical). At this point if you are within the timeout window, you should now see the Grub menu with the following option now available which you can select to load the netwboot.xyz menu: ```bash Bootable ISO image: netboot.xyz ``` ### Networking Linode uses DHCP so netboot.xyz should be able to get an IP address and load up the menu. If DHCP does not work, you may need to use the alternative failsafe menu to set up the networking for the instance manually by pressing **m** when prompted for the failsafe menu. If you do a installation, you should be able to reinstall over the existing drive at that point and customize the Linode as you see fit. Keep the networking information handy as you will need to populate that when doing an install. :::info If you run into out of memory issues running an installer, you may need a larger Linode. ::: --- # Oracle Cloud Infrastructure Source: https://netboot.xyz/docs/kb/providers/oci netboot.xyz can be loaded on [OCI](https://www.oracle.com/cloud/) compute instances so that you can then customize the compute instance as needed. For this method, we'll use the standard Ubuntu image for the relevant architecture. ### Create a compute instance When creating an instance, make sure to select: - Image: Ubuntu > Canonical Ubuntu (standard, not minimal) Take note of which shape you take, as it will determine further steps: - AMD (`x86_64`) - Ampere A1 (`arm64`) :::warning Set up SSH keys! You will need to log into the server and there is no default password. We assume you know how to use SSH keys. ::: ### Get into the rescue shell First get onto your compute instance's details page, then scroll down to `Resources` under which you'll find `Console connection`. To get into the rescue shell, we recommend you use the Cloud Shell, and not bother with a `local connection`. To do so, click on `Launch Cloud Shell connection` and wait for the console connection status to reach the `ACTIVE` state. Be patient, it can take a minute or two. You do not need to log in, as we'll only use it control the UEFI Firmware. ### Download the EFI binary, Setup GRUB and Reboot into UEFI Now that you have the rescue shell open, you need to open a SSH connection to entere the following commands, as there is no default password. Follow the instructions depending on which architecture/shape you chose earlier: `arm64` or `x86_64`. :::info The rescue shell over the Oracle Cloud Shell can be somewhat buggy, for instance, you might have to press the Escape key twice instead of only once when in netboot.xyz ::: #### `arm64` - Ampere A1 These steps apply to the Ampere A1 (`arm64`) instances. The default GRUB configuration already contains the `UEFI Firmware` option, so we only have to download netboot.xyz and reboot into the correct option. ```shell # Download netboot (arm64) into the EFI directory sudo wget -O /boot/efi/netboot.xyz-arm64.efi https://boot.netboot.xyz/ipxe/netboot.xyz-arm64.efi # Set the default boot entry (for the following boot only) to the UEFI firmware sudo grub-reboot "UEFI Firmware Settings" # Reboot the instance sudo reboot ``` #### `x86_64` - AMD These steps apply to the AMD/Intel (`x86_64`) instances. We need to delete the default GRUB configuration and regenerate it, as it does not contain `UEFI Firmware`. Then, we can reboot into the UEFI Firmware and boot into netboot.xyz: ```shell # Download netboot (amd64) into the EFI directory sudo wget -O /boot/efi/netboot.xyz-snp.efi https://boot.netboot.xyz/ipxe/netboot.xyz-snp.efi # Delete the default configuration (does not contain UEFI Firmware by default) sudo rm -rf /etc/default/grub /etc/default/grub.d/ # Update GRUB menu (with default configuration) sudo update-grub # Set the default boot entry (for the following boot only) to the UEFI firmware sudo grub-reboot "UEFI Firmware Settings" # Reboot sudo reboot ``` ### Boot into netboot.xyz Now that you are in the UEFI Firmware, do the following: - Choose “Boot Maintenance Manager” - Choose “Boot From File” - Choose the only device - Choose the netboot.xyz EFI file - Wait for it to start and configure :::tip If you were not able to boot into netboot.xyz correctly, simple repeat the `grub-reboot` and `reboot` steps to enter UEFI again. ::: #### `x86_64` - Console quirks: Linux Once you have booted into netboot.xyz on `x86_64`, if you plan on using Linux images, you must still set up custom `Kernel cmdline params` under `Utilities (UEFI)`. Set `Kernel cmdline params: []` to `console=ttyS0,9600`. If you make a mistake, move with arrow keys, and use the Delete key. Once you have typed it in, you might have to press the Escape key twice. :::warning This is **not** applicable to `arm64`/Ampere A1. ::: --- # OpenStack Source: https://netboot.xyz/docs/kb/providers/openstack **Experimental, haven't had a chance to run through this recently so YMMV.** The netboot.xyz ISO image can be used with OpenStack clouds to boot an instance and perform a custom installation of an operating system. ### Command line Start by downloading the ISO and then import it into glance: ``` $ wget https://boot.netboot.xyz/ipxe/netboot.xyz.iso $ glance image-create --name netboot.xyz \ --disk-format iso \ --container-format bare \ --file netboot.xyz-dhcp.iso \ --visibility public +------------------+--------------------------------------+ | Property | Value | +------------------+--------------------------------------+ | checksum | 45cdcb89576b6c05598b11585aef46bc | | container_format | bare | | created_at | 2016-01-27T20:02:06Z | | disk_format | iso | | id | 4f11d49e-157b-4740-87ad-db7d59bb5d6d | | min_disk | 0 | | min_ram | 0 | | name | netboot.xyz | | owner | fbfce4cb346c4f9097a977c54904cafd | | protected | False | | size | 1048576 | | status | active | | tags | [] | | updated_at | 2016-01-27T20:02:04Z | | virtual_size | None | | visibility | public | +------------------+--------------------------------------+ ``` It should only take a few seconds to import. Take the UUID from the `id` field returned by glance and verify that the image imported successfully: ``` $ glance image-show 4f11d49e-157b-4740-87ad-db7d59bb5d6d +------------------+--------------------------------------+ | Property | Value | +------------------+--------------------------------------+ | checksum | 45cdcb89576b6c05598b11585aef46bc | | container_format | bare | | created_at | 2016-01-27T20:02:06Z | | disk_format | iso | | id | 4f11d49e-157b-4740-87ad-db7d59bb5d6d | | min_disk | 0 | | min_ram | 0 | | name | netboot.xyz | | owner | fbfce4cb346c4f9097a977c54904cafd | | protected | False | | size | 1048576 | | status | active | | tags | [] | | updated_at | 2016-01-27T20:02:04Z | | virtual_size | None | | visibility | public | +------------------+--------------------------------------+ ``` The image has a status of `active`, so we know that glance imported it properly. Let's boot a new instance with this ISO: ``` nova boot --flavor m1.small \ --image \ --nic net-id= \ netbootxyz-testing ``` Wait about 30 seconds, then request a console URL: ``` nova get-spice-console c4ff017e-1234-4053-b740-e83eade277b9 spice-html5 ``` Open the console URL that nova returns and you should see the familiar netboot.xyz iPXE interface in the spice console! ### Horizon Start by [downloading the netboot.xyz ISO](https://boot.netboot.xyz/ipxe/netboot.xyz.iso) to your local workstation. Follow these steps to import the image into your OpenStack cloud using Horizon: * Click the _Compute_ tab on the left side, then click _Images_ * Click _Create Image_ (top right) * Name: `netboot.xyz ISO` * Image Source: Image File * Image File: (browse to the ISO you downloaded) * Format: ISO - Optical Disk Image * Public: Checked (optional, but recommended if you want other tenants to use it) * Click _Create Image_ Wait a moment for the status to become `active`. This should only take a few seconds. To boot an instance with the ISO you uploaded, be sure to choose _Boot from image_ and select _netboot.xyz ISO_ from the drop down list. Configure networking and security groups as you normally would for any other instance. When the instance has fully built and gone to active status, click on the instance name and then go to the _Console_ tab. Depending on your browser, you may need to click the link to show only the console. At that point, you should be able to view the netboot.xyz iPXE menu and install your operating system. --- # Vultr Source: https://netboot.xyz/docs/kb/providers/vultr [Vultr](http://www.vultr.com/?ref=6870843) has some great support for using netboot.xyz right out of the box. :::info If you have not signed up for a Vultr account yet, please utilize our affiliate link [here](http://www.vultr.com/?ref=6870843). It will help provide us testing resources for improving this project! ::: ### Boot from ISO Once you've logged into the console, select ISOs. In the remote URLs box, enter in the URL of a netboot.xyz ISO and press upload: https://boot.netboot.xyz/ipxe/netboot.xyz.iso Go back to the main console screen and press "Deploy New Instance". Follow these steps: * Select _Custom_ for the operating system * Select the ISO you uploaded * Click _Place Order_ The instance should be online in a few minutes. Once it's online, go to the main account page that lists all of your instances. Click _Manage_ next to the instance you just launched, and then click _View Console_ under _Server Actions_. When the console appears, you should see the netboot.xyz iPXE menu. When you've completed the OS installation, select _Custom ISO_ from the Server Manager page and click _Remove ISO_. The ISO will be removed from your instance and it will reboot. ### Boot from iPXE Chain URL Using an iPXE chain url may be easier for some users. Follow these steps: * Click _Deploy New Instance_ * Select _Custom_ for the operating system * Select _iPXE_ in the Virtual ISO section * Set the chain URL to `https://boot.netboot.xyz` * Click _Place Order_ The instance will boot within a few minutes. Once it boots, you'll have five minutes to launch a console and choose an option from the netboot.xyz menu: * Go back to your account home page with your instances listed * Click _Manage_ next to the instance you just launched * Click _View Console_ in the _Server Actions_ section * Choose the OS you want to deploy in the netboot.xyz menu * Complete the OS installation Once you've finished the installation, reboot the instance as you normally would. Vultr will automatically reboot your virtual machine into the OS you deployed. ### Boot from iPXE on a Vultr Bare Metal Server On Vultr Bare Metal, you can find the iPXE options in the iPXE tab in the Server Type section. * Set the chain URL to `https://boot.netboot.xyz` Make sure to use Legacy (PCBIOS) images because Bare Metal does not support EFI at this time. You can then load the console up and use the menu from there. --- # PXE Booting the AlmaLinux Installer Source: https://netboot.xyz/docs/kb/pxe/almalinux ## Installer Kernels AlmaLinux maintains installer kernels that are a lightweight way to load the installer and then stream packages over the network as needed. The installer kernels are located at: | URL | Description | | --- | ----------- | | `http://repo.almalinux.org`| Base URL for AlmaLinux mirrors | | `almalinux/${version}/BaseOS/${arch}/os/images/pxeboot/` | Directory containing the installer kernels | | `${version}` | Version (e.g., 8, 9, etc) | | `${arch}` | Architecture (e.g., x86_64, aarch64) | | `vmlinuz` | Kernel filename | | `initrd.img` | Initrd filename | In order to load them, you'll need to use a boot snippet in iPXE similar to: ```bash set install_params inst.ks=http://my.kickstart.com/ks.cfg inst.repo=http://repo.almalinux.org/almalinux/$version/BaseOS/$arch/os/ set mirror http://repo.almalinux.org set base_dir almalinux set version 8 set arch x86_64 set dir ${mirror}/${base_dir}/${version}/BaseOS/${arch}/os/images/pxeboot kernel ${dir}/vmlinuz ${install_params} -- quiet initrd ${dir}/initrd.img boot ``` If you want to use a [Kickstart](https://wiki.almalinux.org/documentation/kickstart.html) URL for automation, you can add this to the kernel line: ```bash set ksurl http://my.kickstart.com/ks.cfg inst.ks=${ksurl} ``` For more examples, you can view the netboot.xyz configuration for AlmaLinux [here](https://github.com/netbootxyz/netboot.xyz/blob/master/roles/netbootxyz/templates/menu/almalinux.ipxe.j2). --- # PXE Booting the Debian Installer Source: https://netboot.xyz/docs/kb/pxe/debian ## Installer Kernels Debian maintains installer kernels that are a lightweight way to load the Debian installer and then stream packages over the network as needed. The installer kernels are located at: | URL | Description | | --- | ----------- | | `http://deb.debian.org` | Base URL for Debian mirrors | | `debian/dists/${version}/main/installer-${arch}/current/images/netboot/` | Directory containing the installer kernels | | `${version}` | Version (e.g., bullseye, bookworm, etc) | | `${arch}` | Architecture (e.g., amd64, arm64) | | `linux` | Kernel filename | | `initrd.gz` | Initrd filename | In order to load them, you'll need to use a boot snippet in iPXE similar to: ```bash set install_params auto=true priority=critical set mirror http://deb.debian.org set base_dir debian set debian_version bookworm set arch amd64 set mirrorcfg mirror/suite=${debian_version} set dir ${mirror}/${base_dir}/dists/${version}/main/installer-${arch}/current/images/netboot/debian-installer/amd64/ kernel ${dir}/linux ${install_params} ${mirrorcfg} -- quiet initrd=initrd.gz initrd ${dir}/initrd.gz boot ``` If you want to use a [preseed](https://www.debian.org/releases/stable/amd64/apb.en.html) URL for automation, you can add this to the kernel line: ```bash set preseedurl http://my.preseed.com/preseed.cfg preseed/url=${preseedurl} ``` For more examples, you can view the netboot.xyz configuration for Debian [here](https://github.com/netbootxyz/netboot.xyz/blob/master/roles/netbootxyz/templates/menu/debian.ipxe.j2). ## Live Boot Debian also provides a number of Live Boot ISOs that will boot an OS directly into memory and can be used immediately without doing an install or modifying the hard drive. The Live OS will also include the installer as well. These are great for evaluating other desktops that you might want to try out without doing a full install. | Distribution | Website | | :--- | :--- | | Debian Live | [https://www.debian.org/CD/live/](https://www.debian.org/CD/live/) | --- # PXE Booting the Rocky Linux Installer Source: https://netboot.xyz/docs/kb/pxe/rockylinux ## Installer Kernels Rocky Linux maintains installer kernels that are a lightweight way to load the installer and stream packages over the network as needed. Rocky Linux is a binary compatible clone of RHEL (Red Hat Enterprise Linux) and is already supported by numerous large, financially strong sponsors. The installer kernels are located at: | URL | Description | | --- | ----------- | | `http://dl.rockylinux.org` | Base URL for Rocky Linux mirrors | | `pub/rocky/${version}/BaseOS/${arch}/os/images/pxeboot/` | Directory containing the installer kernels | | `${version}` | Version (e.g., 8, 9, etc) | | `${arch}` | Architecture (e.g., x86_64, aarch64) | | `vmlinuz` | Kernel filename | | `initrd.img` | Initrd filename | In order to load them, you'll need to use a boot snippet in iPXE similar to: ```bash set install_params inst.ks=http://my.kickstart.com/ks.cfg inst.repo=http://dl.rockylinux.org/pub/rocky/${version}/BaseOS/${arch}/os set mirror http://dl.rockylinux.org set base_dir pub/rocky set version 9 set arch x86_64 set dir ${mirror}/${base_dir}/${version}/BaseOS/${arch}/os/images/pxeboot kernel ${dir}/vmlinuz ${install_params} -- quiet initrd ${dir}/initrd.img boot ``` If you want to use a [Kickstart](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/automated-installation-workflow_rhel-installer) URL for automation, you can add this to the kernel line: ```bash set ksurl http://my.kickstart.com/ks.cfg inst.ks=${ksurl} ``` For more examples, you can view the netboot.xyz configuration for Rocky Linux [here](https://github.com/netbootxyz/netboot.xyz/blob/master/roles/netbootxyz/templates/menu/rockylinux.ipxe.j2). --- # PXE Booting the Ubuntu Installer Source: https://netboot.xyz/docs/kb/pxe/ubuntu ## Installer Kernels Ubuntu maintains installer kernels that are a lightweight way to load the Ubuntu installer and then stream packages over the network as needed. The installer kernels are located at: | URL | Description | | --- | ----------- | | `http://archive.ubuntu.com` | Base URL for Ubuntu mirrors | | `${version}` | Version (e.g., focal, jammy, etc) | | `${arch}` | Architecture (e.g., amd64, arm64) | | `ubuntu/dists/${version}/main/installer-${arch}/current/images/netboot/` | Directory containing the installer kernels | | `linux` | Kernel filename | | `initrd.gz` | Initrd filename | In order to load them, you'll need to use a boot snippet in iPXE similar to: ```bash set mirror http://releases.ubuntu.com set base_dir ubuntu set codename jammy set version_number 22.04 set os_arch amd64 set mirrorcfg mirror/suite=${ubuntu_version} set dir ${mirror}/${base_dir}/dists/${version}/main/installer-${arch}/current/images/netboot set ubuntu_iso_url http://releases.ubuntu.com/${codename}/ubuntu-${version_number}-live-server-${os_arch}.iso set install_params autoinstall ip=dhcp ds=nocloud-net;s=http://my.autoinstall.com/ url=${ubuntu_iso_url} kernel ${dir}/linux ${install_params} ${mirrorcfg} -- quiet initrd=initrd.gz initrd ${dir}/initrd.gz boot ``` If you want to use an [autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/howto/autoinstall-quickstart.html) URL for automation, you can add this to the kernel line: ```bash set autoinstall_url http://my.autoinstall.com/ autoinstall ds=nocloud-net;s=${autoinstall_url} ``` For more examples, you can view the netboot.xyz configuration for Ubuntu [here](https://github.com/netbootxyz/netboot.xyz/blob/master/roles/netbootxyz/templates/menu/ubuntu.ipxe.j2). ## Live Boot Ubuntu also provides a number of Live Boot ISOs that will boot an OS directly into memory and can be used immediately without doing an install or modifying the hard drive. The Live OS will also include the installer as well. These are great for evaluating other desktops that you might want to try out without doing a full install. | Distribution | Website | | :--- | :--- | | Kubuntu | [https://kubuntu.org/](https://kubuntu.org/) | | Lubuntu | [https://lubuntu.me/](https://lubuntu.me/) | | Ubuntu Budgie | [https://ubuntubudgie.org/](https://ubuntubudgie.org/) | | Ubuntu Kylin | [https://www.ubuntukylin.com/](https://www.ubuntukylin.com/) | | Ubuntu Mate | [https://ubuntu-mate.org/](https://ubuntu-mate.org/) | | Ubuntu Studio | [https://ubuntustudio.org/](https://ubuntustudio.org/) | | Xubuntu | [https://xubuntu.org/](https://xubuntu.org/) | --- # Installing Windows via PXE Network Boot with netboot.xyz Source: https://netboot.xyz/docs/kb/pxe/windows # Installing Windows with netboot.xyz This guide will walk you through installing Windows 11 using netboot.xyz using the netboot.xyz Docker container. ## Requirements Before you begin, ensure you have the following: - A Samba (SMB, CIFS) share with the Windows 11 ISO extracted. - A Windows PE image as an ISO. Instructions on how to build it can be found [here](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-create-usb-bootable-drive#create-a-winpe-iso-dvd-or-cd). - The netboot.xyz Docker container set up and running. Follow the instructions [here](../../docker/usage.md) to set up the container. :::note WinPE is used so you can preload any drivers you may need for the equipment being installed. You may need to slipstream drivers like VirtIO if using Proxmox or other types of virtualization. ::: ## Installation Process To start, download the Windows PE image and the Windows 11 ISO. Once you have these files, set up an SMB share and extract the Windows 11 ISO to a directory on this share. Next, upload the Windows PE image to the netboot.xyz container's `/assets/WinPE/x64/` folder. With the files in place, boot the netboot.xyz menu and navigate to the Windows section. You'll need to set the base URL to point to the container's IP address, the correct Nginx port for hosting assets, and the right directory. For example: ```bash http://192.168.2.46:8000/WinPE ``` Load the installer, and you should be prompted with a terminal. In the terminal, type `wpeinit` to load networking support. Then, mount the Windows ISO share using the following command: ```bash net use F: \\\ /user:\ ``` :::note The terminal uses the US keyboard layout by default. ::: Change into the mounted share (`F:`) and execute `setup.exe`: ```bash F:\setup.exe ``` You should now see the normal Windows setup interface and be able to proceed with the installation. ## Persistent URL for Windows with Docker Container To avoid entering the URL each time you boot Windows, you can use the `local-vars.ipxe` file to set the `win_base_url`. This file is checked early during the boot process and allows you to set overrides for variables. Edit the `local-vars.ipxe` file within the web configuration interface and add the following line: ```bash set win_base_url http://192.168.2.46:8080/WinPE ``` With this configuration, you won't need to input the URL anymore when booting Windows. :::note If you don't currently have a [local-vars.ipxe](https://github.com/netbootxyz/netboot.xyz/blob/development/roles/netbootxyz/templates/local-vars.ipxe.j2) file, you can create on in the root of the tftp directory. ::: --- # Quick Start Source: https://netboot.xyz/docs/quick-start [Download](https://netboot.xyz/downloads/) one of the netboot.xyz bootloaders that works best for your situation and start PXE booting your favorite operating system. The bootloaders are precompiled versions of the latest version of [iPXE](https://github.com/ipxe/ipxe) that will allow you to PXE boot into [https://boot.netboot.xyz](https://boot.netboot.xyz). If you have DHCP it'll automatically attempt to boot from DHCP. If you need to set a static IP address, hit the **`m`** key during boot up for the failsafe menu and choose manual network configuration. You can look at the next section entitled [Booting Methods](https://netboot.xyz/docs/category/booting-methods) for instructions on how to set up the downloaded bootloader. If you already have iPXE up and running on the network, you can hit load the netboot.xyz kernel by typing the following when loaded in a Legacy Mode BIOS: ``` chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.lkrn ``` or when in EFI mode BIOS: ``` chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.efi ``` This will load the appropriate netboot.xyz kernel with all of the proper options enabled. You can also boot into netboot.xyz using a local UEFI executable. This method involves placing the UEFI executable on the EFI system partition and configuring the UEFI boot manager to boot from it. For more details, refer to the [Booting from a Local UEFI Executable](https://netboot.xyz/docs/booting/uefi) guide. :::info If your version of iPXE has HTTPS support compiled in, you can retrieve those images over HTTPS. By default the upstream iPXE project does not compile in HTTPS support. ::: ### System Requirements - i686, x86_64, or aarch64 Processor - Bare Metal or Virtual Machine - A hard wired ethernet connection (WiFi networking is not supported) - At least 4GB of RAM is recommended :::info Memory requirements vary depending on the distribution. Live CD Images typically require a lot more memory as the ramdisk is needed to be loaded into memory. Live CD Images loaded over the network may need more than 4GB. If you experience issues where it fails to load during the initrd process, try giving the hardware or virtual machine more RAM. You will typically see errors like `out of space` or `failure to write to destination` in the initrd once the kernel has loaded if you don't have enough RAM. ::: ### Source Code The source code for netboot.xyz is located on [Github](https://github.com/netbootxyz/netboot.xyz). If you enjoy the project, make sure to give it a star! ### Contributing Is there a new version of an operating system out? Have you found one that network boots well with iPXE? Pull requests are welcomed and encouraged and helps out the project! Feel free to issue a pull request for new versions or tools that you might find useful. Once merged into master, [Github Actions](https://github.com/netbootxyz/netboot.xyz/actions) will regenerate new versions of [iPXE from upstream](https://github.com/ipxe/ipxe) and deploy the latest changes to netboot.xyz. See more on contributing [here](https://netboot.xyz/docs/contributing). ### Testing New Features Under the **Utilities** menu on netboot.xyz, there's an option for ["netboot.xyz endpoints"](https://github.com/netbootxyz/netboot.xyz/blob/development/roles/netbootxyz/templates/menu/nbxyz.ipxe.j2). Features or changes that have been merged into the development branch can be loaded here to be tested before they are merged into production. :::info Version updates are typically deployed to the development endpoint and the primary rolling endpoint at the same time automatically. Once the development branch stabilizes, a new release is cut from the development branch and merged into master. This provides our stable point releases and releases new changes and capabilities related to menus or new features. ::: ### Communication Feel free to open up an [issue](https://github.com/netbootxyz/netboot.xyz/issues/new/choose) on Github or join us on our [Discord](https://discord.gg/An6PA2a) server. Follow us on [Twitter](https://twitter.com/netbootxyz) or like us on [Facebook](https://www.facebook.com/netboot.xyz)! ### Next Steps - [Self Hosting](./selfhosting.md) — run your own netboot.xyz server with Docker or Ansible - [Docker Container](./docker/overview.md) — set up the netboot.xyz Docker container with a web UI - [Troubleshooting](./troubleshooting/index.md) — common issues and how to resolve them - [FAQ](./faq.md) — frequently asked questions about the project --- # Self Hosting Source: https://netboot.xyz/docs/selfhosting ### How can I self host netboot.xyz? netboot.xyz was originally a hosted only tool and used static source files that were difficult to customize. Now you can generate your own self hosted environment using the same tooling to generate the hosted site. [Ansible](https://www.ansible.com/), an open-source automation engine, is utilized to generate custom templates based on a set of default configurations which can then be overridden by the user. This allows a user to customize a netboot.xyz environment to their specification and set up a PXE server easily. The Ansible playbooks will generate: * Menus for their netboot.xyz environment using default configuration settings * iPXE Bootloaders for booting into that environment * Customized menu options for those who have additional options they want to add #### Role structure The netbootxyz Ansible [role](https://github.com/netbootxyz/netboot.xyz/tree/master/roles/netbootxyz) is located in the main netboot.xyz repository. Most of the logic for netboot.xyz is contained in these areas: * `defaults/main.yml` - Consists default settings for deployment, OS versions, Utilities, and Bootloaders * `tasks/*` - Contains all tasks for rendering templates and compiling iPXE bootloaders * `templates/disks` - Templates for iPXE bootloaders * `templates/menus` - Templates for netboot.xyz menus * `vars/*` - Contain required package lists needed to support the compile and deployment of netboot.xyz #### Deploying using Ansible To run a deployment using Ansible, install Ansible, Apache and git: ```shell sudo apt install -y ansible git apache2 ``` ```bash sudo dnf install -y ansible git httpd ``` Then check out the netboot.xyz repo: ```bash git clone https://github.com/netbootxyz/netboot.xyz.git /opt/netboot.xyz ``` Finally run the Ansible playbook: ```bash cd /opt/netboot.xyz ansible-playbook -i inventory site.yml ``` The output will be dropped into `/var/www/html` by default. You can override this to deploy to the web server directory of your choice. #### Deploying with Docker You can also leverage Docker to generate the netboot.xyz menu and disks in a container which then outputs the results of the rendered templates and compiled iPXE disks into a directory. First ensure you have Docker installed and then run: ```bash docker build -t localbuild -f Dockerfile . docker run --rm -it -v $(pwd):/buildout localbuild ``` The build output will be in the generated folder `buildout`. Docker provides a consistent and isolated environment for generating the build output. From there you'd drop the files into the root of your favorite web server. #### Local Overrides Ansible will handle source generation as well as iPXE disk generation with your settings. It will generate Legacy (PCBIOS) and UEFI iPXE disks that can be used to load into your netboot.xyz environment. If you want to override the defaults, you can put overrides in user_overrides.yml. See [`user_overrides.yml`](https://github.com/netbootxyz/netboot.xyz/blob/master/user_overrides.yml) for examples. Using the overrides file, you can override all of the settings from the defaults/main.yml so that you can easily change the boot mirror URLs when the menus are rendered. If you prefer to do this after the fact, you can also edit the boot.cfg to make changes, but keep in mind those changes will not be saved when you redeploy the menu. #### Self Hosted Custom Options In addition to being able to host netboot.xyz locally, you can also create your own custom templates for custom menus within netboot.xyz. Those templates are rendered during deployment and are available from the main menu via the custom menu option. When these options are set: ```bash custom_generate_menus: true custom_templates_dir: "{{ netbootxyz_conf_dir }}/custom" ``` The menu will add an option for custom menus and attempt to load into custom/custom.ipxe. From there custom options can be built and maintained separately from the netboot.xyz source tree so that both menus can be updated independently. A sample menu is provided to demonstrate how to configure and set up a menu. You can copy the custom directory from the repo: ```bash cp etc/netbootxyz/custom /etc/netbootxyz/custom ``` --- # Common Error Codes Source: https://netboot.xyz/docs/troubleshooting/common-error-codes # Common Error Codes and Solutions This guide explains the most common error codes you might encounter when using netboot.xyz and how to resolve them. ## PXE Error Codes ### PXE-E32: TFTP Open Timeout **What it means:** The system cannot connect to the TFTP server within the timeout period. **Common causes:** - Network connectivity issues - TFTP server not responding - Firewall blocking TFTP traffic (port 69) - Incorrect TFTP server address **Solutions:** ```bash # Check network connectivity ping boot.netboot.xyz # Verify TFTP is accessible tftp boot.netboot.xyz > get netboot.xyz.kpxe > quit # Check firewall rules sudo iptables -L | grep 69 ``` ### PXE-E51: No DHCP or ProxyDHCP Offers Were Received **What it means:** The system cannot get network configuration from DHCP. **Common causes:** - DHCP server is down or unreachable - Network cable issues - DHCP pool exhausted - Network adapter not supported **Solutions:** 1. **Check DHCP server status:** ```bash sudo systemctl status isc-dhcp-server # or sudo systemctl status dhcpd ``` 2. **Verify DHCP configuration:** ```bash # Check DHCP pool availability dhcp-lease-list ``` 3. **Test network connectivity:** ```bash # On DHCP server, check if client is visible tail -f /var/log/syslog | grep dhcp ``` ### PXE-E53: No Boot Filename Received **What it means:** DHCP server didn't provide boot filename information. **Common causes:** - Missing DHCP Option 67 (boot filename) - Incorrect boot filename configuration - DHCP server doesn't support PXE **Solutions:** ```bash # Add to DHCP server configuration: option bootfile-name "netboot.xyz.kpxe"; # or for UEFI: option bootfile-name "netboot.xyz.efi"; ``` ### PXE-M0F: Exiting PXE ROM **What it means:** PXE boot process was interrupted or cancelled. **Common causes:** - User pressed Ctrl+C or ESC - Timeout waiting for user input - PXE boot disabled in BIOS **Solutions:** 1. **Check BIOS settings:** - Ensure PXE boot is enabled - Set appropriate boot timeout - Verify boot order includes network 2. **Don't interrupt the process:** - Let PXE boot complete automatically - Avoid pressing keys during initial boot ## iPXE Error Codes ### iPXE Error 0x3e1a6001: Connection timed out **What it means:** Network connection to remote server timed out. **Common causes:** - Slow internet connection - Server overloaded - DNS resolution issues - Firewall blocking HTTPS **Solutions:** ```bash # Test DNS resolution nslookup boot.netboot.xyz # Test HTTPS connectivity curl -I https://boot.netboot.xyz # Try alternative endpoints # Set different URL in iPXE: chain https://github.netboot.xyz/ ``` ### iPXE Error 0x3c092003: Operation not supported **What it means:** The requested operation is not supported by the current iPXE build. **Common causes:** - HTTPS not supported in iPXE build - Missing crypto support - Incompatible iPXE version **Solutions:** 1. **Use different bootloader:** ``` # Try different iPXE variants: - netboot.xyz.kpxe (standard) - netboot.xyz-undionly.kpxe (UNDI only) - netboot.xyz.efi (UEFI) ``` 2. **Check iPXE build features:** ``` # In iPXE command line: ipxe> help # Look for HTTPS, crypto support ``` ### iPXE Error 0x2f038001: No such file or directory **What it means:** The requested file could not be found on the server. **Common causes:** - Incorrect file path - File moved or deleted - Server configuration issues **Solutions:** ```bash # Verify file exists: curl -I https://boot.netboot.xyz/ipxe/netboot.xyz.lkrn # Check alternative paths: https://boot.netboot.xyz/ipxe/ https://github.netboot.xyz/ipxe/ ``` ## HTTP Error Codes ### HTTP 404: Not Found **What it means:** The requested resource is not available on the server. **Common causes:** - Incorrect URL - File has been moved - Temporary server issue **Solutions:** 1. **Check URL spelling:** ``` # Correct format: https://boot.netboot.xyz/ipxe/filename ``` 2. **Try alternative sources:** ``` # GitHub mirror: https://github.netboot.xyz/ipxe/filename ``` ### HTTP 503: Service Unavailable **What it means:** The server is temporarily unable to handle the request. **Common causes:** - Server maintenance - High server load - CDN issues **Solutions:** 1. **Wait and retry:** ``` # Wait 5-10 minutes and try again # Check status page if available ``` 2. **Use alternative endpoints:** ``` # Try different server: chain https://github.netboot.xyz/ ``` ## OS-Specific Error Codes ### Linux Kernel Panic **Common error messages:** - "Kernel panic - not syncing: VFS: Unable to mount root fs" - "Out of memory: Kill process" **Solutions:** 1. **Memory issues:** ``` # Ensure minimum RAM requirements: - Ubuntu: 1GB minimum, 2GB recommended - CentOS/RHEL: 1GB minimum - Arch Linux: 512MB minimum ``` 2. **Root filesystem issues:** ``` # Try different installation method: - Use netinstall instead of live image - Check disk for errors before installation ``` ### Windows Boot Errors **Common error codes:** - 0xc0000225: Boot configuration data is missing - 0x0000007B: INACCESSIBLE_BOOT_DEVICE **Solutions:** 1. **UEFI vs BIOS compatibility:** ``` # Ensure boot mode matches installation: - UEFI installation requires UEFI boot - Legacy BIOS installation requires Legacy boot ``` 2. **Storage driver issues:** ``` # Load appropriate drivers during installation # Use different Windows version if hardware not supported ``` ## Debugging Tools and Commands ### iPXE Command Line ```bash # Access iPXE shell (press Ctrl+B during boot) ipxe> help # Show available commands ipxe> config # Show current configuration ipxe> ifstat # Show network interface status ipxe> route # Show routing table ipxe> dhcp # Request DHCP configuration ipxe> chain http://url # Load and execute from URL ``` ### Network Diagnostics ```bash # From rescue environment: ip addr show # Show IP configuration ip route show # Show routing table cat /etc/resolv.conf # Show DNS configuration ping -c 4 8.8.8.8 # Test internet connectivity nslookup boot.netboot.xyz # Test DNS resolution ``` ### Log Analysis ```bash # System logs (most Linux distributions): journalctl -b # Current boot messages dmesg | tail -50 # Kernel messages tail -f /var/log/syslog # System log # DHCP server logs: tail -f /var/log/dhcpd.log # ISC DHCP server journalctl -u dhcpd -f # systemd DHCP service ``` ## Getting Help If you encounter an error code not listed here: 1. **Note the exact error code and message** 2. **Check our GitHub issues:** https://github.com/netbootxyz/netboot.xyz/issues 3. **Join our Discord:** https://discord.gg/An6PA2a 4. **Provide detailed information:** - Full error message - Hardware details - Network configuration - Steps to reproduce --- # Troubleshooting Guide Source: https://netboot.xyz/docs/troubleshooting # Troubleshooting netboot.xyz This guide covers common issues you might encounter when using netboot.xyz and their solutions. ## Quick Diagnostic Steps Before diving into specific issues, try these basic diagnostic steps: 1. **Verify network connectivity** - Ensure the device can access the internet 2. **Check DHCP/PXE configuration** - Verify your network supports PXE booting 3. **Test with different bootloaders** - Try both UEFI and BIOS versions 4. **Check firewall settings** - Ensure ports 53 (DNS), 67/68 (DHCP), and 69 (TFTP) are open ## Common Issues by Category ### Boot Issues #### The system doesn't PXE boot at all **Symptoms:** - No PXE boot option in BIOS/UEFI - "No bootable device found" errors - Boot process skips network boot entirely **Solutions:** 1. **Enable PXE/Network Boot in BIOS/UEFI:** ``` - Enter BIOS/UEFI settings (usually F2, F12, Del during boot) - Look for "Network Boot", "PXE", or "Boot from LAN" options - Enable these options and set network boot as first priority ``` 2. **Check network cable and connection:** ``` - Use a known-good Ethernet cable - Verify link lights are active on network port - Try a different network port if available ``` 3. **DHCP Configuration Issues:** ``` - Ensure DHCP server is running on your network - Verify DHCP has available IP addresses - Check if DHCP server supports PXE (Options 66/67) ``` #### System boots but gets stuck loading netboot.xyz **Symptoms:** - PXE boot starts but hangs at "Loading netboot.xyz..." - Timeout errors when downloading files - Partial menu loading **Solutions:** 1. **Network Speed Issues:** ```bash # Try a different netboot.xyz endpoint # Instead of boot.netboot.xyz, try: # - boot.netboot.xyz (primary) # - github.netboot.xyz (GitHub pages backup) ``` 2. **DNS Resolution Problems:** ```bash # Add to DHCP server configuration: option domain-name-servers 8.8.8.8, 1.1.1.1; ``` 3. **Firewall Blocking:** ``` - Allow outbound HTTPS (port 443) traffic - Allow DNS resolution (port 53) - Check corporate firewall/proxy settings ``` #### Menu loads but the USB keyboard doesn't respond **Symptoms:** - The netboot.xyz menu displays correctly but keystrokes do nothing - You cannot navigate or select menu entries - The keyboard works in BIOS/UEFI setup but not in the menu **Solution:** USB NIC drivers in the standard iPXE builds can disable the BIOS USB legacy support that emulates a PS/2 keyboard. Boot the **legacy** images instead, which omit those drivers and restore keyboard support. See [USB Keyboard Issues](../kb/hardware/usb-keyboard.md) for the download links and instructions. ### Menu and OS Loading Issues #### Menu loads but OS downloads fail **Symptoms:** - netboot.xyz menu appears correctly - OS selection fails with download errors - "Could not download" messages **Solutions:** 1. **Insufficient Memory:** ``` Minimum Requirements: - 1GB RAM for most Linux distributions - 2GB RAM for larger distributions (Ubuntu, Fedora) - 4GB+ RAM for rescue environments with GUI ``` 2. **Storage Issues:** ``` - Ensure target disk has sufficient free space - Check for disk errors or corruption - Verify disk is properly detected by system ``` 3. **Network Bandwidth:** ``` # For slow connections, try: - Use minimal/netinstall versions when available - Schedule downloads during off-peak hours - Consider self-hosting netboot.xyz for local network ``` #### Specific OS fails to boot after download **Symptoms:** - Download completes successfully - Boot process starts but fails - Kernel panic or boot loop **Solutions:** 1. **Hardware Compatibility:** ``` - Check OS hardware requirements - Try different kernel versions when available - Verify CPU architecture (x86_64 vs ARM64) ``` 2. **UEFI vs BIOS Issues:** ``` - Try switching between UEFI and Legacy BIOS modes - Use appropriate netboot.xyz bootloader for your system - Check Secure Boot settings (disable if necessary) ``` ### Self-Hosting Issues #### Docker container won't start **Symptoms:** - Container exits immediately - Port binding errors - Permission denied errors **Solutions:** 1. **Port Conflicts:** ```bash # Check if ports are already in use sudo netstat -tulpn | grep :80 sudo netstat -tulpn | grep :69 # Use different ports if needed docker run -p 8080:80 -p 6969:69 netbootxyz/netboot.xyz ``` 2. **Permission Issues:** ```bash # Ensure Docker daemon is running sudo systemctl status docker # Add user to docker group sudo usermod -aG docker $USER # Then logout and login again ``` #### Custom menus not loading **Symptoms:** - Default menus work fine - Custom menu entries don't appear - Custom ISOs fail to boot **Solutions:** 1. **File Path Issues:** ```yaml # In docker-compose.yml, ensure paths are correct: volumes: - /local/path/to/assets:/assets - /local/path/to/menus:/config/menus ``` 2. **File Permissions:** ```bash # Ensure files are readable by container chmod -R 644 /path/to/assets/ chmod -R 755 /path/to/assets/directories/ ``` ## Environment-Specific Issues ### Home Network Setup **Common Issues:** - Consumer routers don't support PXE by default - WiFi networks don't support PXE booting - Limited DHCP configuration options **Solutions:** 1. **Router Configuration:** ``` - Look for "PXE Boot Support" in router settings - Enable TFTP server if available - Set DHCP Option 66 to boot.netboot.xyz - Set DHCP Option 67 to netboot.xyz.kpxe ``` 2. **Alternative Approaches:** ``` - Use USB/ISO images for initial testing - Set up a dedicated PXE server (Raspberry Pi) - Use netboot.xyz Docker container locally ``` ### Enterprise Network **Common Issues:** - Network segmentation blocking access - Proxy servers interfering - Security policies preventing PXE boot **Solutions:** 1. **Network Access:** ``` Required firewall rules: - Outbound HTTPS to *.netboot.xyz (port 443) - Outbound DNS resolution (port 53) - TFTP if using local TFTP server (port 69) ``` 2. **Proxy Configuration:** ``` # If using HTTP proxy, configure: ``` ### Cloud Environments #### AWS/EC2 Issues **Common Issues:** - EBS boot volumes not properly configured - Security groups blocking network access - Instance types without sufficient resources **Solutions:** ```bash # Ensure security group allows: - Inbound SSH (port 22) for management - Outbound HTTPS (port 443) for downloads - Inbound HTTP (port 80) if serving local content ``` #### VMware/VirtualBox Issues **Common Issues:** - Network adapter configuration - Insufficient allocated memory - Boot order problems **Solutions:** ``` VMware: - Set network adapter to "Bridged" mode - Allocate minimum 2GB RAM - Enable VT-x/AMD-V in VM settings VirtualBox: - Use "Bridged Adapter" network setting - Enable "Cable Connected" option - Set boot order: Network, then Hard Disk ``` ## Getting Additional Help If you're still experiencing issues after trying these solutions: 1. **Check the FAQ** - Many common questions are answered in our [FAQ section](/docs/faq) 2. **Search GitHub Issues** - Check if your issue is already reported: https://github.com/netbootxyz/netboot.xyz/issues 3. **Join Discord** - Get community help: https://discord.gg/An6PA2a 4. **Create a detailed issue report** with: - Your hardware/platform details - Network configuration - Exact error messages - Steps to reproduce the problem ## Diagnostic Information Collection When asking for help, please include: ```bash # System Information uname -a lscpu | head -20 free -h ip addr show # Network Configuration cat /etc/resolv.conf ip route show ``` For DHCP/PXE servers: ```bash # DHCP lease information dhcp-lease-list cat /var/lib/dhcp/dhcpd.leases | tail -50 # TFTP server status systemctl status tftpd-hpa ls -la /srv/tftp/ ``` --- # Performance Optimization Source: https://netboot.xyz/docs/troubleshooting/performance-optimization # Performance Optimization Guide This guide helps you optimize netboot.xyz performance for faster boot times, quicker downloads, and better user experience. ## Boot Time Optimization ### Network Boot Speed **Reduce PXE Boot Time:** 1. **Optimize DHCP Response Time:** ```bash # In DHCP server configuration: default-lease-time 86400; max-lease-time 86400; # Reduce timeout values: timeout 10; retry 5; ``` 2. **Use Local TFTP Server:** ```bash # Instead of boot.netboot.xyz, use local server: option next-server 192.168.1.100; # Your local server option bootfile-name "netboot.xyz.kpxe"; ``` 3. **Preload Network Drivers:** ``` # Use appropriate bootloader for your hardware: - netboot.xyz.kpxe (includes common drivers) - netboot.xyz-undionly.kpxe (uses BIOS network drivers) - netboot.xyz.efi (UEFI with SNP support) ``` ### Menu Loading Optimization **Faster Menu Display:** 1. **Enable HTTP Compression:** ```nginx # Nginx configuration: location / { gzip on; gzip_types text/plain application/json text/css application/javascript; gzip_min_length 1000; } ``` 2. **Use CDN for Static Assets:** ``` # Configure custom endpoints with CDN: https://your-cdn.com/netboot/menus/ ``` 3. **Optimize Network MTU:** ```bash # Test optimal MTU size: ping -f -l 1472 boot.netboot.xyz # Windows ping -M do -s 1472 boot.netboot.xyz # Linux # Set optimal MTU (usually 1500 for Ethernet): sudo ip link set dev eth0 mtu 1500 ``` ## Download Speed Optimization ### Bandwidth Management **Optimize Download Performance:** 1. **Choose Optimal Mirror:** ```bash # Test mirror speeds: curl -w "@curl-format.txt" -o /dev/null https://boot.netboot.xyz/ curl -w "@curl-format.txt" -o /dev/null https://github.netboot.xyz/ # curl-format.txt content: # time_namelookup: %{time_namelookup}\n # time_connect: %{time_connect}\n # time_total: %{time_total}\n # speed_download: %{speed_download}\n ``` 2. **Parallel Downloads:** ```bash # For custom implementations, use parallel downloads: wget --parallel=4 --continue url1 url2 url3 url4 ``` 3. **Local Caching:** ```bash # Set up local cache with nginx: proxy_cache_path /var/cache/nginx/netboot levels=1:2 keys_zone=netboot:10m max_size=10g inactive=60m use_temp_path=off; location / { proxy_pass https://boot.netboot.xyz; proxy_cache netboot; proxy_cache_valid 200 24h; proxy_cache_use_stale error timeout updating; } ``` ### Self-Hosting Optimization **Local netboot.xyz Instance:** 1. **Docker Performance Tuning:** ```yaml # docker-compose.yml optimizations: version: '3.8' services: netbootxyz: image: netbootxyz/netboot.xyz restart: unless-stopped environment: - MENU_VERSION=2.0.59 ports: - "80:80" - "69:69/udp" volumes: - ./config:/config - ./assets:/assets # Performance optimizations: deploy: resources: limits: memory: 2G reservations: memory: 512M sysctls: - net.core.somaxconn=65535 ``` 2. **Nginx Configuration:** ```nginx # /config/nginx/site-confs/default server { listen 80; server_name _; # Performance optimizations: sendfile on; tcp_nopush on; tcp_nodelay on; keepalive_timeout 30; # Compression: gzip on; gzip_vary on; gzip_types text/plain text/css application/json application/javascript; # Caching: location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; } # Assets location: location /assets/ { alias /assets/; autoindex on; } } ``` ## Memory Optimization ### RAM Usage Optimization **Reduce Memory Footprint:** 1. **Choose Lightweight Distributions:** ``` Minimal RAM Requirements: - Alpine Linux: 128MB - Tiny Core Linux: 64MB - Puppy Linux: 256MB - Debian Netinstall: 512MB ``` 2. **Optimize iPXE Memory Usage:** ``` # Use smaller bootloaders when possible: - netboot.xyz.lkrn: ~500KB (Linux kernel format) - netboot.xyz.kpxe: ~100KB (PXE format) - netboot.xyz.efi: ~200KB (UEFI format) ``` 3. **Configure Swap for Low-Memory Systems:** ```bash # Create swap file for systems with limited RAM: sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # Make permanent: echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab ``` ### Storage Optimization **Disk Usage Optimization:** 1. **Clean Downloaded Assets:** ```bash # Regularly clean temporary downloads: find /tmp -name "*.iso" -mtime +1 -delete find /var/cache -name "*.deb" -mtime +7 -delete ``` 2. **Optimize Asset Storage:** ```bash # Use compression for stored ISOs: find /assets -name "*.iso" -exec gzip {} \; # Configure automatic decompression in nginx: location ~ \.iso$ { gzip_static on; } ``` ## Network Optimization ### Network Stack Tuning **Optimize Network Performance:** 1. **TCP Optimization:** ```bash # /etc/sysctl.conf optimizations: net.core.rmem_max = 134217728 net.core.wmem_max = 134217728 net.ipv4.tcp_rmem = 4096 65536 134217728 net.ipv4.tcp_wmem = 4096 65536 134217728 net.core.netdev_max_backlog = 5000 net.ipv4.tcp_window_scaling = 1 # Apply changes: sudo sysctl -p ``` 2. **Network Interface Optimization:** ```bash # Optimize network interface settings: sudo ethtool -G eth0 rx 4096 tx 4096 # Increase ring buffer sudo ethtool -K eth0 tso on gso on # Enable offloading ``` ### DNS Optimization **Improve DNS Resolution:** 1. **Use Fast DNS Servers:** ```bash # /etc/resolv.conf: nameserver 1.1.1.1 # Cloudflare nameserver 8.8.8.8 # Google nameserver 9.9.9.9 # Quad9 ``` 2. **Local DNS Caching:** ```bash # Install and configure dnsmasq: sudo apt-get install dnsmasq # /etc/dnsmasq.conf: cache-size=1000 local-ttl=300 ``` ## Self-Hosting Performance ### Hardware Recommendations **Optimal Hardware for Self-Hosting:** 1. **Minimum Specifications:** ``` CPU: 2 cores, 2GHz RAM: 4GB Storage: 50GB SSD Network: Gigabit Ethernet ``` 2. **Recommended Specifications:** ``` CPU: 4+ cores, 3GHz+ RAM: 8GB+ Storage: 100GB+ NVMe SSD Network: Gigabit Ethernet with QoS ``` 3. **Enterprise Specifications:** ``` CPU: 8+ cores, 3.5GHz+ RAM: 16GB+ Storage: 500GB+ NVMe SSD in RAID 1 Network: 10Gbps with redundancy ``` ### Docker Optimization **Container Performance Tuning:** 1. **Resource Limits:** ```yaml services: netbootxyz: deploy: resources: limits: cpus: '2.0' memory: 4G reservations: cpus: '1.0' memory: 2G ``` 2. **Volume Optimization:** ```yaml volumes: # Use bind mounts for better performance: - type: bind source: ./assets target: /assets - type: bind source: ./config target: /config ``` ## Monitoring and Metrics ### Performance Monitoring **Track Performance Metrics:** 1. **Network Monitoring:** ```bash # Monitor network usage: iftop -i eth0 # Real-time bandwidth nethogs # Per-process network usage ss -tuln # Active connections ``` 2. **System Performance:** ```bash # Monitor system resources: htop # CPU and memory usage iotop # Disk I/O vmstat 1 # System statistics ``` 3. **Docker Monitoring:** ```bash # Monitor container performance: docker stats netbootxyz # Resource usage docker logs netbootxyz # Container logs ``` ### Log Analysis **Performance Log Analysis:** 1. **Nginx Access Logs:** ```bash # Analyze slow requests: awk '$9 >= 400 {print $0}' /var/log/nginx/access.log # Top requesting IPs: awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head -20 ``` 2. **System Logs:** ```bash # Check for performance issues: journalctl -p err -b # Error messages from current boot dmesg | grep -i error # Kernel errors ``` ## Troubleshooting Slow Performance ### Common Performance Issues **Identify and Fix Slow Performance:** 1. **Network Bottlenecks:** ```bash # Test network speed: iperf3 -c server_ip # Bandwidth test mtr boot.netboot.xyz # Network path analysis tcpdump -i eth0 port 80 # Monitor HTTP traffic ``` 2. **Storage Issues:** ```bash # Test disk performance: hdparm -tT /dev/sda # Hard drive speed test dd if=/dev/zero of=/tmp/test bs=1M count=1024 # Write speed test ``` 3. **Memory Pressure:** ```bash # Check memory usage: free -h # Available memory cat /proc/meminfo # Detailed memory info ps aux --sort=-%mem # Top memory consumers ``` Remember: Performance optimization is an iterative process. Monitor your metrics, make incremental changes, and measure the impact of each optimization.