diff --git a/docs/realms.md b/docs/realms.md index 54062bc..f1757bd 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -1,34 +1,24 @@ Citadel Realms -============== +-------------- -In Citadel applications are installed into and run from spaces called Realms. Realms -are implemented internally as systemd-nspawn containers but you don't need to know -this because the `realms` command-line tool manages creating and launching containers -for you. +Citadel contains only the base operating system and the Gnome desktop, it does not +include any applications. To be able to install and run applications Citadel can +create spaces which are called Realms. +A Realm is a container similar to a Docker or LXC container in which any Linux +distribution could be installed. We use a Debian based image but it would not be +difficult to create an image for another Linux distribution. -### Application Images +The realm containers are launched with systemd-nspawn but this is a detail of +how they are implemented and not something it is necessary to learn about in order to use them. -The root filesystem for realms are called Application Images, but we usually just call them -appimgs. We have created a framework for constructing these images from Debian based distributions -which we use to build the default appimg that we provide, but we -also encourage users to experiment with building their own images. +Citadel provides a command-line tool `realms` for creating, managing, and launching Realm instances. -#### Tree Application Images +### The `default` realm -Tree images are the only type of application image which is currently implemented for realms. - -The rootfs is a tree of files on the filesystem, and also it is a btrfs subvolume. - -#### Block Application Images - - - -### `default` realm - -One realm is always selected to be the `default` realm. The default realm +One realm is always selected to be the `default` realm. This realm starts automatically when the system boots. The `realms` utility can be used -to change which realm is the default realm. Switching the default realm changes +to change which realm is the default realm. Switching the default realm changes the symlink `/realm/default.realm` to point to a different realm instance directory. citadel:~# realms default @@ -40,21 +30,112 @@ the symlink `/realm/default.realm` to point to a different realm instance direct citadel:~# realms default Default Realm: project -### `current` realm +### The `current` realm -If any realms are running, then one realm is always the `current` realm. The current -realm is a realm that is being monitored by the `citadel-desktopd` daemon. This -daemon is responsible for safely copying application `.desktop` files from the running -realm instance to a temporary directory where they will be read by the GNOME desktop to -to display a menu of applications that can be launched. +Multiple realms may be launched at once but the Gnome Desktop is only associated with +one of the running realms. This realm is called the `current` realm. -Changing the `current` realm, changes the set of applications which are visible to -gnome-shell to only the applications installed in this realm. Also, any applications -started by gnome-shell will run in the `current` realm. +When displaying applications available to launch from the desktop, Gnome will only +be aware of applications that are installed in the realm which is set as `current` +and any application launched from the desktop will run inside this current realm. - citadel:~# realms +Setting another realm as current does not affect any applications that are already running. +Changing the current realm only means that any further applications which are launched +will now run in the newly chosen realm. + +Changing or querying the current realm is done with the `realms current` command, and +if you choose a realm which is not currently running it will be automatically started. + + citadel:~# realms current Current Realm: main - + + citadel:~ # realms current project + [+]: Started realm 'project' + [+]: Realm 'project' set as current realm + + citadel:~ # realms current + Current Realm: project + +Underneath the hood, this command just changes the symlink `/run/realms/current.realm` to +point to a new realm. This directory is monitored for changes with `inotify` and when +the symlink changes a new set of `.desktop` files is swapped into a temporary directory +where Gnome will look for metadata about which applications are installed. + +### Creating a new realm + +New realms are created with the command `realms new ` + +When a new realm is created a btrfs snapshot of some application image is created at +`/realms/realm-$name/rootfs`. By default it is the base image (`base.appimg`) which +is cloned as a snapshot. Application images are described in detail in a later section. + + citadel:~ # realms new project + [+]: Populating realm home directory with files from /realms/skel + Create a snapshot of '/storage/appimg/base.appimg' in '/realms/realm-project/rootfs' + +A new empty home directory is also created for the realm instance. Any file which are placed +into the `/realm/skel` directory will be copied into any newly created realm home directory. + + +### Realms configuration file + +All of the curretly supported configuration options are listed below with their default values assigned. + + use-shared-dir = true + use-sound = true + use-x11 = true + use-wayland = true + use-gpu = false + use-kvm = false + use-network = true + network-zone = "clear" + +If you wish to change any of these options to something other than what is listed above add the +corresponding line to the file `/realms/realm-$name/config` + + citadel:~ # echo "use-gpu = true" > /realms/realm-main/config + +#### Option `use-shared-dir` + +Set to `false` to disable mounting the shared directory `/realms/Shared` into this realm at +`/home/user/Shared`. + +#### Option `use-sound` + +Set to `false` to prevent mounting pulse audio socket and sound device into this realm. + +#### Option `use-x11` + +Set to `false` to prevent mounting `/tmp/.X11-unix` into the realm. This is the socket for communicating +with the `XWayland` X11 compatibility daemon. + +#### Option `use-wayland` + +Set to `false` to prevent mounting the wayland display server socket `/run/user/1000/wayland-0` + into the realm. + +#### Option `use-gpu` + +Set to `true` to mount the device `/dev/dri/renderD128` into the realm. Adding this +device will make hardware graphics acceleration available to applications running +in the realm. + +#### Option `use-kvm` + +Set to `true` to mount the device `/dev/kvm` into the realm. This will make it +possible to run Qemu and other KVM based tools with hardware virtualization +inside the realm. + +#### Option `use-network` + +Set to `false` to disable configuring the realm with access to the internet. The +realm instance will only have a localhost network interface. + +#### Option `network-zone` + +Setting a name here will create bridge device in citadel with the name vz-$name if +it doesn't already exist and attach this realm instance to that bridge. + ### Realms base directory layout The realms base directory is stored on the storage partition at `/storage/realms` and is bind mounted to `/realms` on the root filesystem for convenience. @@ -68,23 +149,30 @@ The realms base directory is stored on the storage partition at `/storage/realms /realm-project /realm-testing -#### `/realms/config` file +#### File `/realms/config` -This file is a template of the configuration file for individual realms. When a new realm is created this file in copied into the new realm instance directory. By modifying this file, the default configuration for new realm instances can be changed. +This file is a template of the configuration file for individual realms. When a new +realm is created this file in copied into the new realm instance directory. By +modifying this file, the default configuration for new realm instances can be changed. -#### `/realms/Shared` directory +#### Directory `/realms/Shared` -This directory is bind mounted to `/home/user/Shared` of each running realm that has the option `use-shared-dir` enabled. It's a convenient way to move files between different realms and between citadel and realms. +This directory is bind mounted to `/home/user/Shared` of each running realm that has +the option `use-shared-dir` enabled. It's a convenient way to move files between +different realms and between citadel and realms. -#### `/realms/skel` directory +#### Directory `/realms/skel` -Files which are added to this directory will be copied into the home directory of any newly created realm. The directory is copied as a tree of files and may contain subdirectories. +Files which are added to this directory will be copied into the home directory of +any newly created realm. The directory is copied as a tree of files and may contain +subdirectories. -#### `/realms/default.realm` +#### Symlink `/realms/default.realm` -A symlink which points to a realm instance directory of the default realm. The default realm is the realm which starts when the system is booted. - -#### `/realms/realm-$name` +A symlink which points to a realm instance directory of the default realm. The +default realm is the realm which starts when the system is booted. + +#### Directory `/realms/realm-$name` This is a realm instance directory, for a realm with $name as the realm name. @@ -93,15 +181,67 @@ This is a realm instance directory, for a realm with $name as the realm name. /home /rootfs - * `config` : configuration file copied from `/realms/config` - * `/home` : directory mounted to `/home/user` in the realm, populated from `/realms/skel` - * `/rootfs` : btrfs subvolume clone (snapshot) of an application image. - + ##### `config` -#### Realm instance directory layout +Configuration file for the realm instance copied from `/realms/config` or +created by the user. - /realm-main - config - /home - /rootfs +##### `/home` +Home directory for this realm. It will be mounted to `/home/user` in +the realm instance. + +##### `/rootfs` + +The root filesystem of this realm. It is cloned from (a btrfs subvolume snapshot of) +some application image. + +### Application Images + +(Not to be confused with the [AppImage](https://appimage.org) packaging system) + +The root filesystem for realms are called Application Images but we often use +the shorter name *appimg*. + +We have created [a framework](https://github.com/subgraph/citadel/tree/master/appimg-builder) +for building a Debian based images and we use this to build the default appimg that we ship. + +We also encourage users to experiment with building their own custom images. + + +**Tree Application Images** are the only type of application image which are currently implemented for realms. + +The rootfs is a tree of files on the filesystem, and it is also a btrfs subvolume +which is cloned at zero cost (internally with `btrfs subvolume snapshot`) to use +as the root filesystem of newly created realms. + + +#### Block Application Images (and also Sealed Application Images) + +In the future we will add another type of application image called a **Block +Application Image**. This type of image will be stored as a disk volume image file +and will be mounted with a loop device rather than existing as a tree of files on the +filesystem. + +This will make it possible to enforce [dm-verity](https://www.kernel.org/doc/Documentation/device-mapper/verity.txt) +verification over the image and ensure that no malicous or unintended modifications +can be made to any of the the files on the root filesystem. Signature verification +over the dm-verity root hash is done from the citadel rootfs image which is also +secured with dm-verity. When enforcement of boot integrity is also implemented this +will create a chain of cryptographic assurances that no component of the system has +been tampered with. + +Block images with signatures and dm-verify verification enabled are called **Sealed Application Images** + +### Updating an Application Image + +To modify or update an application image run the `realms update-appimg` command. +A container will be created for updating the image and a root shell session will +open. From this session regular package management commands can be run. Any changes +made will only affect future realms created from this appimg. + + citadel:~ # realms update-appimg + [+]: Entering root shell on base appimg + root@base-appimg-update:/# apt update + + [...]