secubox-deb/docs/LIVE-USB.md

SecuBox Live USB

Bootable live USB image for SecuBox security appliance.

Features

• UEFI Boot with GRUB bootloader
• SquashFS compressed root filesystem (~250MB)
• OverlayFS for runtime changes
• Persistence partition for saving changes across reboots
• Slipstream all SecuBox packages pre-installed

Download

Get the latest release from GitHub Releases or build from source.

Flash to USB

# Decompress and write to USB drive (replace /dev/sdX with your device)
zcat secubox-live-amd64-bookworm.img.gz | sudo dd of=/dev/sdX bs=4M status=progress
sync

Warning: This will erase all data on the target device. Double-check the device name!

Find your USB device

# List block devices
lsblk

# Or use dmesg after inserting USB
dmesg | tail -20

Boot Options

The GRUB menu offers several boot modes:

Option	Description
SecuBox Live	Normal boot with persistence enabled
Safe Mode	Minimal drivers for troubleshooting
No Persistence	Fresh start, changes not saved
To RAM	Load entire system to memory (remove USB after boot)

Default Credentials

Service	Username	Password
SSH	root	secubox
SSH	secubox	secubox
Web UI	admin	admin

Important: Change these passwords immediately after first boot!

# Change root password
passwd

# Change secubox user password
passwd secubox

Network Configuration

The live system auto-configures networking:

• DHCP on all detected interfaces
• Static fallback: 192.168.1.1/24 on first interface
• Web UI: https://<IP>:8443

Find your IP address

ip addr show
# or
hostname -I

Persistence

Changes are saved to the persistence partition automatically. This includes:

• User files in /home
• Configuration in /etc
• Installed packages
• Log files

Disable persistence temporarily

Select "No Persistence" from the boot menu, or add nopersistence to kernel parameters.

Reset persistence

# Mount persistence partition
sudo mount /dev/sdX3 /mnt

# Clear all saved changes
sudo rm -rf /mnt/*

# Unmount
sudo umount /mnt

Partition Layout

Partition	Size	Type	Mount	Description
p1	512MB	EFI System	/boot/efi	GRUB bootloader
p2	2GB	FAT32	/run/live/medium	Live system (squashfs)
p3	Remaining	ext4	/run/live/persistence	Persistent storage

Building from Source

Prerequisites

sudo apt-get install -y \
  debootstrap parted dosfstools e2fsprogs \
  squashfs-tools grub-efi-amd64-bin grub-pc-bin \
  xorriso mtools rsync

Build

# Basic build (8GB image)
sudo bash image/build-live-usb.sh --size 8G

# Without persistence partition
sudo bash image/build-live-usb.sh --size 4G --no-persistence

# With slipstream (include .deb packages)
sudo bash image/build-live-usb.sh --size 8G --slipstream

Output

output/
  secubox-live-amd64-bookworm.img.gz      # Compressed image
  secubox-live-amd64-bookworm.img.gz.sha256  # Checksum

Verify Download

# Check SHA256 checksum
sha256sum -c secubox-live-amd64-bookworm.img.gz.sha256

# Verify GPG signature (if available)
gpg --verify SHA256SUMS.gpg

Troubleshooting

USB not booting

1. Check BIOS/UEFI settings - enable USB boot
2. Disable Secure Boot (or enroll SecuBox keys)
3. Try different USB port (USB 2.0 ports may be more compatible)

Black screen after boot

1. Select "Safe Mode" from boot menu
2. Try adding nomodeset to kernel parameters

No network

# Check interface status
ip link show

# Restart networking
sudo systemctl restart networking

# Manual DHCP
sudo dhclient eth0

Persistence not working

1. Check partition exists: lsblk
2. Check label: sudo blkid | grep persistence
3. Check mount: mount | grep persistence

Included Packages

The live image includes all SecuBox packages:

• Core: secubox-core, secubox-hub, secubox-portal
• Security: secubox-crowdsec, secubox-waf, secubox-auth, secubox-nac
• Networking: secubox-wireguard, secubox-netmodes, secubox-dpi, secubox-qos
• Applications: secubox-mail, secubox-gitea, secubox-nextcloud
• Publishing: secubox-droplet, secubox-streamlit, secubox-metablogizer

Support

• GitHub Issues: https://github.com/CyberMind-FR/secubox-deb/issues
• Documentation: https://secubox.in/docs