carnyc/pxe-boot0r repository overview

⁠pxe-boot0r

A free, Docker-based PXE server that auto-generates a boot menu from a folder of ISOs — an open alternative to iVentoy, built on ideas from netboot.xyz⁠ and Ventoy⁠.

Drop *.iso files into a folder, start the container, and machines on your LAN get an iPXE boot menu with every detected system. DHCP is optional and can be disabled.

⁠English

⁠Features

• Auto menu from your ISO folder. Linux families are booted directly with the right kernel + initrd: Ubuntu/Mint, Debian (live + installer), Fedora/RHEL/Alma/Rocky, openSUSE, Arch, Alpine, SystemRescue.
• Windows install media — WinPE is booted via wimboot, and the install sources are wired up automatically (no manual Shift+F10 dance), iVentoy-style.
• Unknown ISOs get sanboot + memdisk fallback entries.
• Three DHCP modes, switchable by env var: off, proxy (ProxyDHCP, recommended), full (standalone DHCP server).
• BIOS + UEFI — both are served (undionly.kpxe / ipxe.efi).

⁠Quick start

Create a docker-compose.yml:

services:
  pxe-boot0r:
    image: carnyc/pxe-boot0r:latest
    container_name: pxe-boot0r
    network_mode: host        # PXE/DHCP need raw L2 broadcasts
    privileged: true          # only required for WIN_INSTALL_MODE=smb
    restart: unless-stopped
    environment:
      DHCP_MODE: proxy        # off | proxy | full
      PXE_SERVER_IP: 192.168.1.10
      WIN_INSTALL_MODE: http   # smb | http
    volumes:
      - ./isos:/srv/isos:ro

Then add ISOs and start:

mkdir -p isos && cp /path/to/*.iso isos/
docker compose up -d

A client doing PXE boot on the same LAN now sees the menu. Tags: latest, 1.0.0.

⁠Configuration (environment variables)

⁠Example: standalone DHCP (full mode)

Use full only when nothing else serves DHCP on the LAN (e.g. an isolated lab network). PXE_SERVER_IP, DHCP_RANGE_START and DHCP_RANGE_END are required:

    environment:
      DHCP_MODE: full
      PXE_SERVER_IP:    192.168.50.10    # this host (must be in the subnet below)
      DHCP_RANGE_START: 192.168.50.100   # first lease — a single IPv4, NOT a CIDR
      DHCP_RANGE_END:   192.168.50.200   # last lease  — a single IPv4
      DHCP_NETMASK:     255.255.255.0    # dotted-quad
      DHCP_ROUTER:      192.168.50.1     # gateway given to clients (DHCP option 3)
      DHCP_DNS:         1.1.1.1          # DNS given to clients (DHCP option 6)

• DHCP_RANGE_START / _END are single addresses (e.g. 192.168.50.100), not a CIDR like 192.168.50.0/24.
• PXE_SERVER_IP must be in the same subnet as the range.
• For proxy mode you only set PXE_SERVER_IP; the DHCP_RANGE_* / DHCP_ROUTER / DHCP_DNS options are ignored (your existing DHCP server hands those out).

⁠Volumes

⁠Windows ISOs

wimboot and httpdisk are bundled in the image — nothing to download. Drop the Windows ISO into ./isos and pick how the install sources reach WinPE:

• WIN_INSTALL_MODE=smb (default): the ISO is loop-mounted and exposed via an anonymous Samba share; WinPE mounts it and runs setup.exe. Needs privileged: true.
• WIN_INSTALL_MODE=http (iVentoy-style): the bundled httpdisk⁠ driver is injected into boot.wim; WinPE mounts the HTTP-served ISO as a virtual CD-ROM. Disable Secure Boot on the client (WinPE is booted in test-signing mode). No SMB, no loop-mount — does not need privileged.

⁠Networking notes

network_mode: host is required (DHCP uses raw broadcasts). Ports: 67/udp (DHCP), 69/udp (TFTP), 4011/udp (ProxyDHCP), 80/tcp (HTTP), plus 445/139 (SMB) in smb mode. privileged: true is only needed for WIN_INSTALL_MODE=smb.

⁠Deutsch

⁠Funktionen

• Automatisches Menü aus deinem ISO-Ordner. Linux-Familien werden direkt mit passendem Kernel + Initrd gebootet: Ubuntu/Mint, Debian (Live + Installer), Fedora/RHEL/Alma/Rocky, openSUSE, Arch, Alpine, SystemRescue.
• Windows-Installationsmedien — WinPE wird per wimboot gestartet und die Installationsquellen werden automatisch eingebunden (kein manuelles Shift+F10), im iVentoy-Stil.
• Unbekannte ISOs bekommen sanboot- + memdisk-Fallback-Einträge.
• Drei DHCP-Modi per Umgebungsvariable: off, proxy (ProxyDHCP, empfohlen), full (eigenständiger DHCP-Server).
• BIOS + UEFI — beide werden bedient (undionly.kpxe / ipxe.efi).

⁠Schnellstart

docker-compose.yml anlegen:

services:
  pxe-boot0r:
    image: carnyc/pxe-boot0r:latest
    container_name: pxe-boot0r
    network_mode: host        # PXE/DHCP brauchen rohe L2-Broadcasts
    privileged: true          # nur für WIN_INSTALL_MODE=smb nötig
    restart: unless-stopped
    environment:
      DHCP_MODE: proxy        # off | proxy | full
      PXE_SERVER_IP: 192.168.1.10
      WIN_INSTALL_MODE: http   # smb | http
    volumes:
      - ./isos:/srv/isos:ro

Dann ISOs ablegen und starten:

mkdir -p isos && cp /pfad/zu/*.iso isos/
docker compose up -d

Ein PXE-Client im selben LAN sieht jetzt das Menü. Tags: latest, 1.0.0.

⁠Konfiguration (Umgebungsvariablen)

⁠Beispiel: eigenständiger DHCP (full-Modus)

full nur nutzen, wenn sonst niemand im LAN DHCP macht (z. B. isoliertes Lab-Netz). PXE_SERVER_IP, DHCP_RANGE_START und DHCP_RANGE_END sind Pflicht:

    environment:
      DHCP_MODE: full
      PXE_SERVER_IP:    192.168.50.10    # dieser Host (muss im Subnetz unten liegen)
      DHCP_RANGE_START: 192.168.50.100   # erste Lease — eine einzelne IPv4, KEIN CIDR
      DHCP_RANGE_END:   192.168.50.200   # letzte Lease — eine einzelne IPv4
      DHCP_NETMASK:     255.255.255.0    # als Dotted-Quad
      DHCP_ROUTER:      192.168.50.1     # Gateway für Clients (DHCP-Option 3)
      DHCP_DNS:         1.1.1.1          # DNS für Clients (DHCP-Option 6)

• DHCP_RANGE_START / _END sind einzelne Adressen (z. B. 192.168.50.100), kein CIDR wie 192.168.50.0/24.
• PXE_SERVER_IP muss im selben Subnetz wie der Bereich liegen.
• Im proxy-Modus setzt du nur PXE_SERVER_IP; die Optionen DHCP_RANGE_* / DHCP_ROUTER / DHCP_DNS werden ignoriert (die vergibt dein vorhandener DHCP-Server).

⁠Volumes

⁠Windows-ISOs

wimboot und httpdisk sind im Image enthalten — nichts herunterzuladen. Windows-ISO nach ./isos legen und wählen, wie die Quellen zu WinPE kommen:

• WIN_INSTALL_MODE=smb (Default): Die ISO wird loop-gemountet und per anonymem Samba-Share bereitgestellt; WinPE mountet sie und startet setup.exe. Braucht privileged: true.
• WIN_INSTALL_MODE=http (iVentoy-Stil): Der gebündelte httpdisk⁠-Treiber wird in die boot.wim injiziert; WinPE mountet die per HTTP ausgelieferte ISO als virtuelles CD-Laufwerk. Am Client Secure Boot deaktivieren (WinPE läuft im Test-Signing-Modus). Kein SMB, kein Loop-Mount — braucht kein privileged.

⁠Netzwerk-Hinweise

network_mode: host ist nötig (DHCP nutzt rohe Broadcasts). Ports: 67/udp (DHCP), 69/udp (TFTP), 4011/udp (ProxyDHCP), 80/tcp (HTTP), zusätzlich 445/139 (SMB) im smb-Modus. privileged: true ist nur für WIN_INSTALL_MODE=smb erforderlich.

Source / Issues: see the project repository. License: the image bundles open-source components (dnsmasq, nginx, iPXE, samba, …) plus wimboot (GPLv2) and httpdisk (GPL) — both redistributed binaries; their sources are referenced in the repository's vendor/ folder.