ShaniOS Wiki
A comprehensive guide to the immutable operating system with blue-green subvolume switching
Introduction
ShaniOS is an innovative immutable operating system based on Arch Linux that employs a blue-green deployment strategy using Btrfs subvolumes. The system provides atomic updates through a custom deployment tool (shani-deploy), maintains system integrity with read-only root partitions, and offers enhanced security through AppArmor profiles, firewalld configurations, and full-disk encryption.
What is an Immutable OS?
An immutable operating system is one where the system partition cannot be modified during normal operation. This approach offers several advantages:
- Improved system stability and reliability
- Enhanced security by preventing runtime modifications
- Simpler system maintenance and updates
- Protection against accidental or malicious system changes
Core Design Principles
System Immutability
The root filesystem is mounted read-only to prevent runtime modifications
Atomic Updates
The system can be updated atomically by switching between blue and green subvolumes
Reliable Rollback
If an update fails, the system can revert to the previous state
Security First
Implementation of comprehensive security measures
Features
Blue-Green Deployment
ShaniOS implements a blue-green deployment strategy using Btrfs subvolumes, adapting concepts from web application deployment. This approach maintains two complete system states (blue and green) with only one active at any time, enabling atomic updates and immediate rollback capabilities.
Immutable System Design
The root filesystem is mounted read-only, preventing modifications during normal operation. This ensures system integrity and protects against both malicious attacks and accidental system changes.
Application Isolation
Flatpak is the preferred application deployment method, providing sandboxing and isolation from the base system. This enhances security while allowing users to install and manage applications independently from the system core.
Enhanced Security
ShaniOS comes with AppArmor profiles, firewalld configurations, and full-disk encryption through LUKS. The system also supports UEFI secure boot with Unified Kernel Images (UKIs).
Hibernation Support
Despite the challenges of implementing hibernation on a Btrfs filesystem, ShaniOS provides reliable hibernation support through a dedicated swap subvolume with Copy-on-Write explicitly disabled.
Automatic Recovery
ShaniOS includes a robust boot failure detection and automatic rollback mechanism to ensure system reliability even when updates fail.
Architecture
ShaniOS is built with a layered architecture designed to balance immutability, security, and user experience.
ShaniOS Architecture Diagram showing the layered structure from boot layer through user data layer, with blue-green deployment mechanism highlighted.
Architectural Layers
Boot Layer
systemd-boot with Unified Kernel Images (UKIs)
Storage Layer
LUKS-encrypted Btrfs with specialized subvolumes
Base System Layer
Read-only root filesystem
Configuration Layer
Overlay-mounted directories
Application Layer
Flatpak-based application deployment
User Data Layer
Persistent storage for user data
Storage Layout
The system uses Btrfs as its primary filesystem with a sophisticated subvolume structure designed to balance immutability, persistence, and performance.
Btrfs Subvolume Organization showing hierarchical relationship between system subvolumes (@blue/@green), user data (@home), and persistence subvolumes (@data, @log, @cache).
| Subvolume | Purpose |
|---|---|
| @blue/@green | Root subvolumes for blue-green deployment |
| @home | User data and personal configurations |
| @data | Persistent storage used by overlay filesystems |
| @log | System logs, mounted at /var/log |
| @cache | System cache, mounted at /var/cache |
| @flatpak | Dedicated subvolume for Flatpak applications |
| @containers | Container storage |
| @swap | Optimized subvolume for swap file with CoW disabled |
Installation
System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| Processor | x86_64 dual-core | x86_64 quad-core |
| Memory | 2 GB RAM | 4 GB RAM |
| Storage | 20 GB | 40 GB |
| UEFI | Required | Required |
Installation Steps
Installation Sequence Diagram showing workflow from ISO boot through disk partitioning to final bootloader setup.
Download the ISO
Download the ShaniOS installation ISO from the official website.
Create Bootable Media
Use a tool like Ventoy, Rufus, or dd to create bootable USB media.
Boot from Installation Media
Boot your computer from the installation media. The system will start a minimal Sway window manager environment.
Launch OS-Installer
The OS-Installer application will launch automatically to guide you through the installation process.
Disk Partitioning
Follow the guided disk partitioning process. You can enable full-disk encryption with LUKS during this step.
System Installation
The installer will unpack the base Btrfs image and Flatpak image, create the necessary subvolumes, and configure the bootloader.
Configuration
Set up user accounts, timezone, and other system settings.
Complete Installation
Finalize the installation and reboot into your new ShaniOS system.
Usage
System Updates
ShaniOS uses a custom update tool called shani-deploy that implements the blue-green deployment strategy for atomic system updates.
Update Process Flowchart detailing steps from initialization through deployment to bootloader update and validation.
Update Process
To update your ShaniOS system, simply run:
sudo shani-deployThe update process includes the following steps:
- Initialization: Check running as root, internet connectivity
- System Inhibit: Prevent system sleep/shutdown during update
- Boot Validation: Ensure system is booted from expected subvolume
- Update Information: Fetch latest version information from configured update channel
- Download: Securely download and verify system image
- Deployment: Apply update to inactive subvolume
- UKI Generation: Create and sign new Unified Kernel Image
- Bootloader Update: Update boot entries for the new system
- Configuration Migration: Apply persistent configurations
- Update Validation: Verify integrity of the new subvolume
Note: If an update fails, ShaniOS will automatically roll back to the previous working system on the next boot.
Software Management
ShaniOS uses Flatpak as the primary method for application management, while the base system remains immutable.
Installing Applications
To install applications, use Flatpak:
flatpak install flathub org.application.NameManaging Applications
You can manage your Flatpak applications through the command line or using graphical tools like GNOME Software or KDE Discover.
Base System Modifications
While the base system is immutable, you can make persistent modifications to certain directories like /etc through the overlay filesystem. These changes will persist across system updates.
Warning: Traditional package management workflows through pacman are not supported as they would violate the immutability of the system. Use Flatpak for application management instead.
Technical Details
Blue-Green Deployment
ShaniOS implements a blue-green deployment strategy using Btrfs subvolumes, adapting concepts from web application deployment.
Blue-Green Deployment Diagram showing the active and inactive subvolumes, update flow, and subvolume switching mechanism.
How It Works
The blue-green deployment concept works as follows:
- Dual Root Subvolumes: The system maintains two complete root filesystems (@blue and @green).
- Active/Inactive States: At any given time, one subvolume is active while the other remains inactive.
- Update Process Flow:
- System boots from active subvolume (e.g., @blue)
- Updates are applied to inactive subvolume (e.g., @green)
- Boot configuration is updated to point to the updated subvolume as active
- System reboots into the updated new active subvolume
- Previous active subvolume is preserved for potential rollback as inactive subvolume
Btrfs Subvolumes
ShaniOS uses Btrfs as its primary filesystem with a sophisticated subvolume structure designed to balance immutability, persistence, and performance.
Btrfs Features for Immutable Systems
Btrfs provides several features that make it ideal for implementing immutable operating systems:
- Copy-on-Write (CoW) functionality minimizes storage duplication
- Subvolumes enable efficient organization of filesystem components
- Snapshots provide atomic state preservation
- Send/receive operations allow efficient transfer of filesystem changes
- Compression capabilities reduce storage requirements
Overlay Filesystem Configuration
A critical aspect of ShaniOS's immutability strategy is the use of overlay filesystems to allow specific directories to be writable while maintaining the immutable nature of the root filesystem.
Overlay Filesystem Structure showing the relationship between read-only lower layer and writable upper layer with workdir for filesystem operations.
Security Features
ShaniOS includes comprehensive security features designed to protect against various threat categories:
Full Disk Encryption
ShaniOS uses LUKS2 for full disk encryption with the following features:
- Modern argon2id key derivation function
- Support for both password and TPM2-based unlocking
- Automatic unlocking during system updates
Secure Boot
ShaniOS supports UEFI Secure Boot through:
- Machine Owner Keys (MOK): Custom MOK keys generated during build time
- Unified Kernel Images (UKIs): Combining kernel, initramfs, and command line into a single signed EFI binary
- Secure Boot Chain: Shim loaded by UEFI firmware, followed by GRUB and kernel
AppArmor
ShaniOS includes AppArmor for mandatory access control, limiting the capabilities of applications and processes to enhance system security.
Firewalld
The system comes with firewalld pre-configured to protect against network-based threats.
Application Isolation
Flatpak provides application sandboxing to contain malicious applications and prevent them from affecting the base system.
Frequently Asked Questions
Can I install regular Arch Linux packages?
No, traditional package management workflows through pacman are not supported as they would violate the immutability of the system. Use Flatpak for application management instead. If you need specific packages, you may need to wait for the next system update that includes them or consider creating a custom system image.
What happens if an update fails?
ShaniOS includes a robust boot failure detection and automatic rollback mechanism. If the system detects that it failed to boot properly after an update, it will automatically revert to the previous working state. This ensures that your system remains bootable even when updates encounter issues.
Does ShaniOS support hibernation?
Yes, ShaniOS provides hibernation support through a dedicated swap subvolume with Copy-on-Write explicitly disabled. This unique approach solves the challenges associated with implementing hibernation on Btrfs filesystems, providing reliable hibernation functionality.
How do I make persistent changes to system configuration?
While the root filesystem is immutable, ShaniOS uses overlay filesystems to allow specific directories like /etc to be writable. Changes made to these directories will persist across system updates. For more extensive system modifications, you may need to create a custom system image.
How much disk space does ShaniOS require?
ShaniOS requires at least 20 GB of disk space, with 40 GB recommended. Despite maintaining two complete system states (blue and green), the system's efficient use of Btrfs's Copy-on-Write features results in only about 18% storage overhead compared to traditional systems.
Can I use ShaniOS on non-UEFI systems?
No, ShaniOS requires UEFI firmware to support features like Unified Kernel Images (UKIs) and Secure Boot. Legacy BIOS systems are not supported at this time.
Contribute
ShaniOS is an open-source project, and contributions are welcome! Here's how you can get involved: