DOCSEARCHbyAlgolia
Submit Docs

netboot.xyz

repository·development·Indexed 9 days ago

https://github.com/netbootxyz/netboot.xyz

A network-based boot menu using iPXE that allows users to boot various operating systems and utilities over the network without physical media. Supports Legacy/BIOS, UEFI, ARM64, and Raspberry Pi 4 architectures. Includes options for self-hosting via Docker or Ansible, as well as the ability to configure custom iPXE menus.

Tokens
1.2K
Snippets
5
Records
6
Agent score
46%

What's inside netboot.xyz

  1. Self-host netboot.xyz using Ansible or Docker

    development

    You can deploy your own netboot.xyz environment using the provided Ansible templates or Docker configuration.

    Deploying with Ansible

    To generate and run the deployment, use the site.yml playbook. By default, the build output is located in /var/www/html.

    ansible-playbook site.yml

    Deploying with Docker

    To build and run the environment locally, use the following commands. The build output will be placed in a generated buildout folder.

    docker build -t localbuild --platform=linux/amd64 -f Dockerfile .
docker run --rm -it --platform=linux/amd64 -v $(pwd):/buildout localbuild

    Configuration and Overrides

    • Local Overrides: Use a user_overrides.yml file to override default settings (such as boot mirror URLs). This is preferred over editing boot.cfg directly, as changes to boot.cfg will be lost upon redeployment.
    • Custom Menus: You can create custom templates for custom menus within netboot.xyz. Refer to the documentation in etc/netbootxyz/custom/README.md for details.
    ansible-playbook site.yml

  2. Boot netboot.xyz via existing iPXE

    development

    If you already have iPXE running on your network, you can chainload netboot.xyz directly using the following commands:

    For Legacy (PCBIOS) mode:

    chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.lkrn

    For UEFI mode:

    chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.efi

    Note: While HTTPS is supported, default iPXE builds typically do not have HTTPS support compiled in. Using HTTP will load the appropriate kernel with the correct options enabled.

    chain --autofree http://boot.netboot.xyz/ipxe/netboot.xyz.lkrn

  3. Set up custom menus using Docker

    development

    When running netboot.xyz via Docker, you can provide custom menus by creating a custom folder in your root source directory and configuring the custom_templates_dir variable to point to that location within the container environment.

    Example configuration for Docker users:

    custom_generate_menus: true
custom_templates_dir: "/ansible/custom"

  4. Download netboot.xyz bootloaders

    development

    netboot.xyz provides various bootloader files depending on your hardware environment (Legacy/BIOS, UEFI, ARM64, or Raspberry Pi) and your specific needs (USB, ISO, DHCP, or Kernel).

    Combined Legacy and UEFI

    • ISO: netboot.xyz.iso (CD/DVD, Virtual media, DRAC/iLO, VMware, VirtualBox)
    • USB: netboot.xyz.img (USB Keys)

    Legacy (PCBIOS) iPXE

    • Kernel: netboot.xyz.lkrn (Boot from GRUB/EXTLINUX)
    • Floppy: netboot.xyz.dsk or netboot.xyz.pdsk (Virtual floppy for DRAC/iLO, VMware, etc.)
    • DHCP: netboot.xyz.kpxe (Standard) or netboot.xyz-undionly.kpxe (Use if experiencing NIC issues)

    UEFI iPXE

    • DHCP: netboot.xyz.efi (Standard)
    • DHCP-snp: netboot.xyz-snp.efi (Uses Simple Network Protocol, attempts to boot all net devices)
    • DHCP-snponly: netboot.xyz-snponly.efi (Uses Simple Network Protocol, only boots from device chained from)

    Legacy USB iPXE

    Note: Use these if your USB keyboard does not work with standard bootloaders. These exclude USB NIC drivers to preserve BIOS SMM-based USB legacy support for PS/2 keyboard emulation.

    • ISO: netboot.xyz-legacy.iso
    • USB: netboot.xyz-legacy.img
    • Kernel: netboot.xyz-legacy.lkrn
    • Floppy: netboot.xyz-legacy.dsk or netboot.xyz-legacy.pdsk
    • DHCP: netboot.xyz-legacy.kpxe
    • DHCP-efi: netboot.xyz-legacy.efi

    ARM64 iPXE

    • DHCP: netboot.xyz-arm64.efi
    • DHCP-snp: netboot.xyz-arm64-snp.efi
    • DHCP-snponly: netboot.xyz-arm64-snponly.efi

    Raspberry Pi 4

    • USB/SD Card: netboot.xyz-rpi4-sdcard.img
    • EFI: netboot.xyz-rpi4-snp.efi

    Checksums for all builds can be verified here.

  5. Configure custom iPXE menus for self-hosted netboot.xyz

    development

    You can create and maintain custom iPXE menus independently of the main netboot.xyz source tree. When enabled, the netboot.xyz main menu will include a 'custom menu' option that attempts to load custom/custom.ipxe from your specified custom templates directory.

    To enable this feature, set the following configuration options:

    1. custom_generate_menus: Set to true.
    2. custom_templates_dir: The path to your custom iPXE files.

    If you are using Docker, ensure your custom folder is mapped correctly and the custom_templates_dir points to the path inside the container.

    custom_generate_menus: true
custom_templates_dir: "{{ netbootxyz_conf_dir }}/custom"