ShaniOS Technical Documentation

What is ShaniOS?

ShaniOS is an immutable Linux distribution that brings enterprise DevOps practices to desktop computing. Built on Arch Linux with Btrfs filesystem, it provides atomic updates, instant rollback, and system integrity by design.

3. System Optimizations

ShaniOS includes extensive performance, gaming, and reliability optimizations out of the box, eliminating the need for manual tweaking. These enterprise-grade optimizations are pre-configured and active from first boot.

Memory & Storage Management

• ZRAM Compression: Automatic RAM compression using the zstd algorithm (configured to use full RAM size) provides improved memory efficiency without requiring swap partitions. The system dynamically allocates compressed swap in RAM, reducing disk I/O and extending SSD lifespan.
• Optimized Swappiness: Tuned to 133 for balanced memory management on modern systems. This value encourages the kernel to use compressed ZRAM swap before evicting clean page cache, maintaining system responsiveness under memory pressure.
• Btrfs Maintenance: Automated filesystem maintenance runs in the background, including periodic scrubbing for data integrity, balance operations to optimize storage layout, and defragmentation for improved performance. These operations are scheduled to minimize impact on system usage.
• Profile Sync Daemon: Browser profiles are stored in tmpfs (RAM) for dramatically faster load times and reduced disk writes. Changes are periodically synchronized back to persistent storage, combining speed with data safety. This reduces SSD wear while improving browser responsiveness.
• Optimized Page Lock Unfairness: Set to 1 to reduce lock contention and improve multi-threaded application performance, particularly beneficial for databases and high-concurrency workloads.

Gaming & Performance Optimizations

ShaniOS is optimized for gaming performance with multiple layers of system tuning:

Gaming Hardware Support:

• game-devices-udev Package: Comprehensive udev rules for gaming peripherals with user-grade permissions, including:
  • Controllers: 8BitDo, PlayStation (DualShock 3/4, DualSense, DualSense Edge), Xbox (360, One, Series), Nintendo (Switch Pro, Joy-Cons, GameCube adapter), Google Stadia, NVIDIA Shield, Razer, Nacon, Hori, PowerA, PDP, Mad Catz, Astro C40, and more
  • Fight Sticks & Arcade: Razer Panthera, Mad Catz FightStick, Hit Box, and arcade-style controllers
  • VR Equipment: HTC Vive, PlayStation VR, Valve Index/SteamVR devices with full hardware access
  • Flight Sticks & Sim: VKBSim Gladiator, Logitech F310/F710, and other simulation controllers
  • uinput Support: Early creation of /dev/uinput for virtual device emulation (gamepad mappers, streaming tools)
• Additional RGB & Peripheral Support: OpenRGB udev rules (60-openrgb.rules) for comprehensive RGB control:
  • RGB Keyboards: ASUS Aura, Corsair, Razer, SteelSeries, Logitech G-series, MSI Mystic Light, Cooler Master, NZXT, and dozens more
  • RGB Mice: Gaming mice from all major manufacturers with LED control
  • RGB Mousepads: Corsair, Razer, SteelSeries, and other illuminated mousepads
  • RGB Accessories: Headset stands, mouse docks, PC case lighting, AIO coolers, and more
• Racing Wheel Support: Full force feedback and configuration access:
  • Logitech wheels (99-logitech-wheel-perms.rules): G29, G920, G923, G PRO, and legacy wheels (G25, G27, Driving Force, MOMO) with range, gain, LED, and force feedback tuning
  • Thrustmaster wheels (99-thrustmaster-wheel-perms.rules): T150, T300RS, T500RS, T248, TS-XW, TS-PC with spring, damper, and friction control
  • Fanatec wheels (99-fanatec-wheel-perms.rules): Full hardware access with deadzone removal via evdev-joystick
• Game Input Utilities:
  • AntiMicroX: Gamepad to keyboard/mouse mapper with uinput access (60-antimicrox-uinput.rules)
  • Steam Controller support: Native hardware access for Valve's gaming ecosystem

Kernel-Level Gaming Optimizations:

• Game Compatibility Kernel Parameters: Pre-configured for maximum compatibility:
  • Increased PID limit (65535) supports complex games with many processes
  • Expanded memory map areas (2147483642) accommodates large game worlds and high-resolution texture streaming
  • Enhanced inotify limits (1024 instances, 524288 watches) for games with extensive file monitoring
• Network Optimization: TCP FIN timeout reduced to 5 seconds (from default 60s) enables games to quickly reuse network ports when restarting. This Valve SteamOS optimization prevents "address already in use" errors in multiplayer games.
• CPU Scheduler Tuning: Multiple scheduler optimizations for gaming performance:
  • CFS bandwidth slice: 3000μs for improved interactivity and reduced input latency
  • Base slice: 3000000ns (3ms) for consistent frame times
  • Migration cost: 500000ns to prevent excessive CPU migration overhead
  • Migration limit: 8 tasks per balance operation for optimal multi-core utilization
  • Child runs first: Disabled (0) to prevent priority inversion in gaming scenarios
  • Autogroup scheduling: Enabled (1) to automatically group related processes for better desktop responsiveness
• Advanced Memory Management:
  • MGLRU (Multi-Gen LRU) enabled with aggressive settings for intelligent memory reclaim that preserves recently accessed game data
  • Transparent Hugepage set to madvise for selective large page usage, improving performance for games that explicitly request it
  • Optimized watermark scaling (500) and minimum free memory (1MB) for consistent response times under load
  • Reduced compaction proactiveness (0) minimizes latency spikes during memory allocation
  • Watermark boost factor: Set to 1 (minimal) to reduce aggressive memory reclaim
  • Zone reclaim disabled (0) prevents unnecessary NUMA overhead on multi-socket systems
• GameMode Integration: GameMode daemon enabled globally for all users, providing automatic performance optimizations when gaming. GameMode dynamically adjusts CPU governor, process priorities, I/O scheduling, and GPU performance levels. Games are automatically detected and optimized without manual configuration.
• High-Precision Timers: HPET and RTC frequencies increased to 3072 Hz (from default 64 Hz) for superior timing accuracy. This reduces input lag and improves frame pacing in games requiring precise timing, particularly beneficial for rhythm games and competitive shooters.

Process Management & Responsiveness

ShaniOS enables several system services for intelligent resource management:

• Ananicy-cpp: Automatic process priority management service with game-aware rules (enabled by default). Background tasks are automatically deprioritized when games or media applications are active, ensuring smooth performance without manual nice/renice commands.
• systemd-oomd: System-wide OOM (Out-Of-Memory) daemon enabled by default prevents system freezes. When memory pressure is detected, systemd-oomd selectively terminates low-priority processes based on memory usage patterns and process priorities, keeping critical services and active applications running.
• IRQBalance: Service enabled to optimize interrupt distribution across CPU cores, preventing a single core from becoming overwhelmed with hardware interrupts. This is particularly important for systems with high-bandwidth network cards or NVMe drives, ensuring balanced load across all cores.
• Increased File & Process Limits: Default limits raised to 1,048,576 for both open files (NOFILE) and processes (NPROC). This prevents "too many open files" errors in development environments, containerized workloads, and servers running multiple services.
• Fast Shutdown: Reduced timeout values (10s for stop, 10s for abort) ensure quick system shutdowns without waiting for unresponsive services. Services that fail to stop gracefully are automatically killed after the timeout.

Security Hardening

• AppArmor Mandatory Access Control:
  • AppArmor (apparmor.service): Enabled by default to confine system services and applications with security profiles
• Firewall Protection:
  • firewalld: Active firewall enabled by default, denying inbound connections while allowing essential services
  • Pre-configured rules: Automatic firewall configuration for KDE Connect/GSConnect and Waydroid during installation
• Kernel Hardening:
  • NMI watchdog disabled for faster boot times and reduced CPU overhead (this is safe on modern systems with other hang detection mechanisms)
  • Unprivileged user namespaces enabled for secure containerization (required for Podman, Flatpak sandboxing, and Distrobox)
  • Magic SysRq keys enabled for emergency recovery (Alt+SysRq+REISUB sequence for safe reboots during system hangs)
• Hardware Access Controls: The realtime group receives permission to access HPET and RTC devices directly. This is essential for professional audio production, real-time multimedia applications, and low-latency gaming. Users in the realtime group can run applications with real-time scheduling priorities.
• Blacklisted Kernel Modules:
  • PC speaker (pcspkr) disabled to eliminate annoying beeps
  • Intel Management Engine (mei, mei_me) disabled for enhanced privacy and security, removing Intel's remote management interface

Boot & System Efficiency

• Plymouth (BGRT Theme): Smooth graphical boot experience with the BGRT (Boot Graphics Resource Table) theme enabled by default. Plymouth provides a polished boot animation while hiding technical boot messages, presenting a clean interface for password entry during LUKS unlock. The BGRT theme displays your manufacturer's logo for a seamless firmware-to-OS transition.
• Journal Size Limit: SystemD journal capped at 50MB to prevent excessive disk usage from log accumulation. This is particularly important on systems with limited storage, while still maintaining sufficient logs for troubleshooting recent issues.
• Reduced Kernel Messages: Console printk level set to 3 (errors and critical messages only) for cleaner boot output. This eliminates informational noise while preserving important error messages needed for diagnostics.
• Optimized Service Startup: Parallel service initialization with optimized dependencies reduces boot time. Non-critical services are delayed or started on-demand, prioritizing services required for desktop readiness.
• Time Synchronization: systemd-timesyncd enabled by default for automatic network time protocol (NTP) synchronization, ensuring accurate system time without requiring a full NTP daemon.
• Socket Activation: Many services use socket activation for on-demand startup, reducing boot time and memory usage:
  • pcscd.socket: Smart card daemon (PC/SC) starts only when smart cards are accessed
  • lircd.socket: Linux Infrared Remote Control daemon for IR remote support
  • gpsd.socket: GPS daemon for location services and navigation hardware
  • cups.socket: Printing service starts on-demand when print jobs are sent
  • avahi-daemon.socket: Network service discovery (mDNS/DNS-SD) for zero-configuration networking
  • saned.socket: Scanner daemon starts when scanning is needed

Hardware & Peripheral Support

ShaniOS enables comprehensive hardware support services by default:

• Printing:
  • CUPS (cups.socket): Common UNIX Printing System for all printer support
  • cups-browsed: Automatic printer discovery on the network
  • ipp-usb: IPP-over-USB support for modern driverless printers
  • Avahi (avahi-daemon.socket): Network printer discovery via Bonjour/mDNS
• Scanning:
  • SANE (saned.socket): Scanner Access Now Easy for scanner support
  • ipp-usb: Also provides driverless scanning support
• Biometric Authentication:
  • fprintd: Fingerprint reader support for login and authentication
• Bluetooth:
  • bluetooth.service: Full Bluetooth stack for wireless peripherals, audio, and file transfer
• Mobile Devices:
  • usbmuxd: iOS device support for iPhone/iPad connectivity, file transfer, and tethering
• Networking:
  • NetworkManager: Intelligent network connection management for wired, wireless, VPN, and mobile connections
  • ModemManager: Mobile broadband modem support (3G/4G/5G)
• Gaming Peripherals:
  • ratbagd: Gaming mouse configuration daemon for DPI, button mapping, and LED control (libratbag)
  • inputattach: Serial input device support (legacy joysticks, game controllers)
• Location Services:
  • geoclue: Geolocation service for applications requiring location data
  • gpsd.socket: GPS hardware support
• Thunderbolt Security:
  • bolt: Thunderbolt 3 device authorization and management
• Power Management:
  • apcupsd: APC UPS monitoring and management for battery backup systems
  • power-profiles-daemon: System power profile management (performance, balanced, power-saver)
  • switcheroo-control: Hybrid graphics switching for laptops with dual GPUs (Intel + NVIDIA/AMD)
• Firmware Updates:
  • fwupd: Linux Vendor Firmware Service for automatic firmware updates
  • fwupd-refresh.timer: Periodic firmware update checks

Enhanced Shell Experience

ShaniOS provides a modern, feature-rich shell environment that rivals the best developer setups:

• Zsh as Default Shell: Powerful shell with advanced completion, globbing, and command-line editing. Zsh provides better defaults than Bash while maintaining compatibility with Bash scripts.
• Fish-Style Features:
  • Syntax highlighting shows valid/invalid commands in real-time as you type
  • Autosuggestions suggests commands from history with ghost text completion
  • History substring search allows arrow-up/down to search through history based on what you've typed
• Starship Prompt: Fast, minimal, and infinitely customizable prompt with intelligent git integration, showing branch status, ahead/behind commits, and repository state. The prompt adapts to display context-relevant information (Python virtualenv, Node.js version, Rust toolchain, etc.).
• McFly: Neural network-powered command history search learns from your usage patterns. McFly prioritizes frequently used commands in relevant directories and contexts, providing smarter suggestions than traditional reverse-i-search.
• FZF (Fuzzy Finder): Integrated fuzzy finding for files, command history, and directory navigation. Ctrl+R searches history, Ctrl+T inserts file paths, and Alt+C changes directories—all with fuzzy matching and preview windows.
• Multiple Shell Support: Bash and Fish shells included with completion support. Switch shells anytime with chsh while maintaining consistent functionality across all options.

Automated Maintenance

ShaniOS performs regular background maintenance to keep your system healthy without manual intervention. These systemd timers and services are enabled by default:

• btrfs-scrub.timer: Monthly scrubbing to detect and repair data corruption using filesystem checksums
• btrfs-balance.timer: Periodic filesystem balancing redistributes data across drives for optimal performance
• btrfs-defrag.timer: Automatic defragmentation runs on fragmented files to improve read performance
• btrfs-trim.timer: Regular TRIM operations for SSD optimization and lifespan extension
• profile-sync-daemon (psd): Browser cache synchronization from RAM to disk happens automatically (enabled globally for all users)
• systemd-timesyncd: Automatic time synchronization keeps system clock accurate
• ZRAM compression/decompression: Transparently handles memory pressure without user interaction

All maintenance operations are scheduled during low-usage periods and use minimal system resources to avoid impacting active work.

Key Concepts

1. Immutability

The root filesystem (/) is mounted read-only, preventing any modifications to system files. This ensures:

• Malware cannot modify system binaries
• Updates cannot partially fail and corrupt the system
• System always boots to a known-good state
• Configuration changes are isolated and manageable

2. Blue-Green Deployment

ShaniOS maintains two complete system images (@blue and @green). While one is active, updates are applied to the inactive one. On next boot, you switch to the updated system. If it fails, automatic rollback occurs.

3. Atomic Updates

Updates either succeed completely or fail safely—no partial updates that leave your system in a broken state. This is achieved through:

• Updating the inactive system image
• Switching boot target only after successful update
• Automatic rollback on boot failure

4. Selective Persistence

While the system is immutable, user data and configurations persist:

• /home: Your personal files and settings
• /etc: System configuration (via overlay filesystem)
• Service data: Application states, databases, containers

Understanding Immutability

ShaniOS's immutability fundamentally changes how you interact with the system. Understanding this concept is key to using ShaniOS effectively.

What You CAN Do

• ✅ Install applications via Flatpak
• ✅ Edit configuration files in /etc
• ✅ Create and modify files in /home
• ✅ Run containers (Podman, Distrobox, LXC)
• ✅ Update the entire system atomically
• ✅ Store data in /data and persistent subvolumes

What You CANNOT Do

• ❌ Use pacman to install traditional packages
• ❌ Modify files in / (root filesystem)
• ❌ Edit files in /usr, /bin, /lib directly
• ❌ Install software that requires system-level changes

Why This Design?

Blue-Green Deployment

ShaniOS implements blue-green deployment using Btrfs subvolumes—a strategy adapted from DevOps for desktop Linux.

How It Works

1. System maintains @blue and @green subvolumes
2. One subvolume is active (mounted as /), the other inactive
3. Updates apply to inactive subvolume
4. Bootloader updated to point to updated subvolume
5. Reboot switches to updated system
6. Previous version remains available for instant rollback

Advantages

• Atomic Updates: All-or-nothing updates
• Zero Downtime: Active system never modified
• Instant Rollback: Boot into previous version anytime
• Safe Testing: Validate updates before committing

Atomic Updates

ShaniOS uses an intelligent multi-layered update system with automatic checking, user notifications, and the shani-deploy tool for atomic system updates.

Persistence Strategy

ShaniOS selectively persists data across immutable system updates through bind mounts and dedicated subvolumes.

Bind-Mounted Service State

Critical service data is bind-mounted from @data subvolume:

# Example bind mounts from fstab

# Network configuration
/data/varlib/NetworkManager /var/lib/NetworkManager none bind,nofail 0 0

# Bluetooth pairings
/data/varlib/bluetooth /var/lib/bluetooth none bind,nofail 0 0

# systemd state
/data/varlib/systemd /var/lib/systemd none bind,nofail 0 0

What Persists

• Core: dbus, systemd, NetworkManager
• Authentication: AccountsService, fprint, bluetooth, boltd
• Display: gdm, sddm
• Hardware: colord, upower, cups, sane
• Security: firewalld
• Networking: geoclue, samba, nfs

Bind Mount Handling

ShaniOS intelligently handles bind mounts during configuration:

• Source check: Only mounts if source directory exists in @data
• Target check: Only mounts if service is installed in the system
• Graceful skipping: Missing services (e.g., sddm on GNOME) don't cause errors
• Optional services: Services not present in base system are automatically skipped

Spool Directory Persistence

In addition to /var/lib, some /var/spool directories are also persisted:

• anacron: Scheduled job state
• cron: Cron job state
• cups: Print queue
• samba: Samba print queue

System Requirements

Pre-Installation Setup

BIOS/UEFI Configuration

Configure your firmware before installation (typically accessed via F2, F10, Del, or Esc during startup):

Creating Installation Media

Download the ShaniOS ISO from shani.dev and write it to USB:

• Recommended: Balena Etcher (cross-platform, user-friendly)
• Windows: Rufus (advanced options available)
• Linux/Mac: dd command or GNOME Disks

Installation Steps

Installation takes approximately 10-15 minutes:

First Boot Configuration

On first boot, the Initial Setup wizard guides you through:

• Creating your user account
• Configuring network connections
• Setting privacy preferences
• Enabling location services (optional)
• Customizing appearance settings

This approach keeps installation fast while personalizing the system on first use.

Btrfs Deep Dive

ShaniOS leverages advanced Btrfs features for immutability and efficiency.

Copy-on-Write (CoW)

Btrfs CoW minimizes storage duplication:

• Shared data blocks between @blue and @green
• Only ~18% overhead despite dual root system
• Modified blocks consume additional space
• Efficient updates even with two complete systems

Transparent Compression

# Default mount options
compress=zstd,space_cache=v2,autodefrag

• Reduces disk usage by 30-50%
• Minimal CPU overhead
• Improves SSD lifespan

Performance Optimizations

Specific subvolumes use nodatacow:

• @swap: CoW disabled for swap files (required)
• @libvirt: VM disk images benefit from direct writes

Mount Options by Subvolume

Why noatime?

All subvolumes use noatime to improve performance:

• Prevents writing to disk every time a file is read
• Significantly reduces SSD wear
• Improves battery life on laptops
• No impact on most applications (very few rely on access times)

Filesystem Structure

ShaniOS uses Btrfs with a sophisticated subvolume layout:

Overlay Filesystem

OverlayFS enables writable /etc on read-only root.

# /etc overlay mount
overlay /etc overlay rw,lowerdir=/etc,upperdir=/data/overlay/etc/upper,workdir=/data/overlay/etc/work 0 0

Overlay Directories

Both /etc use overlay filesystems with this structure:

@data/overlay/etc/
  ├── lower/      # (unused, just structure)
  ├── upper/      # Your changes stored here
  └── work/       # Overlay working directory

Viewing Changes

# List all overlay modifications
ls -la /data/overlay/etc/upper

# Compare with base system
diff -r /etc /data/overlay/etc/upper

Boot Process

Understanding how ShaniOS boots:

Bootloader Configuration

ShaniOS uses systemd-boot with Unified Kernel Images (UKI):

• Timeout: 5 seconds
• Console mode: Maximum resolution
• Editor: Disabled for security (prevents boot parameter tampering)
• Default entry: Current active slot (@blue or @green)

Boot Entry Naming

Boot menu entries clearly show system state:

• shanios-blue (Active): Currently running system
• shanios-green (Candidate): Standby system for next update

After an update, the labels switch automatically.

UEFI Boot Entry

ShaniOS creates a UEFI boot entry during installation:

• Label: shanios
• Loader: \EFI\BOOT\BOOTX64.EFI (Shim for Secure Boot)
• Fallback: Boot entry creation failures don't stop installation

Shim and Secure Boot Chain

The boot chain when Secure Boot is enabled:

UEFI Firmware
    ↓
shimx64.efi (signed by Microsoft, validates next stage)
    ↓
grubx64.efi (actually systemd-boot, signed by MOK)
    ↓
Unified Kernel Image (signed by MOK)
    ↓
Linux Kernel + Initramfs

Kernel Command Line

ShaniOS uses these boot parameters:

quiet splash systemd.volatile=state ro 
lsm=landlock,lockdown,yama,integrity,apparmor,bpf 
rootfstype=btrfs 
rootflags=subvol=@blue,ro,noatime,compress=zstd,space_cache=v2,autodefrag
root=/dev/mapper/shani_root  # If encrypted
rd.luks.uuid=... rd.luks.name=... rd.luks.options=tpm2-device=auto  # If TPM enrolled
resume=UUID=... resume_offset=...  # If swapfile exists

Kernel Hardening

Security-focused kernel parameters are enabled by default:

lsm=landlock,lockdown,yama,integrity,apparmor,bpf

This enables multiple Linux Security Modules for layered protection:

• Landlock: Sandboxing for unprivileged processes
• Lockdown: Restricts kernel access from userspace
• Yama: Ptrace restrictions to prevent debugging attacks
• Integrity: File integrity measurement
• AppArmor: Mandatory Access Control profiles
• BPF: Secure BPF program loading

Kernel Parameter: systemd.volatile=state

The systemd.volatile=state kernel parameter creates a tmpfs (RAM-based) overlay for /var, making it volatile by default:

# From kernel command line
systemd.volatile=state

# Result: /var is tmpfs, cleared on every reboot
# Only explicitly mounted subdirectories persist

Hibernation Support

ShaniOS automatically configures hibernation if a swapfile is created:

• Swapfile location: /swap/swapfile (in @swap subvolume)
• Size: Equal to RAM (or less if disk space limited)
• Resume offset: Automatically calculated using btrfs inspect-internal map-swapfile
• Btrfs CoW: Disabled on @swap subvolume for reliability

Security Features

ShaniOS implements defense-in-depth security:

Secure Boot Setup

ShaniOS supports UEFI Secure Boot via Machine Owner Keys (MOK).

Automatic Secure Boot Enrollment (If Enabled During Install)

If you enabled Secure Boot during installation:

1. On first reboot, MOK Manager will appear automatically
2. Select "Enroll MOK"
3. Enter the password: shanios
4. Reboot to complete the enrollment
5. Secure Boot will be active with ShaniOS keys enrolled

Manual Secure Boot Enablement

To enable Secure Boot after installation:

sudo mokutil --import /etc/secureboot/keys/MOK.der

sudo mokutil --list-enrolled

TPM-Based Encryption

Enroll your LUKS encryption key to TPM 2.0 for automatic unlocking.

Prerequisites

• TPM 2.0 hardware module (enabled in BIOS/UEFI)
• LUKS2 encryption enabled during installation
• Recommended: Secure Boot enabled for maximum security

Enrollment Process

systemd-cryptenroll --tpm2-device=list

mokutil --sb-state

# Get the physical encrypted device
LUKS_DEVICE=$(sudo cryptsetup status shani_root | grep 'device:' | awk '{print $2}')
echo "Your encrypted device is: $LUKS_DEVICE"

# Example output: /dev/sda2 or /dev/nvme0n1p2

LUKS_DEVICE=$(sudo cryptsetup status shani_root | grep 'device:' | awk '{print $2}')
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+7 "$LUKS_DEVICE"

LUKS_DEVICE=$(sudo cryptsetup status shani_root | grep 'device:' | awk '{print $2}')
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0 "$LUKS_DEVICE"

sudo gen-efi configure blue
sudo gen-efi configure green

# Verify enrollment
LUKS_DEVICE=$(sudo cryptsetup status shani_root | grep 'device:' | awk '{print $2}')
sudo cryptsetup luksDump "$LUKS_DEVICE" | grep systemd-tpm2

Remove TPM Enrollment

To restore password-only unlocking:

LUKS_DEVICE=$(sudo cryptsetup status shani_root | grep 'device:' | awk '{print $2}')
sudo systemd-cryptenroll --wipe-slot=tpm2 "$LUKS_DEVICE"
sudo gen-efi configure blue
sudo gen-efi configure green

Re-enroll After Enabling Secure Boot

If you enable Secure Boot after TPM enrollment:

# Get the device
LUKS_DEVICE=$(sudo cryptsetup status shani_root | grep 'device:' | awk '{print $2}')

# Remove old enrollment
sudo systemd-cryptenroll --wipe-slot=tpm2 "$LUKS_DEVICE"

# Re-enroll with Secure Boot protection
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+7 "$LUKS_DEVICE"

# Update boot images
sudo gen-efi configure blue
sudo gen-efi configure green

System Updates

Automatic Update Checker

ShaniOS includes a background service that automatically checks for updates:

• shani-update: Runs periodically via systemd user timer
• Checks SourceForge for new releases matching your system profile
• Notifies you when updates are available
• Provides user-friendly GUI dialogs for update approval
• Automatically launches terminal-based update installer

Manual Update

sudo shani-deploy

The update process includes:

1. Prerequisites check (root access, internet, disk space)
2. Power management (prevents sleep/shutdown)
3. Boot validation (verifies current @blue or @green state)
4. Mirror discovery (finds fastest SourceForge mirror)
5. Intelligent download with resume support
6. Verification (SHA256 checksum and GPG signature)
7. Deployment to inactive subvolume
8. UKI generation for both slots
9. Bootloader update
10. Configuration migration

Update Channels

ShaniOS supports multiple update channels:

• stable (default): Thoroughly tested releases
• latest: Newest features (may be less stable)

Set your preferred channel:

# Choose channel
sudo shani-deploy -t latest

# Or set permanently
echo "latest" | sudo tee /etc/shani-channel

Update Options

# Show help
sudo shani-deploy --help

# Force rollback to previous version
sudo shani-deploy --rollback

# Manual cleanup of old backups and downloads
sudo shani-deploy --cleanup

# Storage analysis with deduplication
sudo shani-deploy --storage-info

# Dry run (simulate without changes)
sudo shani-deploy --dry-run

# Verbose output for troubleshooting
sudo shani-deploy --verbose

Other Updates

# Update Flatpak applications
flatpak update

# Update firmware via LVFS
fwupdmgr refresh
fwupdmgr update

Software Management

ShaniOS uses Flatpak as the primary application delivery method, with containers for development tools and system-level software.

Managing Applications via GUI

• GNOME: Use GNOME Software for graphical app management
• KDE: Use Discover for browsing and installing Flatpaks
• Both: Support Flathub integration out of the box

Installing Flatpak Applications

# Search for applications
flatpak search keyword

# Install from Flathub
flatpak install flathub org.application.Name

# List installed apps
flatpak list

# Remove an app
flatpak uninstall org.application.Name

Gaming

Game Launchers:

flatpak install flathub com.valvesoftware.Steam
flatpak install flathub com.heroicgameslauncher.hgl
flatpak install flathub net.lutris.Lutris
flatpak install flathub org.libretro.RetroArch

Gaming Peripherals:

flatpak install flathub io.github.antimicrox.antimicrox  # Gamepad mapper
flatpak install flathub org.freedesktop.Piper            # Mouse configuration
flatpak install flathub org.openrgb.OpenRGB              # RGB lighting

Performance Tools:

flatpak install flathub io.github.benjamimgois.goverlay  # Overlay manager
flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud
flatpak install flathub org.freedesktop.Platform.VulkanLayer.gamescope

Windows Applications

Run Windows apps using Wine via Bottles:

flatpak install flathub com.usebottles.bottles

Using Containers for Development

Distrobox (Recommended for CLI tools):

# Create Ubuntu environment
distrobox create --name ubuntu --image ubuntu:22.04

# Enter environment
distrobox enter ubuntu

# Inside container, install anything with apt
sudo apt update && sudo apt install build-essential nodejs python3

Podman (Docker-compatible):

# Run container
podman run -it --rm ubuntu:22.04 bash

# Docker Compose style
podman compose up -d

LXC System Containers:

lxc launch images:ubuntu/22.04 my-container

Android Applications

Waydroid is pre-installed. Launch from Applications menu and complete setup wizard.

Editing System Configuration

The /etc directory uses overlay filesystem, allowing modifications:

# Edit system configuration
sudo nano /etc/some-config-file

# Changes are stored in /data/overlay/etc/upper
# and persist across system updates

Web Hosting & Networking

ShaniOS lets you host websites and services directly from your desktop or laptop—even on home internet connections without a static IP. All tools listed here are installed for convenience and are not enabled or running by default.

How Desktop Web Hosting Works

Pre-installed Networking Tools

sudo systemctl start caddy
sudo systemctl enable caddy  # Auto-start on boot

# Login to Cloudflare
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create my-tunnel

# Configure tunnel (edit config file)
sudo nano ~/.cloudflared/config.yml

# Example config:
# tunnel: YOUR-TUNNEL-ID
# credentials-file: /home/USER/.cloudflared/YOUR-TUNNEL-ID.json
# 
# ingress:
#   - hostname: mysite.example.com
#     service: http://localhost:8080
#   - service: http_status:404

# Start tunnel
cloudflared tunnel run my-tunnel

# Enable as service
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Cloudflared creates OUTBOUND connections only
# No inbound ports need to be opened in firewall
# This is the security advantage of tunnels!

# Verify outbound connections are allowed (default)
sudo firewall-cmd --list-all

# If you have strict outbound rules, allow HTTPS
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reload

# Start Tailscale
sudo systemctl start tailscaled
sudo systemctl enable tailscaled

# Login and connect
sudo tailscale up

# Check status
tailscale status

# Allow Tailscale in firewall (UDP 41641)
sudo firewall-cmd --add-port=41641/udp --permanent
sudo firewall-cmd --reload

sudo systemctl start sshd
sudo systemctl enable sshd

# Configure (optional)
sudo nano /etc/ssh/sshd_config

# Restart after changes
sudo systemctl restart sshd

# Allow SSH through firewall (for local/Tailscale access)
sudo firewall-cmd --add-service=ssh --permanent
sudo firewall-cmd --reload

sudo systemctl start fail2ban
sudo systemctl enable fail2ban

# Check status
sudo fail2ban-client status

# View SSH jail status
sudo fail2ban-client status sshd

# Fail2ban automatically integrates with firewalld
# No manual firewall rules needed

# Verify Fail2ban can control firewall
sudo firewall-cmd --get-active-zones
sudo fail2ban-client status

# Check banned IPs
sudo firewall-cmd --direct --get-all-rules

# Check status
sudo firewall-cmd --state

# List active rules
sudo firewall-cmd --list-all

# Open HTTP/HTTPS
sudo firewall-cmd --add-service=http --permanent
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reload

# Open custom port
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload