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

en → zh-CN

docs / Admin Console

Admin Console

Web UI tour and REST API reference.

在 GitHub 上编辑 ↗

Admin Console Guide#

Complete guide for using the Bootimus admin interface and REST API.

Table of Contents#

Accessing the Admin Panel
Dashboard
Client Management
Image Management
Boot Logs
REST API
Automation Examples
Security Best Practises

Accessing the Admin Panel#

Web Interface#

http://your-server:8081/

Requirements:

Admin interface runs on separate port (default 8081)
Works with SQLite or PostgreSQL
JWT token-based authentication (with optional LDAP/AD backend)

On first startup, Bootimus generates a random admin password:

╔════════════════════════════════════════════════════════════════╗
║                    ADMIN PASSWORD GENERATED                    ║
╠════════════════════════════════════════════════════════════════╣
║  Username: admin                                                ║
║  Password: AbCdEfGh1234567890-_XyZ123456                       ║
╠════════════════════════════════════════════════════════════════╣
║  This password will NOT be shown again!                        ║
║  Save it now or reset it using --reset-admin-password flag    ║
╚════════════════════════════════════════════════════════════════╝

Navigate to http://your-server:8081 and you’ll see a dedicated login page. Enter the admin credentials to access the panel.

Login credentials:

Username: admin
Password: Check server startup logs

If LDAP is configured, a dropdown will appear on the login page allowing you to choose between local and LDAP authentication. See Authentication Guide for details.

Quick Start#

Start Bootimus:

docker-compose up -d
# OR
./bootimus serve

Copy the admin password from server logs
Open browser to http://localhost:8081/
Log in with username admin and generated password

Dashboard#

The dashboard provides real-time statistics:

Total clients - All registered clients
Active clients - Enabled clients that can boot
Total images - All ISO images
Enabled images - Images available in boot menu
Total boots - Number of boot attempts

All statistics update in real-time via WebSocket/SSE.

Client Management#

Add a Client#

Click “Add Client” button
Enter MAC address (format: 00:11:22:33:44:55)
Optionally add name and description
Check “Enabled” to allow booting
Click “Create Client”

Via API:

curl -u admin:password -X POST http://localhost:8081/api/clients \
  -H "Content-Type: application/json" \
  -d '{
    "mac_address": "00:11:22:33:44:55",
    "name": "Lab Machine 1",
    "description": "Test workstation",
    "enabled": true
  }'

Edit a Client#

Click “Edit” on any client row
Modify name, description, or enabled status
Select which ISOs this client can access (multi-select)
Click “Update Client”

Via API:

curl -u admin:password -X PUT "http://localhost:8081/api/clients?mac=00:11:22:33:44:55" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "enabled": false
  }'

Delete a Client#

Click “Delete” on any client row and confirm deletion.

Via API:

curl -u admin:password -X DELETE "http://localhost:8081/api/clients?mac=00:11:22:33:44:55"

Assign Images to Client#

Via Web Interface:

Click “Edit” on client
Select images from multi-select dropdown
Click “Update Client”

Via API:

curl -u admin:password -X POST http://localhost:8081/api/clients/assign \
  -H "Content-Type: application/json" \
  -d '{
    "mac_address": "00:11:22:33:44:55",
    "image_filenames": ["ubuntu-24.04.iso", "debian-12.iso"]
  }'

Image Management#

Upload an ISO#

Via Web Interface:

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 limit: 10GB per file

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 server:

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

Extract Kernel/Initrd#

Extract boot files for faster booting and reduced bandwidth:

Via Web Interface:

Find image in Images tab
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.iso"}'

Benefits:

Faster boot (download 100MB instead of 6GB)
Reduced bandwidth (critical for multiple clients)
Better compatibility (some ISOs don’t support sanboot)

See Image Management Guide for detailed extraction information.

Download Netboot Files#

For Debian/Ubuntu installer ISOs that require netboot:

Via Web Interface:

Find image 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?

Official minimal boot files from Debian/Ubuntu
~30-50MB download (instead of full ISO)
Installer downloads packages from internet during installation
Always get latest packages

See Netboot Support for details.

Scan for ISOs#

Scan data directory for manually added ISOs:

Via Web Interface:

Manually copy ISO files to /data/isos/ directory
Click “Scan for ISOs” button
Bootimus detects and registers new ISOs

Via API:

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

Enable/Disable Image#

Via Web Interface:

Click “Enable” or “Disable” button on any image
Disabled images won’t appear in boot menus

Via API:

curl -u admin:password -X PUT "http://localhost:8081/api/images?filename=ubuntu.iso" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Make Public/Private#

Via Web Interface:

Click “Make Public” to allow all clients to access
Click “Make Private” to restrict to assigned clients only

Via API:

curl -u admin:password -X PUT "http://localhost:8081/api/images?filename=ubuntu.iso" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

Delete Image#

Via Web Interface:

Click “Delete” on any image row
Confirm deletion
Image removed from database
ISO file remains on disk (delete manually if needed)

Via API:

# Delete from database only
curl -u admin:password -X DELETE "http://localhost:8081/api/images?filename=ubuntu.iso"

# Delete from database and filesystem
curl -u admin:password -X DELETE "http://localhost:8081/api/images?filename=ubuntu.iso&delete_file=true"

Boot Logs#

View recent boot attempts with live streaming:

Information shown:

Timestamp
Client MAC address
Image name
IP address
/ Success/failure status
Error messages (if any)

Auto-refresh: Logs update in real-time via SSE (Server-Sent Events)

Via API:

# Get last 100 logs (default)
curl -u admin:password http://localhost:8081/api/logs

# Get last 10 logs
curl -u admin:password http://localhost:8081/api/logs?limit=10

# Get last 500 logs (max 1000)
curl -u admin:password http://localhost:8081/api/logs?limit=500

REST API#

All admin functions available via REST API for automation.

Authentication#

HTTP Basic Authentication required for all endpoints:

Username: admin
Password: Auto-generated on first run

curl -u admin:your-password http://localhost:8081/api/stats

API Endpoints#

Stats#

GET /api/stats

Response:

{
  "success": true,
  "data": {
    "total_clients": 10,
    "active_clients": 8,
    "total_images": 5,
    "enabled_images": 4,
    "total_boots": 127
  }
}

Clients#

Method	Endpoint	Description
`GET`	`/api/clients`	List all clients
`GET`	`/api/clients?mac=<MAC>`	Get client by MAC
`POST`	`/api/clients`	Create client
`PUT`	`/api/clients?mac=<MAC>`	Update client
`DELETE`	`/api/clients?mac=<MAC>`	Delete client
`POST`	`/api/clients/assign`	Assign images to client

Images#

Method	Endpoint	Description
`GET`	`/api/images`	List all images
`GET`	`/api/images?filename=<name>`	Get image
`PUT`	`/api/images?filename=<name>`	Update image
`DELETE`	`/api/images?filename=<name>`	Delete image
`POST`	`/api/images/upload`	Upload ISO
`POST`	`/api/images/download`	Download ISO from URL
`POST`	`/api/images/extract`	Extract kernel/initrd
`POST`	`/api/images/netboot/download`	Download netboot files
`POST`	`/api/scan`	Scan for new ISOs

Downloads#

Method	Endpoint	Description
`GET`	`/api/downloads`	List active downloads
`GET`	`/api/downloads/progress?filename=<name>`	Get download progress

Logs#

Method	Endpoint	Description
`GET`	`/api/logs?limit=<N>`	Get boot logs
`GET`	`/api/logs/stream`	SSE stream of real-time logs

Automation Examples#

Bulk Add Clients#

#!/bin/bash
# bulk-add-clients.sh

ADMIN_PASSWORD="${ADMIN_PASSWORD:-your-password}"

CLIENTS=(
  "00:11:22:33:44:01:Server1"
  "00:11:22:33:44:02:Server2"
  "00:11:22:33:44:03:Workstation1"
)

for entry in "${CLIENTS[@]}"; do
  IFS=':' read -r mac1 mac2 mac3 mac4 mac5 mac6 name <<< "$entry"
  mac="${mac1}:${mac2}:${mac3}:${mac4}:${mac5}:${mac6}"

  curl -u admin:$ADMIN_PASSWORD -X POST http://localhost:8081/api/clients \
    -H "Content-Type: application/json" \
    -d "{\"mac_address\":\"$mac\",\"name\":\"$name\",\"enabled\":true}"

  echo "Added $name ($mac)"
done

Make All Images Public#

#!/bin/bash
# make-all-public.sh

ADMIN_PASSWORD="${ADMIN_PASSWORD:-your-password}"

images=$(curl -u admin:$ADMIN_PASSWORD -s http://localhost:8081/api/images | jq -r '.data[].filename')

for filename in $images; do
  curl -u admin:$ADMIN_PASSWORD -X PUT "http://localhost:8081/api/images?filename=$filename" \
    -H "Content-Type: application/json" \
    -d '{"public":true}'
  echo "Made $filename public"
done

Monitor Boot Attempts#

#!/bin/bash
# monitor-boots.sh

ADMIN_PASSWORD="${ADMIN_PASSWORD:-your-password}"

while true; do
  clear
  echo "=== Recent Boot Attempts ==="
  curl -u admin:$ADMIN_PASSWORD -s http://localhost:8081/api/logs?limit=20 | \
    jq -r '.data[] | "\(.created_at) | \(.mac_address) | \(.image_name) | \(if .success then "" else "✗" end)"'
  sleep 5
done

Export Statistics#

#!/bin/bash
# export-stats.sh

ADMIN_PASSWORD="${ADMIN_PASSWORD:-your-password}"

echo "Bootimus Usage Report - $(date)"
echo "================================"

stats=$(curl -u admin:$ADMIN_PASSWORD -s http://localhost:8081/api/stats | jq '.data')

echo "Total Clients: $(echo $stats | jq -r '.total_clients')"
echo "Active Clients: $(echo $stats | jq -r '.active_clients')"
echo "Total Images: $(echo $stats | jq -r '.total_images')"
echo "Total Boots: $(echo $stats | jq -r '.total_boots')"

echo -e "\nTop Clients by Boot Count:"
curl -u admin:$ADMIN_PASSWORD -s http://localhost:8081/api/clients | \
  jq -r '.data | sort_by(.boot_count) | reverse | .[:5] | .[] | "\(.boot_count) boots - \(.name // .mac_address)"'

Security Best Practises#

Network Isolation#

Keep admin port separate from boot network:

# Allow boot traffic (TFTP/HTTP) on one interface
# Allow admin traffic on different interface or localhost only

Firewall Rules#

# Allow admin access only from specific IP range
sudo ufw allow from 192.168.1.0/24 to any port 8081

# Or block admin port from external access entirely
sudo ufw deny 8081

SSH Tunnel#

Access admin interface securely via SSH tunnel:

# Create SSH tunnel
ssh -L 8081:localhost:8081 user@bootimus-server

# Access admin panel
open http://localhost:8081/

VPN Access#

Place Bootimus admin port on VPN network only
Require VPN connection for admin access
Keep boot ports (69, 8080) on separate network segment

Password Management#

Store admin password securely (password manager)
Rotate password periodically by deleting .admin_password and restarting
🛡 Consider additional authentication layer (nginx with client certs)

Troubleshooting#

Admin Interface Not Loading#

# Check service is running
docker ps | grep bootimus

# Check logs
docker logs bootimus

# Verify port is accessible
curl -u admin:password http://localhost:8081/api/stats

# Check firewall
sudo ufw status | grep 8081

Cannot Upload Large ISOs#

# Check available disk space
df -h /opt/bootimus/data

# Upload limit is 10GB by default
# For larger ISOs, use download from URL or manual copy + scan

Changes Not Reflecting#

Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)
Check browser console for errors (F12)
Verify API responses with curl
Check server logs for detailed errors

API Returns Errors#

# Check request format (JSON content-type for POST/PUT)
curl -v -u admin:password -X POST http://localhost:8081/api/clients \
  -H "Content-Type: application/json" \
  -d '{"mac_address":"00:11:22:33:44:55","name":"Test"}'

# Verify resource exists for update/delete
curl -u admin:password http://localhost:8081/api/images | jq

# Check server logs
docker logs bootimus | tail -50

Next Steps#

Read Image Management Guide for ISO handling
See Deployment Guide for production setup
Configure DHCP Server for PXE booting
Set up Client Management for access control

Admin Console Guide#

Table of Contents#

Accessing the Admin Panel#

Web Interface#

First-Time Login#

Quick Start#

Dashboard#

Client Management#

Add a Client#

Edit a Client#

Delete a Client#

Assign Images to Client#

Image Management#

Upload an ISO#

Download from URL#

Extract Kernel/Initrd#

Download Netboot Files#

Scan for ISOs#

Enable/Disable Image#

Make Public/Private#

Delete Image#

Boot Logs#

REST API#

Authentication#

API Endpoints#

Stats#

Clients#

Images#

Downloads#

Logs#

Automation Examples#

Bulk Add Clients#

Make All Images Public#

Monitor Boot Attempts#

Export Statistics#

Security Best Practises#

Network Isolation#

Firewall Rules#

SSH Tunnel#

VPN Access#

Password Management#

Troubleshooting#

Admin Interface Not Loading#

Cannot Upload Large ISOs#

Changes Not Reflecting#

API Returns Errors#

Next Steps#