Subgraph

Subgraph OS · Citadel

Citadel Documentation

Documentation for Subgraph Citadel, the core operating system of the new version of Subgraph OS. Citadel is built and distributed as a single static disk image rather than as a collection of software packages.

01Using Citadel

User Guide

Working with the Citadel desktop operating system: the base system, running applications in realms, and how to configure them.

  1. 01 Subgraph Citadel What Citadel is: the GNOME desktop and a few system services, built from source and shipped as a single static disk image. Applications run in realms, as containers or as virtual machines under a KVM hypervisor. What is Citadel?
  2. 02 Citadel Realms Realms are the spaces where applications are installed and run. How the current realm decides where desktop applications launch, and how realms are laid out under /realms. The current realm · Realm directory layout
  3. 03 Configuring Realms Reference for every option in a realm's TOML configuration file, from display and sound access to networking, GPU access and the RealmFS image the realm uses. Options
  4. 04 RealmFS Images RealmFS images hold the root filesystem of realms. They are signed and mounted read-only with dm-verity. How images are updated and sealed, how the signing key is kept, and safe mode. Updates · Signing RealmFS Images · Base RealmFS image
02Under the hood

Citadel Internals

How Citadel is built and booted: disk and filesystem layout, resource images, kernel command line options, and developer notes.

  1. 01 Developer Guide Notes for developers, starting with how to disable dm-verity and remount the root filesystem read-write for testing. Make Root Filesystem Writable · Debugging GNOME startup
  2. 02 Booting Citadel How an installed system boots: the EFI and LUKS partitions, the LVM volumes inside, and the initramfs units that find and mount the root filesystem. Disk Layout
  3. 03 Disk Layout A hands-on tour of the disk: the partitions created at install, the block devices set up at boot, the Citadel filesystem tree, and the loop devices that mount resource images. Partitions · Citadel Filesystem Layout · Resource Image Mounts
  4. 04 Kernel Command Line Options Kernel command line options such as citadel.noverity, citadel.install and citadel.channel, and what each one changes at boot. Most are for development, testing or installation.
  5. 05 Citadel Resource Images Resource images are signed disk images mounted read-only with dm-verity. The four image types (rootfs, kernel, extra, realmfs), the image layout and every header field. Resource Image Types · Image Header