tsupdate

Update daemon for tsOS-based Raspberry Pi devices with A/B partition management and safe rollback.

Overview

tsupdate manages OS updates on Raspberry Pi devices using an A/B partition scheme with the tryboot mechanism for safe, atomic updates with automatic rollback.

Features

• System status monitoring - View OS version, partitions, and boot method
• A/B partition management - Dual root partitions (rootfs/clonefs) for safe updates
• Tryboot integration - Hardware-backed boot failsafe with automatic rollback
• Incremental updates - Apply rsync-based differential updates (pidiff)
• Image restoration - Restore complete OS images from various formats
• GitHub integration - Check for available updates from GitHub releases
• Partition operations - Mount, unmount, and sync partitions
• Boot management - Configure, persist, and rollback boot configurations
• Automatic updates - Background daemon for unattended update management

Installation

# Install from source
git clone https://github.com/trackit-systems/tsupdate.git
cd tsupdate
pip install -e .

Commands

System Information

status - Display current system status (OS version, partitions, boot method)

tsupdate status          # Human-readable output
tsupdate status --json   # JSON output

Boot Management

tryboot - Configure tryboot to switch to alternate partition

sudo tsupdate tryboot              # Configure and reboot automatically
sudo tsupdate tryboot --no-reboot  # Configure without reboot

persist - Make tryboot configuration permanent

sudo tsupdate persist           # Persist configuration
sudo tsupdate persist --reboot  # Persist and reboot

rollback - Revert from tryboot to previous partition

sudo tsupdate rollback              # Rollback and reboot automatically
sudo tsupdate rollback --no-reboot  # Rollback without reboot

Updates

check - Check GitHub releases for available updates

tsupdate check                                    # Check for updates
tsupdate check --pre                              # Include pre-releases
tsupdate check --max-releases 10                  # Check more releases
tsupdate check --github-url https://github.com/...  # Custom repository

apply - Apply incremental update to inactive partition

sudo tsupdate apply <url>          # Apply from URL
sudo tsupdate apply <file>         # Apply from local file
sudo tsupdate apply <url> -k       # Keep downloaded file

restore - Restore OS image to inactive partition

sudo tsupdate restore <url>        # Restore from URL
sudo tsupdate restore <file>       # Restore from local file
sudo tsupdate restore <url> -p 3   # Use partition 3 from image
sudo tsupdate restore <url> -k     # Keep downloaded image

Partition Operations

syncroot - Sync active partition to inactive partition

sudo tsupdate syncroot   # Clone current system to inactive partition

mount - Mount inactive partition to /media/root-up

sudo tsupdate mount   # Mount for manual access

unmount - Unmount inactive partition

sudo tsupdate unmount   # Unmount after manual access

Typical Workflows

Incremental Update

# 1. Check for updates
tsupdate check

# 2. Apply incremental update
sudo tsupdate apply https://github.com/.../update-2025.12.1-to-2025.12.2.tar

# 3. Reboot to test (automatic)

# 4. Persist if working correctly
sudo tsupdate persist

# Or rollback if issues found
sudo tsupdate rollback

Full Image Restore

# 1. Check for latest release
tsupdate check

# 2. Restore OS image
sudo tsupdate restore https://github.com/.../tsos-2025.12.2.img.gz

# 3. Reboot to test (automatic)

# 4. Persist or rollback
sudo tsupdate persist

Manual Partition Inspection

# Mount inactive partition
sudo tsupdate mount

# Inspect or modify files
ls /media/root-up
sudo nano /media/root-up/etc/config

# Unmount when done
sudo tsupdate unmount

Automatic Updates (Daemon)

The tsupdated daemon provides automatic background update management:

Installation

# Copy example configuration
sudo cp tsupdate.example.yml /boot/firmware/tsupdate.yml

# Install systemd service
sudo cp tsupdated.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now tsupdated

Configuration

Edit /boot/firmware/tsupdate.yml:

# Check for updates every hour
check_interval: 3600

# Include pre-releases
include_prereleases: false

# Wait 10 minutes before persisting after tryboot
persist_timeout: 600

# Give users 1 minute to cancel before reboot
update_countdown: 60

Monitoring

# Check daemon status
sudo systemctl status tsupdated

# View logs
sudo journalctl -u tsupdated -f

Cancelling Updates

During the countdown before reboot, cancel with:

# Send termination signal
sudo systemctl restart tsupdated

See daemon.md for complete documentation.

Creating Updates

Incremental update files (rsync batch files) can be created using pimod's pidiff tool:

# Compare two images and create an incremental update
pidiff --tar base.img updated.img

# This creates a tar archive containing the rsync batch file
# which can be applied using: tsupdate apply update.tar

GitHub Authentication

For private repositories, set GH_TOKEN environment variable or use GitHub CLI:

# Using environment variable
export GH_TOKEN="ghp_..."

# Or authenticate with GitHub CLI
gh auth login

# Commands now work with private repositories
tsupdate check
sudo tsupdate apply https://github.com/private-org/repo/releases/download/...

Requirements

• Python 3.11+
• Raspberry Pi with tryboot support (Pi 4, 400, CM4, Pi 5)
• A/B partition layout - mmcblk0p2 (rootfs) and mmcblk0p3 (clonefs)
• Root privileges for most operations

Documentation

Detailed documentation for each module is available in the docs/ directory:

• daemon.md - Automatic update daemon
• status.md - System status and partition detection
• tryboot.md - Tryboot configuration and management
• syncroot.md - Partition mounting and syncing
• apply.md - Incremental update application
• restore.md - OS image restoration
• github.md - GitHub API integration
• utils.md - File download and caching utilities

Version Scheme

tsupdate uses time-based versioning: YEAR.MONTH.COUNT

Examples: 2025.12.1, 2025.12.2, 2026.01.1

Authors

Jonas Höchst hoechst@trackit.systems

Links

• Raspberry Pi Tryboot Documentation
• pimod - Tool for creating Raspberry Pi images and incremental updates