A production-ready, self-contained PXE and HTTP boot server written in Go with embedded iPXE bootloaders, SQLite/PostgreSQL support, and a full-featured web admin interface. Deploy in seconds with a single binary or Docker container.
This is an early-stage work-in-progress project - there may be bugs. Please raise an issue for any unexpected behaviour you encounter.
I've used Claude CLI to help with some parts of this project - mostly making the web UI pretty, as I'm NOT a frontend developer. I also used it to generate the docs, but I review them manually - no automatically-generated AI code goes into the project without review from myself.
- Single binary, zero config: Everything bundled - bootloaders, web UI, database. Just run it
- Standalone PXE: Built-in proxyDHCP responder lets Bootimus drive PXE on any LAN without touching the existing DHCP server
- 50+ distro support: Automatic kernel/initrd extraction with a generic fallback scanner for unknown ISOs
- Unattended Windows install (opt-in): PXE-boot Windows 10/11 end-to-end — Bootimus hosts the install media over SMB and auto-launches
setup.exe. Requiressambaon the host (bundled in the Docker image) - Built-in diagnostic tools: GParted, Clonezilla, Memtest86+, SystemRescue, ShredOS, Netboot.xyz - one-click download and enable from the admin UI
- Custom tools: Add your own PXE-bootable tools with configurable boot methods (kernel, chain, memdisk)
- Per-client access control: Assign specific images per MAC address, toggle public image visibility per client
- Client auto-discovery: Clients are automatically detected when they PXE boot, like DHCP leases - promote to static when ready
- Next boot action: Set a one-time boot image for a client with optional Wake-on-LAN - auto-clears after use
- Hardware inventory: Automatic collection of CPU, memory, manufacturer, serial number, and NIC info from PXE clients
- JWT authentication: Secure token-based auth with a dedicated login page
- LDAP/Active Directory: Optional LDAP backend with group-based admin access - local accounts always work as fallback
- Swappable bootloaders: Ship with embedded iPXE, or bring your own custom bootloader sets
- Modern admin UI: Sidebar navigation, consistent toolbars, real-time colour-coded logs, REST API
- Multi-database: SQLite out of the box, PostgreSQL for production
- Docker and bare metal: Multi-arch images (amd64/arm64) or a single static binary
| Admin Dashboard | Upload ISOs | Download from URL |
|---|---|---|
 |
 |
 |
# Create data directory
mkdir -p data
# Run with SQLite (no database container needed)
docker run -d \
--name bootimus \
--cap-add NET_BIND_SERVICE \
-p 69:69/udp \
-p 8080:8080/tcp \
-p 8081:8081/tcp \
-v $(pwd)/data:/data \
garybowers/bootimus:latest
# Check logs for admin password
docker logs bootimus | grep "Password"
# Access admin interface
open http://localhost:8081A docker logo is available, see Bootimus bootimus_logo.png.
Ex.: it can be used with unraid with: https://github.com/garybowers/bootimus/logos/bootimus_logo_square_ulow.png
# Download binary
wget https://github.com/garybowers/bootimus/releases/latest/download/bootimus-amd64
chmod +x bootimus-amd64
# Run (SQLite mode - no database required)
./bootimus-amd64 serve
# Admin panel: http://localhost:8081git clone https://github.com/garybowers/bootimus
cd bootimus
docker-compose up -d- Deployment Guide - Docker, binary, networking, and storage
- Image Management - Upload ISOs, extract kernels, netboot support
- USB Appliance - Flashable Alpine+bootimus image for portable PXE servers
- Admin Console - Web UI and REST API reference
- DHCP Configuration - Configure your DHCP server
- Client Management - MAC-based access control, auto-discovery, next boot
- Authentication - JWT auth, LDAP/Active Directory setup
- Distro Profiles - Data-driven distro detection and boot params
Bootimus includes a built-in tools system for diagnostic and utility software. Tools can be downloaded and enabled from the admin UI under the Tools section. When enabled, they appear in a Tools submenu in the PXE boot menu.
| Tool | Description |
|---|---|
| GParted Live | Partition editor for managing disk partitions |
| Clonezilla Live | Disk cloning and imaging |
| Memtest86+ | Memory testing and diagnostics |
| SystemRescue | Full rescue toolkit (file recovery, disk repair, network tools) |
| ShredOS | Secure disk wiping based on nwipe |
| Netboot.xyz | Chainloads into hundreds of OS installers and tools |
Download URLs are shown in the UI and can be overridden to point at local mirrors or newer versions.
You can add your own PXE-bootable tools via the "+ Add Custom Tool" button in the Tools section. Custom tools support:
- Boot methods: Kernel/initrd, chain (EFI), or memdisk
- Archive types: ZIP, single binary, or ISO
- Boot parameters: With
{{HTTP_URL}}placeholder for server URL substitution - Download from URL: Specify any HTTP/HTTPS URL for the tool files
Bootimus ships with embedded iPXE bootloaders for UEFI (x86_64, ARM64) and Legacy BIOS. You can also use custom bootloader sets:
- Create a subfolder in
{data-dir}/bootloaders/(e.g.ipxe-custom/) - Place your custom bootloader files in it
- Select the set from the Bootloaders section in the admin UI
The built-in set is always available as a fallback. Files not present in the active custom set are served from the built-in set automatically.
- Arch Linux, CachyOS, EndeavourOS, Manjaro, Garuda, Artix, BlackArch, Parabola, SteamOS
- Ubuntu (all flavours), Debian, Linux Mint, Pop!_OS, Kali, Parrot, Zorin, elementary OS, MX Linux, antiX, Devuan, PureOS, Deepin, LMDE, TrueNAS SCALE, Proxmox
- Fedora, CentOS, Rocky Linux, AlmaLinux, Oracle Linux, Nobara, Mageia
- openSUSE, NixOS, Alpine, Gentoo, Void, Slackware, Solus, Tiny Core, Clear Linux
- FreeBSD
- Windows 10/11 (via wimboot) — optional unattended install via SMB (see the Windows Unattended Install section). Needs
sambaon the host if enabled.
For distributions not in this list, the generic boot scanner automatically walks the ISO filesystem to find kernel and initrd files and attempts to extract boot parameters from syslinux/grub configuration files.
Need to add a new distro? Create a custom distro profile from the admin UI — no code change required. See the Distro Profiles Guide. You can also contribute profiles to the official list via pull request.
ISOs can be organised into groups by placing them in subdirectories:
data/isos/
├── ubuntu-24.04.iso # ungrouped, appears in main menu
├── linux/ # creates "linux" group
│ ├── debian-12.iso # in "linux" submenu
│ └── servers/ # creates "servers" subgroup
│ └── truenas-scale.iso # in "linux > servers" submenu
└── windows/ # creates "windows" group
└── win11.iso # in "windows" submenu
Groups are auto-created on startup and when scanning for ISOs. They can also be managed manually via the admin UI.
Off by default. When enabled, bootimus starts an isolated smbd child process that exposes each extracted Windows ISO as a read-only guest SMB share, and patches the WinPE boot.wim so setup.exe auto-mounts that share and runs — no manual net use from the WinPE prompt, no keyboard input after PXE.
This feature requires Samba on the host. The Docker image ships samba out of the box. Standalone Linux users install it manually:
# Debian / Ubuntu
sudo apt install samba
# Arch
sudo pacman -S samba
# Fedora / RHEL
sudo dnf install sambaIf smbd isn't in PATH, the feature self-disables with a clear log line and the rest of bootimus runs normally — nothing else depends on samba.
-
wimlib-imagex(already required for Windows driver injection). -
Port 445 reachable from clients. Windows'
net useignores non-445 SMB ports, so--windows-smb-portis for testing only. -
If running standalone with
setcapinstead of root, grantsmbdthe same capability so the forked child can bind 445:sudo setcap 'cap_net_bind_service=+eip' /usr/sbin/smbd(Docker users skip this — the image runs as root.)
# Standalone
./bootimus serve --windows-smb
# Config file (bootimus.yaml)
windows_smb:
enabled: true
port: 445Docker Compose — uncomment both the env var and the port mapping in docker-compose.yml:
services:
bootimus:
environment:
BOOTIMUS_WINDOWS_SMB_ENABLED: "true"
ports:
- "445:445/tcp"- Settings tab shows live SMB status:
Enabled (N shares, port 445),Disabled, orRequested but unavailableifsmbdis missing. - Patched Windows ISOs get an SMB chip in the image list.
- The image-properties panel gains a Patch SMB / Re-patch SMB button for applying (or re-applying) the boot.wim patch without re-extracting.
- iPXE colour theming (blocked on iPXE firmware compatibility)
- NetBSD/OpenBSD support
| Feature | Bootimus | iVentoy |
|---|---|---|
| Language | Go | C |
| Single Binary | Yes | No |
| Embedded Bootloaders | Yes | No |
| Standalone PXE | Built-in proxyDHCP — no DHCP reconfig needed | Requires external DHCP changes |
| Database | SQLite / PostgreSQL | File-based |
| Web UI | Modern sidebar UI with REST API | Basic HTML |
| Authentication | JWT + LDAP/AD | None |
| Boot Logging | Full tracking with live streaming | Limited |
| MAC-based ACL | Granular per-client | No |
| ISO Upload | Web upload + URL download | Manual copy |
| Boot Tools | GParted, Clonezilla, Memtest86+, etc. | No |
| Bootloader Management | Swappable sets via UI | No |
| Docker Support | Multi-arch | Limited |
| API-First | RESTful API | No |
| Licence | Apache 2.0 | GPL |
Bootimus has two options for the DHCP side of PXE.
Bootimus ships with a built-in proxyDHCP responder. Enable it and your existing DHCP server (router, Pi-hole, Windows DHCP, anything) needs zero PXE configuration — it keeps handing out IPs as normal, and Bootimus answers only the PXE-specific bits on the same broadcast domain.
bootimus serve --proxy-dhcp
# or: BOOTIMUS_PROXY_DHCP_ENABLED=trueBinds UDP/67; needs CAP_NET_BIND_SERVICE or root. Off by default so existing installs aren't surprised.
If you'd rather keep PXE config on your existing DHCP server, point it at Bootimus. Example for ISC DHCP:
subnet 192.168.1.0 netmask 255.255.255.0 {
range 192.168.1.100 192.168.1.200;
next-server 192.168.1.10; # Bootimus server IP
# Chain to HTTP after iPXE loads
if exists user-class and option user-class = "iPXE" {
filename "http://192.168.1.10:8080/menu.ipxe";
}
# UEFI systems
elsif option arch = 00:07 or option arch = 00:09 {
filename "ipxe.efi";
}
# Legacy BIOS
else {
filename "undionly.kpxe";
}
}
See DHCP Configuration Guide for Dnsmasq, MikroTik, Ubiquiti, and more.
# Clone repository
git clone https://github.com/garybowers/bootimus
cd bootimus
# Build and run locally
make build
make run
# Build container image locally
make docker-build
# Start services via docker compose
make docker-up
# Build all platform binaries for GitHub release
make release
# Build and push multi-arch container to Docker Hub
make docker-push
# Push amd64 only (faster, skips arm64 QEMU emulation)
make docker-push PLATFORMS=linux/amd64Run make help for all available targets.
- Read-only TFTP: TFTP server is read-only (no write operations)
- Path sanitisation: All file paths sanitised to prevent directory traversal
- MAC address verification: ISOs served only to authorised clients
- Admin authentication: JWT token-based auth with bcrypt password hashing, optional LDAP/AD backend
- Separate admin port: Admin interface isolated from boot network
- Audit logs: All boot attempts logged with client/image/success tracking
Bootimus binds privileged UDP ports: 69 for TFTP, and 67 if --proxy-dhcp is enabled.
# Run as root
sudo ./bootimus serve
# Or grant capabilities once to the binary
sudo setcap 'cap_net_bind_service=+ep' ./bootimus
# Or use Docker with NET_BIND_SERVICE (default image already runs as root)
docker run --cap-add NET_BIND_SERVICE ...
# Or use a non-privileged TFTP port
./bootimus serve --tftp-port 6969Most common first-time PXE failures:
# 1. Check Bootimus is seeing the client's DHCP request
docker logs bootimus | grep -E 'proxyDHCP|TFTP'
# 2. Same broadcast domain — PXE DHCP is L2 broadcast.
# In Docker, the container must use macvlan/ipvlan or network_mode: host.
# The default bridge network will NOT work; docker0 traps broadcasts.
# 3. Two DHCP servers advertising PXE? Pick one.
# If proxyDHCP is enabled, strip PXE options from your router's DHCP.
# 4. Firewall
sudo ufw allow 67/udp # proxyDHCP (if enabled)
sudo ufw allow 69/udp # TFTP
sudo ufw allow 8080/tcp # HTTP boot
# 5. Check the client can reach HTTP
curl -v http://<bootimus-ip>:8080/menu.ipxe# Check data directory
ls -la data/isos/
# Scan for ISOs via API
curl -H "Authorization: Bearer $TOKEN" -X POST http://localhost:8081/api/scan
# Enable public access to images
curl -H "Authorization: Bearer $TOKEN" -X PUT http://localhost:8081/api/images?filename=ubuntu.iso \
-H "Content-Type: application/json" \
-d '{"public": true, "enabled": true}'Bootimus does not currently ship Microsoft-signed bootloaders. On machines with Secure Boot enabled, PXE boot fails with a signature-verification error.
Fix: disable Secure Boot in the target's firmware, or enrol Bootimus's iPXE EFI binary into the firmware's MOK keystore.
# Prints a fresh random password to the logs, then continues starting
./bootimus serve --reset-admin-password
# Via Docker
docker exec bootimus bootimus serve --reset-admin-password
docker logs bootimus | grep "New Password"# Check SQLite database
ls -la data/bootimus.db
# For PostgreSQL, test connection
psql -h localhost -U bootimus -d bootimusLicensed under the Apache Licence, Version 2.0. See LICENSE for details.
Copyright 2025-2026 Bootimus Contributors
Contributions welcome! Please open an issue or pull request.
- GitHub: https://github.com/garybowers/bootimus
- Docker Hub: https://hub.docker.com/r/garybowers/bootimus
- Documentation: https://github.com/garybowers/bootimus/tree/main/docs