此页面尚未翻译。显示英文版本。

en → zh-CN

docs / Image Management

Image Management

Upload ISOs, extract kernels, netboot support.

在 GitHub 上编辑 ↗

Image Management Guide#

Complete guide for managing ISO images, extracting boot files, and handling special cases like Debian/Ubuntu netboot.

Table of Contents#

Adding Images
Kernel Extraction
Netboot Support
Ubuntu Desktop Optimisation
Supported Distributions
Troubleshooting

Adding Images#

Upload via Web Interface#

Navigate to admin panel: http://your-server:8081
Click “Upload ISO” button
Drag and drop ISO file or click to browse
Optionally add description
Check “Public” to make available to all clients
Click “Upload”

Upload limits: 10GB per file

Upload via API#

curl -u admin:password -X POST http://localhost:8081/api/images/upload \
  -F "file=@/path/to/ubuntu-24.04-live-server-amd64.iso" \
  -F "description=Ubuntu 24.04 LTS Server" \
  -F "public=true"

Download from URL#

Download ISOs directly to the server without local upload:

Via Web Interface:

Click “Download from URL” button
Enter ISO download URL
Add description
Click “Download”

Via API:

curl -u admin:password -X POST http://localhost:8081/api/images/download \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://releases.ubuntu.com/24.04/ubuntu-24.04-live-server-amd64.iso",
    "description": "Ubuntu 24.04 LTS Server"
  }'

Monitor progress:

curl -u admin:password http://localhost:8081/api/downloads/progress?filename=ubuntu-24.04-live-server-amd64.iso

Organise with Folders#

ISOs placed in subdirectories are automatically grouped in the boot menu:

/data/isos/
├── ubuntu-24.04.iso              # ungrouped
├── linux/                        # "linux" group
│   ├── debian-12.iso
│   └── servers/                  # "servers" subgroup under "linux"
│       └── truenas-scale.iso
└── windows/                      # "windows" group
    └── win11.iso

Groups are auto-created on startup and when scanning. They can also be managed manually via the Groups tab in the admin UI.

Scan Existing ISOs#

If you manually copy ISOs to the data directory (including into subdirectories):

Copy ISO files to /data/isos/ directory (or subdirectories)
Click “Scan for ISOs” button in admin panel
Bootimus detects and registers new ISOs and creates groups from folders

Via API:

curl -u admin:password -X POST http://localhost:8081/api/scan

Kernel Extraction#

Most modern ISOs support direct HTTP booting via iPXE’s sanboot command, which downloads and boots the entire ISO. However, extracting the kernel and initrd provides significant benefits:

Benefits of Kernel Extraction#

Faster boot times: Only download kernel/initrd (~100MB) instead of entire ISO (1-10GB)
Reduced bandwidth: Critical for networks with multiple clients
Better compatibility: Some ISOs don’t support sanboot properly
Network installation: Use netboot files for Debian/Ubuntu installers

How to Extract#

Via Web Interface:

Navigate to Images tab
Find your ISO image
Click “Extract” button
Wait for extraction to complete

Via API:

curl -u admin:password -X POST http://localhost:8081/api/images/extract \
  -H "Content-Type: application/json" \
  -d '{"filename": "ubuntu-24.04-live-server-amd64.iso"}'

Manual Extraction#

If the built-in extractor doesn’t support your ISO, you can extract the boot files manually and bootimus will detect them automatically.

Create a directory with the same name as the ISO (minus the .iso extension):
```
mkdir -p data/isos/my-custom-distro/
```

Place the kernel and initrd in that directory with these exact names:

data/isos/
├── my-custom-distro.iso
└── my-custom-distro/
    ├── vmlinuz          # kernel
    └── initrd           # initrd/initramfs

Click “Scan for ISOs” in the admin panel (or restart bootimus). The image will be automatically detected as extracted and set to kernel boot method.

This also works for ISOs in subdirectories:

data/isos/linux/my-custom-distro.iso
data/isos/linux/my-custom-distro/vmlinuz
data/isos/linux/my-custom-distro/initrd

What Gets Extracted#

Bootimus automatically detects the distribution and extracts:

Kernel: vmlinuz (or linux, bzImage)
Initrd: initrd, initrd.gz, initrd.lz
Squashfs (Ubuntu/Debian live): filesystem.squashfs
Distribution metadata: OS type, boot parameters

Extracted files location:

/data/isos/
├── ubuntu-24.04.iso                    # Original ISO
└── ubuntu-24.04/                       # Extracted directory
    ├── vmlinuz                         # Kernel
    ├── initrd                          # Initrd
    └── casper/
        └── filesystem.squashfs         # Squashfs filesystem

Automatic Boot Method Selection#

After extraction, Bootimus automatically selects the optimal boot method:

Distribution	Boot Method	Downloads
Ubuntu Desktop (extracted)	`fetch=`	~2.8GB (squashfs only)
Ubuntu Desktop (not extracted)	`url=`	~18GB (ISO × 3)
Ubuntu Server (netboot)	Netboot	~50MB (netboot files)
Debian Installer (netboot)	Netboot	~30MB (netboot files)
Arch Linux	HTTP boot	~100MB (kernel/initrd)
Fedora/RHEL	HTTP boot	~150MB (kernel/initrd + stage2)

Netboot Support#

Some installer ISOs (Debian, Ubuntu Server) don’t contain a full OS - they’re designed to download packages during installation. For these, Bootimus supports downloading official netboot files.

Detecting Netboot Requirement#

When you extract a Debian or Ubuntu Server installer ISO, Bootimus detects it requires netboot:

Indicators:

ISO contains /install/ directory (not /casper/)
Installer type (not live/desktop)
Small ISO size (< 1GB)

Admin panel shows:

“Netboot Required” badge
📥 “Download Netboot” button

Downloading Netboot Files#

Via Web Interface:

Navigate to Images tab
Find the installer ISO with “Netboot Required” badge
Click “Download Netboot” button
Wait for download and extraction

Via API:

curl -u admin:password -X POST http://localhost:8081/api/images/netboot/download \
  -H "Content-Type: application/json" \
  -d '{"filename": "debian-13.2.0-amd64-netinst.iso"}'

What Are Netboot Files?#

Netboot files are official, minimal boot files provided by distributions:

Debian netboot:

Source: http://ftp.debian.org/debian/dists/trixie/main/installer-amd64/current/images/netboot/netboot.tar.gz
Size: ~30MB
Contains: vmlinuz, initrd.gz, installer files

Ubuntu netboot:

Source: http://archive.ubuntu.com/ubuntu/dists/noble/main/installer-amd64/current/legacy-images/netboot/netboot.tar.gz
Size: ~50MB
Contains: vmlinuz, initrd.gz, installer files

How Netboot Works#

Client boots: Downloads netboot kernel/initrd (~50MB)
Installer starts: Netboot initrd starts network installer
Package download: Installer downloads packages from Ubuntu/Debian mirrors
Installation: OS installed directly from internet repositories

Benefits:

Always get latest packages (not stale ISO packages)
Minimal bandwidth to PXE server (no ISO download)
Smaller storage requirements
Official, signed boot files

Debian Installer Netboot#

Supported ISOs:

debian-*-netinst.iso - Network installer
Small Debian installer ISOs with /install/ directory

Detection:

ISO structure:
├── install/
│   ├── vmlinuz
│   └── initrd.gz

Netboot URL: http://ftp.debian.org/debian/dists/trixie/main/installer-amd64/current/images/netboot/netboot.tar.gz

Boot parameters: priority=critical ip=dhcp

Ubuntu Server Netboot#

Supported ISOs:

ubuntu-*-live-server-*.iso - Live server installer with /install/ directory
Older Ubuntu server installers

Detection:

ISO structure:
├── install/
│   ├── vmlinuz
│   └── initrd.gz

Netboot URL: http://archive.ubuntu.com/ubuntu/dists/noble/main/installer-amd64/current/legacy-images/netboot/netboot.tar.gz

Boot parameters: ip=dhcp

Important: Ubuntu Desktop vs Server#

There are two types of Ubuntu ISOs with different boot methods:

Type	ISO Name Pattern	Directory	Boot Method	Netboot?
Desktop/Live	`ubuntu--desktop-.iso`	`/casper/`	`fetch=` or `url=`	No
Server Installer	`ubuntu--live-server-.iso` (with `/install/`)	`/install/`	Netboot	Yes

Ubuntu Desktop (/casper/):

Contains full live OS
Uses casper boot with fetch= or url=
Extract kernel to use fetch= (downloads squashfs only)
No netboot support

Ubuntu Server Installer (/install/):

Minimal network installer
Requires netboot files
Downloads packages during installation
Much more efficient

Ubuntu Desktop Optimisation#

Ubuntu Desktop ISOs use the casper live boot system. Without optimisation, they download the entire ISO three times (~18GB for a 6GB ISO).

Problem: Triple ISO Download#

Default behaviour (no extraction):

Boot parameter: url=http://server/ubuntu.iso

Result:
- Download 1: Kernel verifies ISO (6GB)
- Download 2: Initrd verifies ISO (6GB)
- Download 3: Casper mounts ISO (6GB)
Total: ~18GB downloaded

Solution 1: Extract and Use `fetch=` Parameter#

After extraction:

Boot parameter: fetch=http://server/ubuntu/casper/filesystem.squashfs

Result:
- Download: Only squashfs (~2.8GB)
Total: ~2.8GB downloaded

How to enable:

Extract kernel/initrd from ISO
Bootimus automatically uses fetch= parameter
Only squashfs downloaded (not entire ISO)

Savings: 85% reduction (18GB → 2.8GB)

Solution 2: Use Ubuntu Server Netboot Instead#

For server deployments, use Ubuntu Server installer with netboot:

Netboot approach:

1. Upload ubuntu-server.iso
2. Extract kernel/initrd
3. Download netboot files
4. Boot with netboot (~50MB download)
5. Install from Ubuntu repositories

Savings: 99% reduction (18GB → 50MB)

Boot Parameter Reference#

Ubuntu Desktop (casper):

# Default (no extraction) - downloads ISO 3 times
boot=casper root=/dev/ram0 ramdisk_size=1500000 cloud-init=disabled ip=dhcp url=http://server/ubuntu.iso

# Optimised (with extraction) - downloads squashfs once
boot=casper root=/dev/ram0 ramdisk_size=1500000 cloud-init=disabled ip=dhcp fetch=http://server/ubuntu/casper/filesystem.squashfs

Ubuntu Server (netboot):

# Netboot - minimal download
ip=dhcp

Supported Distributions#

Fully Tested#

Distribution	Kernel Extraction	Netboot	Notes
Arch Linux	Yes	N/A	`/arch/boot/x86_64/vmlinuz-linux`
Fedora Workstation	Yes	N/A	`/isolinux/vmlinuz`
Rocky Linux	Yes	N/A	`/isolinux/vmlinuz`
Debian (installer)	Yes	Yes	`/install/vmlinuz` + netboot
Debian Live	Yes	No	`/live/vmlinuz`
Ubuntu Desktop	Yes	No	`/casper/vmlinuz` + fetch optimisation
Ubuntu Server	Yes	Yes	`/install/vmlinuz` + netboot
Pop!_OS	Yes	No	`/casper/vmlinuz`
TrueNAS SCALE	Yes	No	`/vmlinuz` + `/initrd.img` (root)
Proxmox VE	Yes	No	`/boot/linux26` + `/boot/initrd.img`
openSUSE	Yes	N/A	`/boot/x86_64/loader/linux`
NixOS	N/A	N/A	Sanboot

Detection Patterns#

Bootimus detects distributions by scanning for specific file patterns:

Arch Linux:

/arch/boot/x86_64/vmlinuz-linux
/arch/boot/x86_64/initramfs-linux.img

Fedora/RHEL/Rocky:

/isolinux/vmlinuz
/isolinux/initrd.img

Ubuntu Desktop (casper):

/casper/vmlinuz or /casper/vmlinuz.efi
/casper/initrd or /casper/initrd.gz or /casper/initrd.lz
/casper/filesystem.squashfs

Ubuntu Server Installer:

/install/vmlinuz or /install.amd/vmlinuz
/install/initrd.gz or /install.amd/initrd.gz

Debian Installer:

/install/vmlinuz or /install.amd/vmlinuz
/install/initrd.gz or /install.amd/initrd.gz

TrueNAS SCALE:

/vmlinuz
/initrd.img
/live/filesystem.squashfs

Proxmox VE:

/boot/linux26
/boot/initrd.img

Troubleshooting#

Extraction Failed#

Symptoms: “Extraction failed” error in admin panel

Common causes:

Corrupted ISO: Re-download the ISO
Unsupported ISO: Check if distribution is supported
Disk space: Ensure sufficient space for extraction
Permissions: Check file permissions on data directory

Debugging:

# Check extraction logs
docker logs bootimus | grep -i extract

# Verify ISO integrity
sha256sum ubuntu.iso

# Check disk space
df -h /data/isos/

# Test manual mount
sudo mount -o loop ubuntu.iso /mnt
ls /mnt/casper/
sudo umount /mnt

Netboot Download Failed#

Symptoms: “Netboot download failed” error

Common causes:

Network connectivity: Cannot reach Debian/Ubuntu mirrors
URL changed: Mirror URL may have been updated
Tarball extraction failed: Corrupted download

Solutions:

# Test mirror connectivity
curl -I http://ftp.debian.org/debian/dists/trixie/main/installer-amd64/current/images/netboot/netboot.tar.gz

# Check server logs
docker logs bootimus | grep -i netboot

# Manually verify netboot URL
wget http://archive.ubuntu.com/ubuntu/dists/noble/main/installer-amd64/current/legacy-images/netboot/netboot.tar.gz
tar -tzf netboot.tar.gz | grep vmlinuz

Symptoms: Image shows “[kernel]” badge but doesn’t boot with kernel method

Cause: Database and filesystem out of sync

Solution:

# Re-extract kernel/initrd
curl -u admin:password -X POST http://localhost:8081/api/images/extract \
  -H "Content-Type: application/json" \
  -d '{"filename": "ubuntu-24.04.iso"}'

# Or re-scan ISOs
curl -u admin:password -X POST http://localhost:8081/api/scan

Client Downloads ISO Multiple Times#

Symptoms: Ubuntu Desktop ISO downloads 3 times

Cause: Using url= parameter without extraction

Solution:

Extract kernel/initrd from ISO
Bootimus will automatically use fetch= parameter
Only squashfs downloaded (not entire ISO)

Verify:

# Check if extracted
ls -la /data/isos/ubuntu-24.04/casper/filesystem.squashfs

# Check server logs during boot
docker logs -f bootimus
# Look for: "fetch=..." instead of "url=..."

Netboot Required but No Download Button#

Symptoms: Image shows “Netboot Required” but no download button

Cause: Netboot URL not configured or detection failed

Solution:

# Check image details
curl -u admin:password http://localhost:8081/api/images | jq '.data[] | select(.filename=="debian-13.2.0-amd64-netinst.iso")'

# Verify netboot_required and netboot_url fields
# If netboot_url is empty, the ISO detection may have failed

# Try re-extracting
curl -u admin:password -X POST http://localhost:8081/api/images/extract \
  -H "Content-Type: application/json" \
  -d '{"filename": "debian-13.2.0-amd64-netinst.iso"}'

Next Steps#

See Admin Console Guide for managing images
Read Deployment Guide for storage configuration
Configure DHCP Server for PXE booting
Set up Client Management for access control

Image Management Guide#

Table of Contents#

Adding Images#

Upload via Web Interface#

Upload via API#

Download from URL#

Organise with Folders#

Scan Existing ISOs#

Kernel Extraction#

Benefits of Kernel Extraction#

How to Extract#

Manual Extraction#

What Gets Extracted#

Automatic Boot Method Selection#

Netboot Support#

Detecting Netboot Requirement#

Downloading Netboot Files#

What Are Netboot Files?#

How Netboot Works#

Debian Installer Netboot#

Ubuntu Server Netboot#

Important: Ubuntu Desktop vs Server#

Ubuntu Desktop Optimisation#

Problem: Triple ISO Download#

Solution 1: Extract and Use fetch= Parameter#

Solution 2: Use Ubuntu Server Netboot Instead#

Boot Parameter Reference#

Supported Distributions#

Fully Tested#

Detection Patterns#

Troubleshooting#

Extraction Failed#

Netboot Download Failed#

Boot Menu Shows Wrong Image Type#

Client Downloads ISO Multiple Times#

Netboot Required but No Download Button#

Next Steps#

Solution 1: Extract and Use `fetch=` Parameter#