Router-style upgrades for Pi-Star. Raspberry Pi OS kernel with Alpine Linux userland, A/B root partitions for safe over-the-air updates, and zero-touch configuration from the boot partition.
| Feature | Description |
|---|---|
| A/B Root Partitions | Safe upgrades with automatic rollback — if a new version fails, the system reverts itself |
| Zero-Touch Configuration | Drop pistar-config.txt on the boot partition to configure WiFi, SSH, hostname — works for first boot AND recovery |
| Minimal Footprint | Alpine Linux userland with musl libc — fits on a 4GB SD card with room to spare |
| Persistent /data | User data, SSH keys, and WiFi config survive upgrades via bind mounts from a dedicated partition |
| Secure by Default | SSH key-only auth, locked root account, minimal attack surface |
| SD Card Friendly | Logs on tmpfs to reduce write wear |
| Full Pi Compatibility | Official Raspberry Pi OS kernel and firmware for perfect hardware support |
# Extract the image
xz -d Pi-Star_OS-YYYY.MM.DD.RR.img.xz
# Write to SD card (replace /dev/sdX with your SD card device)
sudo dd if=Pi-Star_OS-YYYY.MM.DD.RR.img of=/dev/sdX bs=4M status=progress conv=fsyncMount the boot partition and set up WiFi, SSH, etc. without ever needing a monitor or keyboard:
# Mount the boot partition
mount /dev/sdX1 /mnt
# Copy and edit the configuration template
cp /mnt/pistar-config.txt.sample /mnt/pistar-config.txt
nano /mnt/pistar-config.txt
# Unmount when done
umount /mntSee Boot Configuration for all available options.
Insert the SD card and power on your Raspberry Pi. Connect via SSH or console:
- Username:
pi-star - Password:
raspberry(or your configured password)
Security Note: Change the password immediately after first login using
passwd
Pi-Star OS includes a zero-touch configuration system. Drop a file on the boot partition to configure the system — no monitor, no keyboard, no network required.
- On the boot partition, you'll find
pistar-config.txt.sample - Copy it to
pistar-config.txtand edit with your settings - On boot, the system processes the file and applies your configuration
- The config file is automatically deleted after processing for security
This works for first boot and recovery. If your WiFi config breaks, pop the SD card into a PC, drop a new pistar-config.txt on the boot partition, put it back, and reboot. No reflashing required.
Configure multiple WiFi networks with priority ordering:
# Networks are numbered 1-10; when more than one is in range, the highest
# number wins. wifi_ssid (no number) is network 1, the lowest priority.
wifi_ssid=HomeNetwork
wifi_password=HomePassword
# Preferred over network 1
wifi_ssid_2=WorkNetwork
wifi_password_2=WorkPassword
wifi_ssid_3=MobileHotspot
wifi_password_3=HotspotPassword
# WiFi country code (affects available channels)
wifi_country=GB# Set password for pi-star user
user_password=MySecurePassword
# Enable SSH password authentication (default is key-only)
enable_ssh_password=true
# Add SSH public key for secure access (recommended)
ssh_key=ssh-rsa AAAAB3NzaC1yc2EAAAA... user@example.comhostname=my-pistar
timezone=Europe/London
locale=en_GB.UTF-8# Pi-Star OS Boot Configuration
# WARNING: This file will be DELETED after processing for security!
# WiFi
wifi_ssid=MyHomeNetwork
wifi_password=MyHomePassword
wifi_ssid_2=WorkNetwork
wifi_password_2=WorkPassword
wifi_country=GB
# Security
user_password=MySecurePassword123!
enable_ssh_password=false
ssh_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDEx... user@example.com
# System
hostname=pistar-shack
timezone=Europe/London
locale=en_GB.UTF-8Pi-Star OS uses an A/B root partition scheme for safe, router-style upgrades. The system can update itself over the air and automatically roll back if something goes wrong.
Boot Partition (FAT32)
slot.conf - tracks active slot, pending state, boot counter
cmdline.txt - kernel command line (root= points to active slot)
kernel*.img, *.dtb - kernel and device tree files (shared, updated on upgrade)
Slot A (ext4) - root filesystem (active or inactive)
Slot B (ext4) - root filesystem (active or inactive)
Data (ext4) - persistent user data, bind-mounted into rootfs
pistar-upgrade --install
1. Downloads new rootfs to inactive slot
2. Builds the inactive slot's boot directory (slotA/ or slotB/) on the
boot partition; the running slot's boot files are never touched
3. Points config.txt's os_prefix at the new slot and marks it PENDING
4. User reboots to activate it
Boot watchdog (pistar-boot-watchdog)
5. Increments boot counter each boot while PENDING
6. If counter exceeds 3, rolls back automatically
Health check (pistar-health-check)
7. Polls for up to 2 minutes: Pi-Star MCP running and answering, and
an address on any interface (skipped if no network is configured)
8. If healthy, clears PENDING — upgrade confirmed
9. If not, watchdog handles rollback on next reboot
# Check for updates
sudo pistar-upgrade --check
# Download and install update to inactive slot
sudo pistar-upgrade --install
# View current slot status
pistar-slot-info
# Manual rollback to previous slot
sudo pistar-rollbackpistar-upgrade --check exits 0 if an update is available, 1 if up to date, and 2 on error.
Releases are tagged YYYY.MM.DD.RR, where RR is the release number for that day starting at 1 (e.g. 2026.10.01.1). The same string is used for the image and rootfs filenames, manifest.txt, /etc/pistar-os-release and slot.conf. An update is offered only when the published version is newer than the running one, compared field by field. Older images reporting 5.0.0 are treated as older than any date-based release.
| Partition | Size | Format | Mount Point | Purpose |
|---|---|---|---|---|
| P1 | 256 MB | FAT32 | /boot/firmware |
GPU firmware, config.txt, slot.conf; each slot's kernels, device trees, overlays and cmdline.txt in slotA/ and slotB/ |
| P2 | 1.5 GB | ext4 | / (slot A) |
Root filesystem A |
| P3 | 1.5 GB | ext4 | / (slot B) |
Root filesystem B |
| P4 | Remaining | ext4 | /data |
Persistent user data (expands on first boot) |
Each root slot has its own directory on the boot partition, slotA/ (root on P2) and slotB/ (root on P3), holding its kernels, device trees, overlays and cmdline.txt. The Raspberry Pi firmware loads the slot named by os_prefix in config.txt. Switching slots, for an upgrade or a rollback, rewrites that one line; an upgrade never touches the running slot's boot files. GPU firmware (start*.elf, fixup*.dat, bootcode.bin) is shared at the root of the partition, because the firmware loads it before reading config.txt.
Images from before this layout are migrated automatically on first boot by pistar-boot-layout, which builds both slot directories and leaves the old root-level files in place as a fallback.
If a slot won't boot: put the SD card in a PC, open config.txt on the boot partition, and change os_prefix=slotA/ to os_prefix=slotB/ (or the other way round). The block at the end of config.txt explains this too.
The /data partition provides persistence. /data/home is bind-mounted via fstab. All /data/etc/*/ and /data/var/lib/*/ directories are automatically bind-mounted over their /etc/ and /var/lib/ counterparts by the pistar-bindmounts init script at boot — empty directories are seeded from rootfs defaults on first use. /data/etc/dhcpcd and /data/var/lib/pistar-mcp are created at boot if missing, so older installs gain them too.
| Path | Bind Mount Source | Contents |
|---|---|---|
/home |
/data/home |
User home directories |
/etc/dropbear |
/data/etc/dropbear |
SSH host keys |
/etc/wpa_supplicant |
/data/etc/wpa_supplicant |
WiFi configuration |
/etc/dhcpcd |
/data/etc/dhcpcd |
dhcpcd.conf (static addressing); /etc/dhcpcd.conf is a symlink to it |
/etc/mmdvmhost |
/data/etc/mmdvmhost |
MMDVM-Host, MMDVM-Display and MMDVM-Info configuration |
/etc/dmrclients |
/data/etc/dmrclients |
DMR gateway/client configs |
/etc/dstarclients |
/data/etc/dstarclients |
D-Star gateway/client configs |
/etc/ysfclients |
/data/etc/ysfclients |
YSF gateway/client configs |
/etc/nxdnclients |
/data/etc/nxdnclients |
NXDN gateway/client configs |
/etc/p25clients |
/data/etc/p25clients |
P25 gateway/client configs |
/etc/fmclients |
/data/etc/fmclients |
FM gateway/client configs |
/etc/aprsclients |
/data/etc/aprsclients |
APRS gateway configs |
/etc/pocsagclients |
/data/etc/pocsagclients |
POCSAG gateway configs |
/etc/dstarrepeater |
/data/etc/dstarrepeater |
D-Star repeater configs |
/var/lib/pistar-mcp |
/data/var/lib/pistar-mcp |
Pi-Star MCP state (host file updates, backups) |
The pi-star password hash is kept in /data/etc/pistar-user.conf, created at boot if missing. Each newly installed slot restores it on its first boot; on later boots the saved copy is updated from /etc/shadow, so changes made with passwd or from the dashboard survive upgrades.
Adding persistence for a new package is as simple as creating its /data/etc/<name>/ directory.
Only user state lives in these directories: packages install their configuration templates to /usr/share/<name>/, which belongs to the slot and is replaced by every upgrade. At boot, pistar-bindmounts removes templates that older packages left in /data/etc/<name>/ once the active slot provides a replacement in /usr/share/<name>/, so stale templates never outlive the packages that shipped them.
boot runlevel:
localmount mounts /boot/firmware, /data, /home bind mount
pistar-bindmounts bind mounts /data/etc/*/ and /data/var/lib/*/ over the rootfs
pistar-config processes config file if present; keeps the saved password hash in step
pistar-boot-watchdog increments boot counter if PENDING
pistar-data-resize expands /data on first boot
wpa_supplicant connects to WiFi
dhcpcd gets IP address
default runlevel:
pistar-health-check checks MCP and network, clears PENDING
dropbear SSH server
crond runs scheduled updates set up by Pi-Star MCP
Pi-Star OS works with all Raspberry Pi models:
| Series | Models |
|---|---|
| Classic | Pi 1 Model A/B/B+ |
| Zero | Pi Zero, Zero W, Zero 2 W |
| Standard | Pi 2B, 3A+/B/B+, 4B, 5 |
| Compute | CM1, CM3, CM3+, CM4, CM4S |
| Special | Pi 400, Pi 500 |
DHCP is enabled by default on eth0. No configuration needed.
Method 1: Boot Configuration (Recommended)
Use pistar-config.txt as described in Boot Configuration.
Method 2: Manual Configuration
# Edit wpa_supplicant config (persists via /data bind mount)
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
# Add a network block:
# network={
# ssid="YourNetwork"
# psk="YourPassword"
# }
# Restart wpa_supplicant
sudo rc-service wpa_supplicant restartPi-Star OS uses Alpine's apk package manager:
# Update package index
apk update
# Install packages
apk add nano htop git
# Search for packages
apk search nginx
# Remove packages
apk del package-name# List all services
rc-status
# Start/stop/restart services
rc-service dropbear restart
# Enable/disable at boot
rc-update add myservice default
rc-update del myservice default| Issue | Solution |
|---|---|
| No network | Check cable/WiFi config, verify with ip addr show |
| WiFi not connecting | Check country code and password, inspect with wpa_cli status |
| SSH refused | Verify dropbear is running: rc-service dropbear status |
| Config not applied | File must be named exactly pistar-config.txt on the boot partition |
| Boot loop | Watchdog will auto-rollback after 3 failed boots |
| Recovery | Pop SD card out, mount boot partition on PC, drop pistar-config.txt, reboot |
From Raspberry Pi OS: Kernel images, device tree blobs, kernel modules (/usr/lib/modules/*), firmware blobs (/usr/lib/firmware/*), boot configuration files
From Alpine Linux: Complete userland (musl libc), OpenRC init system, BusyBox utilities, apk package manager, Dropbear SSH server
Pi-Star OS Specific: A/B partition scheme, boot watchdog and health check, upgrade/rollback system, boot configuration processor, persistent /data partition
Contributions are welcome! Please open an issue or submit a pull request.
git clone https://github.com/MW0MWZ/Pi-Star_OS.git
cd Pi-Star_OSThis project combines components from:
- Raspberry Pi OS - Raspberry Pi OS License
- Alpine Linux - Alpine License
- Raspberry Pi Foundation for kernel and firmware
- Alpine Linux Team for the minimal userland
- RasPINE for the base platform and APK repository
- The Amateur Radio community for continuous support