Wrote some documentation about realms
This commit is contained in:
parent
637d89896a
commit
5cf6c3f9f1
246
docs/realms.md
246
docs/realms.md
@ -1,34 +1,24 @@
|
|||||||
Citadel Realms
|
Citadel Realms
|
||||||
==============
|
--------------
|
||||||
|
|
||||||
In Citadel applications are installed into and run from spaces called Realms. Realms
|
Citadel contains only the base operating system and the Gnome desktop, it does not
|
||||||
are implemented internally as systemd-nspawn containers but you don't need to know
|
include any applications. To be able to install and run applications Citadel can
|
||||||
this because the `realms` command-line tool manages creating and launching containers
|
create spaces which are called Realms.
|
||||||
for you.
|
|
||||||
|
|
||||||
|
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
|
Citadel provides a command-line tool `realms` for creating, managing, and launching Realm instances.
|
||||||
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.
|
|
||||||
|
|
||||||
#### Tree Application Images
|
### The `default` realm
|
||||||
|
|
||||||
Tree images are the only type of application image which is currently implemented for realms.
|
One realm is always selected to be the `default` realm. This realm
|
||||||
|
|
||||||
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
|
|
||||||
starts automatically when the system boots. The `realms` utility can be used
|
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.
|
the symlink `/realm/default.realm` to point to a different realm instance directory.
|
||||||
|
|
||||||
citadel:~# realms default
|
citadel:~# realms default
|
||||||
@ -40,21 +30,112 @@ the symlink `/realm/default.realm` to point to a different realm instance direct
|
|||||||
citadel:~# realms default
|
citadel:~# realms default
|
||||||
Default Realm: project
|
Default Realm: project
|
||||||
|
|
||||||
### `current` realm
|
### The `current` realm
|
||||||
|
|
||||||
If any realms are running, then one realm is always the `current` realm. The current
|
Multiple realms may be launched at once but the Gnome Desktop is only associated with
|
||||||
realm is a realm that is being monitored by the `citadel-desktopd` daemon. This
|
one of the running realms. This realm is called the `current` realm.
|
||||||
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.
|
|
||||||
|
|
||||||
Changing the `current` realm, changes the set of applications which are visible to
|
When displaying applications available to launch from the desktop, Gnome will only
|
||||||
gnome-shell to only the applications installed in this realm. Also, any applications
|
be aware of applications that are installed in the realm which is set as `current`
|
||||||
started by gnome-shell will run in the `current` realm.
|
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
|
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 <realm name>`
|
||||||
|
|
||||||
|
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
|
### 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.
|
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-project
|
||||||
/realm-testing
|
/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.
|
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`
|
|
||||||
|
#### Directory `/realms/realm-$name`
|
||||||
|
|
||||||
This is a realm instance directory, for a realm with $name as the 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
|
/home
|
||||||
/rootfs
|
/rootfs
|
||||||
|
|
||||||
* `config` : configuration file copied from `/realms/config`
|
##### `config`
|
||||||
* `/home` : directory mounted to `/home/user` in the realm, populated from `/realms/skel`
|
|
||||||
* `/rootfs` : btrfs subvolume clone (snapshot) of an application image.
|
|
||||||
|
|
||||||
|
|
||||||
#### Realm instance directory layout
|
Configuration file for the realm instance copied from `/realms/config` or
|
||||||
|
created by the user.
|
||||||
|
|
||||||
/realm-main
|
##### `/home`
|
||||||
config
|
|
||||||
/home
|
|
||||||
/rootfs
|
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
[...]
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user