brl/citadel
1
0
Fork 2
Code Issues Pull Requests 2 Packages Projects Releases Wiki Activity

Citadel documentation system

Browse Source
This commit is contained in:
Bruce Leidl 2020-12-07 17:24:22 -05:00
parent 5b8c330cb7
commit 7faf0ce39e
29 changed files with 2054 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
pages/

25
docs/Makefile Normal file
View File

@ -0,0 +1,25 @@
DUCKFILES= $(notdir $(wildcard duck/*.duck))
PAGES= $(addprefix pages/, $(DUCKFILES:.duck=.page))
OUTDIR= pages
RECIPE_PAGES_DIR= ../meta-citadel/recipes-citadel/citadel-documentation/files/pages
.PHONY: directories clean
all: directories $(PAGES)
install: directories $(PAGES)
rm -f ${RECIPE_PAGES_DIR}/*.page
cp $(PAGES) ${RECIPE_PAGES_DIR}
clean:
rm $(PAGES)
directories: ${OUTDIR}
${OUTDIR}:
mkdir -p ${OUTDIR}
pages/%.page: duck/%.duck
ducktype -o $@ $<

26
docs/README.md Normal file
View File

@ -0,0 +1,26 @@
## Writing documentation
http://projectmallard.org/ducktype/1.0/index.html
## Building documentation
Building the documentation requires the 'ducktype' utility. The makefile will use this
command to generate a directory of .page files from the .duck files in the /duck directory.
$ sudo apt install ducktype
$ make
## Reading documentation
After generating the documentation it can be previewed by running yelp on the /pages directory:
$ yelp pages
## Installing documentation
After making changes to the documentation, run 'make install' to update the set
of .page files in the citadel-documentation recipe.
$ make install

84
docs/duck/boot.duck Normal file
View File

@ -0,0 +1,84 @@
= Booting Citadel
[topic]
@link[guide >index#internals]
== Disk Layout
When Citadel is installed two disk partitions are created on the target disk.
[screen]
sda 8:0 0 477G 0 disk
├─sda1 8:1 0 511M 0 part
└─sda2 8:2 0 476.5G 0 part
The first partition is an EFI boot partition and the second partition is LUKS encrypted
and contains multiple LVM volumes when decrypted.
[screen]
[[[
/dev/sda1 /dev/sda2
[EFI ESP Boot partition] [ LUKS encrypted partition filling remainder of disk ]
. .
. .
. | .
. | .
. V .
. .
[ rootfsA ] [ rootfsB ] [ citadel-storage ]
]]]
There are three logical volumes. Two root filesystem partitions so that one partition
can be updated while the other one is in use, and the remaining space is contained
in a volume called 'storage'.
[screen sh]
# lvs
LV VG Attr LSize
rootfsA citadel -wi-a----- 2.00g
rootfsB citadel -wi-ao---- 2.00g
storage citadel -wi-ao---- 472.43g
=== Bootloader
==== LUKS
The kernel initramfs has an /etc/crypttab file which guides the discovery of the LUKS partition.
The UUID of the LUKS partition is hardcoded to the value listed below. If citadel is installed
on more than one device on the system, the intended LUKS partition may not be chosen correctly.
This problem can be addressed by changing the UUID of other citadel LUKS partitions and passing
the UUID on kernel commandline to override /etc/crypttab. See systemd-cryptsetup-generator(8).
[screen sh]
# cat /etc/crypttab
luks UUID=683a17fc-4457-42cc-a946-cde67195a101 - discard
==== Mounting rootfs
The initramfs boot stage is orchestrated by various systemd unit files which can be found
in the citadel source tree at:
[screen]
citadel/meta-citadel/recipes-initrd/citadel-initramfs
The same kernel and initramfs is used for the installer image. One task of these unit files
is to set up a live mode boot when a certain kernel command line option is set. For a regular
boot, a pair of unit files will attempt to mount the root filesystem partition when it becomes
available:
[screen]
citadel-rootfs-mount.path
citadel-rootfs-mount.service
The .path unit triggers every time /dev/mapper changes and the corresponding .service unit is
activated only when all of the LVM volumes inside
[screen]
ConditionPathExists=/dev/mapper/citadel-rootfsA
ConditionPathExists=/dev/mapper/citadel-rootfsB
ConditionPathExists=/dev/mapper/citadel-storage

61
docs/duck/citadel.duck Normal file
View File

@ -0,0 +1,61 @@
= Subgraph Citadel
[topic]
@link[guide >index]
@desc Introduction to Subgraph Citadel
== What is Citadel?
Citadel is the core operating system of the new version of Subgraph OS.
Citadel includes the GNOME desktop session and a few basic system services and
nothing else. It is built and distributed as a single static disk image
rather than as a collection of software packages like a traditional Linux
distribution such as Ubuntu or Fedora. Citadel disk images are built entirely
from the source code of the individual software components. This gives us
complete control over what is included and how each component is configured.
[note .advanced]
Citadel is a modern desktop operating system based on the GNOME desktop, but if you
prefer we also include an tiling window manager called Sway as an alternative.
Since the Citadel root filesystem is immutable it is not possible to install
applications such as a web browser or text editor directly into Citadel.
Instead applications are run in a separate isolated environment called a Realm.
When Citadel is first installed a single primary Realm is created and while running
a single realm the system resembles and behaves similar to any other desktop Linux
system. The separation between Citadel and the realm in which user applications are
launched is mostly transparent to the user. However, a user may create as many new
realms as they like and each new realm behaves like a freshly installed Debian Linux
environment where the user may install packages and store files.
Realms are implemented in Subgraph OS as either containers or as virtual machines
running in a custom KVM hypervisor. Both approaches have advantages so the user is
free to choose either option for each realm they create.
[note .advanced]
Hypervisor isolation is stronger and more secure, but container isolation uses
less system resources and makes it possible to access hardware devices and other
system features directly. A Citadel user can decide which configuration makes
more sense for each Realm they create.
=== Stateless Foundation
In the architecture of Citadel the building blocks of the system are
immutable filesystem images rather than packages. These images are mounted
read-only and this property is enforced with a Linux kernel feature (dm-verity)
which efficiently guarantees each block loaded from disk has a valid
cryptographic checksum. This means that Citadel always loads exactly the
operating system software prepared by Subgraph and rebooting the system will
always brings the computer into a known consistent state.
When Citadel is updated an entirely new image is loaded rather than applying
a set of changes on top of an existing filesystem. By atomically updating the
entire system from one version to the next there is only ever a single software
configuration to consider and the system can never end up in an inconsistent state.
System upgrades cannot break your computer in mysterious ways and even if an
upgrade fails to boot for some reason, the system simply reverts to the
previously working version.

26
docs/duck/developer.duck Normal file
View File

@ -0,0 +1,26 @@
= Developer Guide
[topic]
@link[guide >index#internals]
== Make Root Filesystem Writable
Sometimes it can be useful to make changes directly to the citadel root filesystem to
experiment with changes or to debug a problem.
First $code(citadel.noverity) must be added to the kernel commandline. After booting with
this command line option verify that dm-verity has been disabled with the $code(dmsetup)
command.
[screen]
# dmsetup status rootfs
0 4194304 linear
If the output displays $code(verity) instead of $code(linear) then dm-verity is enabled
and the disk cannot be safely written to.
Next remount the root filesystem with read-write flag.
[screen]
# mount -oremount,rw,noatime /
== Debugging GNOME startup

198
docs/duck/disk-layout.duck Normal file
View File

@ -0,0 +1,198 @@
= Disk Layout
[topic]
@link[guide >index#internals]
@desc A Hands-on guide the Citadel Disk and Filesystem Layout
== Partitions
During installation, two partitions are created on the disk chosen as
the target of the install.
For example, if the installation disk is $code(/dev/sda):
[terms]
- $code(/dev/sda1)
* 512MB EFI System Partition
- $code(/dev/sda2)
* Remainder of the disk
The partition layout of a running system can be viewed by running the $code(lsblk) command.
[screen]
citadel:~ # lsblk /dev/sda
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 477G 0 disk
├─sda1 8:1 0 511M 0 part
└─sda2 8:2 0 476.5G 0 part
└─luks 252:0 0 476.4G 0 crypt
├─citadel-rootfsA 252:1 0 2G 0 lvm
│ └─rootfs 252:4 0 354M 1 crypt /
├─citadel-rootfsB 252:2 0 2G 0 lvm
└─citadel-storage 252:3 0 472.4G 0 lvm /storage
Several further block devices are created during boot when the main disk partition
is decrypted.
[screen]
sda
├─sda1 (a) /boot partition
└─sda2 (b) LUKS encrypted partition
└─citadel (c) LVM volume group
├─citadel-rootfsA (d1) rootfs partition A (Read Only)
│ └─rootfs (e) The dm-verity device created for rootfsA
├─citadel-rootfsB (d2) rootfs partition B (Read Only)
└─citadel-storage (f) mounted as /storage (Read/Write)
[terms]
- $code((a) /boot partition)
* EFI boot partition
- $code((b) LUKS encrypted partition)
* Remainder of disk is an encrypted volume
- $code((c) LVM volume group)
* Main partition contains several LVM volumes
- $code((d) citadel-rootfs(A/B))
* Two root partitions so one can be updated while other is in use.
- $code((e) /dev/mapper/rootfs)
* verity mapper device for mounted root partion
- $code((f) /dev/mapper/citadel-storage)
* The writable filesystem
== Citadel Filesystem Layout
[code]
/
├─ /run/citadel/images/
│ │
│ ├─ modules.mountpoint/ (modules image mounted here)
│ └─ extra.mountpoint/ (extra image mounted here)
│
└─ /storage
│
├─ resources/dev (resource images for channel 'dev')
│ │
│ ├─base-realmfs.img
│ └─main-realmfs.img
│
├─ /realms (/realms is a bind mount of /storage/realms)
│ ├─skel/
│ └─config
│
├─ /realms/realmfs-images
│ │
│ ├─citadel-kernel-5.7-dev-001.img
│ └─citadel-extra-dev-001.img
│
└─ /realms/realm-main
├─ home
└─ config
== Resource Image Mounts
Resource images are mounted into the system by creating loop devices. These devices can be
viewed by running the 'losetup' command inside Citadel.
[screen]
citadel:~ # losetup -ONAME,OFFSET,RO,BACK-FILE
NAME OFFSET RO BACK-FILE
/dev/loop1 4096 1 /storage/resources/dev/citadel-extra-dev-001.img
/dev/loop2 4096 1 /storage/realms/realmfs-images/main-realmfs.img
/dev/loop0 4096 1 /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
Resource image files are protected against accidental changes or malicious tampering by
using dm-verity so that the kernel verifies a cryptographic checksum of each block loaded
from the image.
You can view the verity device mapper node associated with each loop device with
the $code(lsblk) command.
[screen]
citadel:~ # lsblk /dev/loop0 /dev/loop1 /dev/loop4
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
loop0 7:0 0 116.9M 1 loop
└─verity-kernel 252:5 0 116M 1 crypt /run/citadel/images/kernel.mountpoint
loop1 7:1 0 938.9M 1 loop
└─verity-extra 252:6 0 931.5M 1 crypt /run/citadel/images/extra.mountpoint
loop2 7:2 0 4G 1 loop
└─verity-realmfs-main-11922f31 252:9 0 4G 1 crypt /run/citadel/realmfs/realmfs-main-11922f31.mountpoint
Parameters of each dm-verity instance can be viewed with the veritysetup command.
[screen]
citadel:~ # veritysetup status verity-kernel
/dev/mapper/verity-kernel is active and is in use.
type: VERITY
status: verified
hash type: 1
data block: 4096
hash block: 4096
hash name: sha256
salt: fa430cb7887de60dca6fd1974868036ea39cf5017eb55f02e3a76f82a12a0431
data device: /dev/loop0
data loop: /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
size: 237536 sectors
mode: readonly
hash device: /dev/loop0
hash loop: /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
hash offset: 237544 sectors
When a resource image file is mounted, a file in the root directory called 'manifest' lists
bind mounts to perform to integrate the image into the Citadel root filesystem.
Each line of this file is a directory to bind mount from the mounted image to the root
filesystem. If a directory should be mounted to a location which is different than
the source directory the source and target directories are both listed on a single
line and separated by the ':' character. In the 'extra' image below, the directory
/usr/share from the resource image is mounted to /opt/share on the Citadel filesystem.
[screen]
citadel:~ # cat /run/citadel/images/kernel.mountpoint/manifest
/usr/lib/modules
citadel:~ # cat /run/citadel/images/extra.mountpoint/manifest
/usr/lib/firmware
/usr/share:/opt/share
The citadel-image utility can be used to view the metainfo variables stored in the header
section of a resource image file.
[screen]
citadel:~ # citadel-image metainfo /storage/resources/dev/citadel-extra-dev-001.img
image-type = "extra"
channel = "dev"
version = 1
timestamp = "20190331172025"
nblocks = 195924
shasum = "04e6f58afa6f608aff2d6cbb47cbe704f8ab0995f4dfe8e1c03655dc9bb6635a"
verity-salt = "7bf3eec3c51ffd2e82329a9fc6fe42915743874d7c5af43589e589c037ae81e5"
verity-root = "b94eb3431c4fb95e5b9bd62b4505d089414ae660d75eee0fce54b8483d3f9571"
citadel:~ # citadel-image metainfo /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
image-type = "kernel"
kernel-version = "5.0.6"
kernel-id = "36b7a960dcd51d1649f83a7361f9eb5c2af5741ce6cc53689b411347aa1298b6"
channel = "dev"
version = 1
timestamp = "20190407002748"
nblocks = 29692
shasum = "c988bd7d468c409eb6cd3af8fa9e17b0a75a72d6ad765ad1749d15628a9096be"
verity-salt = "fa430cb7887de60dca6fd1974868036ea39cf5017eb55f02e3a76f82a12a0431"
verity-root = "f4c4fbaebb59d348bd44cfb1cdef54a813728aabc5acc439c2e739b63c1b8370"
RealmFS images also have a resource image header with a slightly different set of
metainfo variables.
[screen]
citadel:~ # citadel-image metainfo /storage/realms/realmfs-images/main-realmfs.img
image-type = "realmfs"
realmfs-name = "main"
nblocks = 1048575
channel = "realmfs-user"
verity-salt = "ad254e6dd385c0392ed8a6a41b849cfd4ef98ec3643e186feb011d5aa4f1d194"
verity-root = "11922f311b5a9141d65b7ef82e1c9159d75e413d1b420a7e3302ec8ec0ad8593"

11
docs/duck/index.duck Normal file
View File

@ -0,0 +1,11 @@
= Citadel Help
[guide]
== User Guide
[#user .2column]
== Citadel Internals
[#internals .2column]

13
docs/duck/kernel-cmdline.duck Normal file
View File

@ -0,0 +1,13 @@
= Kernel Command Line Options
[topic]
@link[guide >index#internals]
* citadel.noverity
* citadel.nosignatures
* citadel.install
* citadel.overlay
* citadel.channel
* citadel.verbose
* citadel.debug
* citadel.sway

88
docs/duck/realm-config.duck Normal file
View File

@ -0,0 +1,88 @@
= Configuring Realms
[topic]
@link[guide >index#user]
@desc Realm configuration file reference
Realms are usually configured with the tools for managing realms, but the configuration
is stored in a TOML file in the realm directory and can also be edited by hand.
== Options
[terms]
- $code(use-wayland)
* If 'true' access to Wayland display will be permitted in realm by
adding wayland socket /run/user/1000/wayland-0
- $code(use-x11)
* If 'true' access to X11 server will be added to realm by bind mounting directory
/tmp/.X11-unix
- $code(use-sound)
* If 'true' allows the use of sound inside realm. The following items will
be added to realm:
* /dev/snd
* /dev/shm
* /run/user/1000/pulse
- $code(use-kvm)
* If enabled, /dev/kvm will be added to the realm.
This option is only available for nspawn realms.
- $code(use-shared-dir)
* If enabled the directory /realms/Shared will be bind mounted into the home directory of the realm.
This directory is shared between all running realms that have this option enabled as a
convenient way to move files between realms.
- $code(use-ephemeral-home)
* If 'true' the home directory of this realm will be set up in ephemeral mode.
The ephemeral home directory is set up with the following steps
[steps]
* Home directory is mounted as tmpfs
* Any files in /realms/skel are copied into home directory
* Any files in /realms/realm-${name}/skel are copied into home directory
* Any directories listed in $code(ephemeral-persistent-dirs) are bind mounted
from /realms/realm-${name}/home into ephemeral home directory.
- $code(ephemeral-persistent-dirs) default: ["Documents"]
* A list of subdirectories of /realms/realm-${name}/home to bind mount into realm
home directory when $code(ephemeral-home) is enabled.
- $code(use-network)
* network
- $code(network-zone) default: "clear"
* network zone
- $code(use-gpu)
* Enables hardware graphics acceleration in relam.
if 'true' render node device /dev/dri/renderD128 will be added to realm.
- $code(use-gpu-card0)
* If 'true' and $code(use-gpu) is also enabled, privileged device /dev/dri/card0
will be added to realm.
- $code(realmfs) default: "base"
* name of realmfs image
- $code(overlay) default: "storage"
* type of overlay to use
- $code(terminal-scheme)
* terminal color scheme
- $code(extra-bindmounts)
* bind mounts
- $code(extra-bindmounts-ro)
* read-only bind mounts
- $code(system-realm) default: false
* system realm
- $code(autostart) default: false
* autostart realm

139
docs/duck/realmfs.duck Normal file
View File

@ -0,0 +1,139 @@
= RealmFS Images
[topic]
@link[guide >index#user]
@desc Realm root filesystem images
A RealmFS image contains a root filesystem for one or more realm instances.
Similar to resource images, RealmFS images are signed and mounted with dm-verity
to prevent tampering with the data on the root filesystem such as the
installation of malware or backdoors. The keys used to sign RealmFS images are
controlled by the user which makes it possible to upgrade software and install
new packages on the image.
RealmFS images are always mounted as read-only and this property is enforced
with dm-verity. Since RealmFS images are immutable a single image can be shared
between multiple running realm instances. By default, when a realm is launched a
temporary overlay is added to the root filesystem so that changes can be
performed that will last only until the realm is stopped or restarted. This
allows experimenting with the system configuration or installing new software
temporarily. The root filesystem can then be reverted to the original state by
simply restarting the realm.
== Updates
Since the root filesystem of realms are stored on read-only disk images,
packages cannot be permanently installed or upgraded in the usual way. Changes
to the root filesystem will succeed inside a realm, but these changes will be
lost as soon as the realm is stopped or restarted.
To make persistent changes to a RealmFS image, the image is first copied, then
changes are applied to the copy. After applying changes a new dm-verity hash
tree is generated for the image and the RealmFS image header is updated and
signed.
[note .advanced]
The process of generating a signature and a dm-verity hash tree for a RealmFS image
after applying some changes such as updating packages is called $em[.strong](Sealing)
the image.
=== Apt-Cacher NG Realm
Upon booting a system utility realm is started which runs an Apt-Cacher NG
instance. Each realm is configured to use this realm as a proxy for package
installation.
[code]
/etc/apt/apt.conf.d/000apt-cacher-ng-proxy
Acquire::http::Proxy "http://172.17.0.213:3142/";
The apt source lines use the special Apt-Cacher NG syntax.
[code]
/etc/apt/sources.list
deb http://HTTPS///deb.debian.org/debian buster main contrib non-free
Using a package cache avoids downloading and storing packages multiple times
when updating multiple RealmFS images. It also makes it possible to download and
cache packages while connected to a network before booting the system into a
safe mode without enabling the network to perform upgrades of realm packages.
=== Updates (Container method)
First the RealmFS image is copied to a temporary file. On a filesystem such as
btrfs, the image file will be cloned as a reflink rather than copying the file.
The copy of the RealmFS will then be mounted as writable so that changes can be
made. A systemd-nspawn container is launched and a root shell opened so that the
user can update packages, install new software, or perform any other
modifications to the root filesystem.
Once the shell is exited a prompt asks the user if they would like to save the
current changes or discard them. If the user chooses to save the changes, the
copied image is then sealed by generating a dm-verity hash tree and the header
of the image is signed with the user RealmFS sealing key.
=== Updates with pH Hypervisor
When a realm is launched with pH, the overlay is managed by the emulated disk
device of the hypervisor which tracks changes to blocks of the disk and stores
the changed blocks in memory. Since the hypervisor is tracking all of the
changes to the disk, it can also transparently apply the changes and generate a
new sealed RealmFS image and then discard the changed blocks and start directly
using the new image.
This process is initiated by the user when they decide they would like to commit
any changes they have made to the root filesystem in the running realm
permanently to the underlying RealmFS image.
[steps]
* The user makes changes to the root filesystem of the realm and pH tracks the blocks that have changed.
* A user request is made to pH to apply the changes to the RealmFS image.
* pH opens a prompt on the desktop to ask the user to confirm that they really did make this request.
* A copy (or reflink) of the current RealmFS is made, and pH applies the changed blocks to this copy.
* The copy is then sealed with the RealmFS key of the user.
* Now pH can quietly swap in the new version of the RealmFS image and discard all of the tracked block changes.
== Signing RealmFS Images
A secret key for signing RealmFS images is generated during installation and
stored on disk in an encrypted file called the User Keyring. During boot
when the user enters a passphrase to decrypt the disk, this passphrase is also
used to decrypt the keyring file and the public and secret key pair is
loaded into the kernel key storage.
The risk exists that an attacker who is able to compromise the kernel may
recover this secret key. This would allow the attacker to modify sealed RealmFS
images and install backdoors or other malware into realm root filesystems. Even
without obtaining the signing key an attacker who has compromised Citadel could
wait for the user to perform an update and make malicious changes at the same
time which the user will then sign.
For these reasons, it is also possible to configure the system so that only
the public key is retained in the kernel upon boot and the user must boot
into a special mode so that the private key is available to perform updates.
=== Safe Mode
If upgrades are performed in normal operating mode, an attacker who has
compromised citadel can persistently backdoor the upgraded realmfs images.
Safe mode is a way to boot citadel without starting any realms or enabling the
network device. Since the integrity of the Citadel root filesystem is enforced
by dm-verity and no realms are running, even if the system had become compromised
at some point in the past it is assumed to now be in a safe state for performing
updates and signing them with the user sealing keys.
Since the network is not available in safe mode, the packages to be installed or
upgraded must be stored somewhere. By either performing the packge updates with
the $code(--download-only) flag or installing them to the temporary overlay of a realm
the user will cause them to be stored on the Apt-Cache NG service realm so that
they are available for install in safe mode.
== Base RealmFS image
Citadel ships with a RealmFS image called $code(base-realmfs.img). There is nothing
special about this image other than that it is initially signed by Subgraph until
the user modifies or updates it. During installation, a copy of this RealmFS is
created with the name $code(main-realmfs.img) and sealed with the newly generated
user keys.

56
docs/duck/realms.duck Normal file
View File

@ -0,0 +1,56 @@
= Citadel Realms
[topic]
@link[guide >index#user]
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.
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 $em(current) realm
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.
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.
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.
== Realm 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.
[screen]
/realms
config
/Shared
/skel
/default.realm -> realm-main
/realm-main
/realm-project
/realm-testing
=== /realms/config
This is the global realm configuration file. Options set in this file apply to every realm
unless the same option has been overridden with a different value in the config file for
a realm.
=== /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.

242
docs/duck/resource-image.duck Normal file
View File

@ -0,0 +1,242 @@
= Citadel Resource Images
[topic]
@link[guide >index#internals]
Resource images are disk image files that are mounted read-only to create
the citadel filesystem. The first block (4096 bytes) of the image file
contains a header and immediately following the header is the raw disk
image contents.
The header contains information about the image including parameters for
configuring dm-verity to enforce the immutability of the image. The header
also contains a public key signature over the image information so that
the authenticity of the header information can be verified.
The root filesystem of citadel is also distributed as a resource image, and
this image will be installed to a disk partition for normal operation.
Resource images other than the root filesystem are mounted by creating loop
devices on the image file. Prior to mounting the image dm-verity is configured
on the loop device or the rootfs partition.
== Resource Image Types
Currently the following image types are defined for use in Citadel:
=== 1) Base Root Filesystem ("rootfs")
The base rootfs image is the only image type which is installed to a
partition. It is mounted as the root of the Citadel filesystem. When an
image is installed on a partition the 4906 byte header block is stored in
the last block (8 sectors) of the partition.
Citadel uses two partitions (A & B) for the root filesystem. This allows
updating one partition while the other one is being used. Then the system
can be rebooted into the updated rootfs partition. If the system fails to
boot after updating it will be reverted to use the working partition.
=== 2) Kernel Image ("kernel")
The kernel modules for the running kernel are stored in a resource image
so that the root filesystem is independent from the running kernel.
During boot, this image is mounted and the kernel modules and a bind mount
is created over /usr/lib/modules on the Citadel root filesystem.
=== 3) Extra Resource Image ("extra")
This image type contains additional directories of files which are mounted
during boot on the Citadel root filesystem. It contains files such as
firmware files and desktop icons which occupy substantial space but do not
need to be updated frequently.
By placing these files into a separate image the size of the root filesystem
image is reduced. This makes the more frequently updated rootfs image
smaller.
=== 4) Realm Filesystem Image ("realmfs")
This type of image contains the entire root filesystem for running a realm
container or VM. Unlike the other types of resource images, these images can
be modified and then signed with keys controlled by the user. This allows
updates and installation of software while still preserving the read-only
property.
=== Image Layout
Each resource image file reserves an initial 4096 byte block where a header is
stored. This is the maximum length of the header, which is generally much
smaller than this size.
Following the header is a raw disk filesystem image which may optionally be
compressed with xz compression algorithm. The disk image filesystem is ext4,
but this is an implementation detail which may change in the future. A header
flag (FLAG_DATA_COMPRESSED) indicates if an image is compressed and if so the
image must be decompressed before being used. Image updates are distributed in
compressed form and are decompressed once during installation.
When dm-verity is used a hash tree must be generated for the image. When an
image is installed it is first decompressed and then the dm-verity hash data
is generated. This hash data is stored in the image file immediately following
the image data and the flag FLAG_HASH_TREE is set to indicate this data is
present.
Image file:
[code]
[[[
[ Header ][ Ext4 Disk Image ][ dm-verity hash data ]
]]]
Partition:
[code]
[[[
[ Ext4 Disk Image ][ dm-verity hash data ][ unused space ][ Header ]
]]]
== Image Header
The image header contains the following fields.
[table]
[tr]
- Field
- Size
- Content
[tr]
* MAGIC
* 4 bytes
* ('S', 'G', 'O', 'S')
[tr]
* status
* 1 byte
* Used by images installed to partition
[tr]
* flags
* 1 byte
* Various flag values
[tr]
* metainfo-len
* 2 bytes
* 16 bit big-endian length
[tr]
* metainfo
* (metainfo-len) bytes
* TOML document containing key-value pairs
[tr]
* signature
* 64 bytes
* ed25519 signature over metainfo field
=== Header Fields
==== MAGIC
The initial 4 bytes are always set to the ascii bytes 'SGOS' so that a
valid image file can easily be identified.
==== status
The `status` field is used only on base rootfs image installed on a partition.
It must be set to 0 for all other images. The field is used to make decisions
about which parition to attempt to boot.
The status value is stored in the low nibble (4 bits) of this field and the
high nibble is reserved for counting boot attempts in `STATUS_TRY_BOOT` state.
The defined status values are:
[table]
[tr]
- status
- value
- description
[tr]
* STATUS_INVALID
* 0
* Partition does not contain a valid image
[tr]
* STATUS_NEW
* 1
* Newly written partition which has not yet been booted
[tr]
* STATUS_TRY_BOOT
* 2
* Set when booting a partition for the first time
[tr]
* STATUS_GOOD
* 3
* Partition has been successfully booted at least once
[tr]
* STATUS_FAILED
* 4
* Partition has failed to boot
[tr]
* STATUS_BAD_SIG
* 5
* Signature verification on metainfo failed
[tr]
* STATUS_BAD_META
* 6
* Parsing metainfo field failed
==== flags
[table]
[tr]
- flag
- value
- description
[tr]
* FLAG_PREFERRED_BOOT
* 0x01
* Override boot choice to boot from this partition
[tr]
* FLAG_HASH_TREE
* 0x02
* Image contains an appended dm-verity hash tree
[tr]
* FLAG_DATA_COMPRESSED
* 0x04
* Image is compressed with xz
==== metainfo-len
Length in bytes of the `metainfo` field.
Since header page has a fixed size of one block (4096 bytes), and all other
header fields have fixed sizes the maximum length of the `metainfo` field is
4096 - (4 + 2 + 2 + 64) = 4024 bytes
==== metainfo
==== signature
When the rootfs partition is chosen to mount, an attempt will be made to verify
the signature before configuring dm-verity. If this signature verification
fails, the partition status will be changed to `STATUS_BAD_SIG`
=== Booting
During boot of Citadel, the initramfs sets up the Citadel root filesystem. The
filesystem is built by locating and mounting three components:
* Base root filesystem
* Kernel modules
* Extra resources
The base root filesystem is stored on a partition unless running in certain
special modes such as installer and live disk. During installation the same
base root filesystem image is mounted from a loop mounted image file. This same
file will eventually be written to a partition during installation.
Kernel modules and extra resources are stored in file images which are
loop mounted during boot.
An additional type of resource image called a sealed application image exists
for the creation of immutable application image filesystems.
Resource images can optionally have dm-verity enabled when mounted.

247
docs/realms.md
View File

@ -1,247 +0,0 @@
Citadel Realms
--------------
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.
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.
Citadel provides a command-line tool `realms` for creating, managing, and launching Realm instances.
### 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
the symlink `/realm/default.realm` to point to a different realm instance directory.
citadel:~# realms default
Default Realm: main
citadel:~# realms default project
[+] default realm changed from 'main' to 'project'
citadel:~# realms default
Default Realm: project
### The `current` realm
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.
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.
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 <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
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.
/realms
config
/Shared
/skel
/default.realm -> realm-main
/realm-main
/realm-project
/realm-testing
#### 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.
#### 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.
#### 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.
#### 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.
#### Directory `/realms/realm-$name`
This is a realm instance directory, for a realm with $name as the realm name.
/realm-main
config
/home
/rootfs
##### `config`
Configuration file for the realm instance copied from `/realms/config` or
created by the user.
##### `/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
[...]

20
meta-citadel/recipes-citadel/citadel-documentation/citadel-documentation.bb Normal file
View File

@ -0,0 +1,20 @@
DESCRIPTION = "Citadel Yelp Documentation"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
inherit allarch
SRC_URI = "\
file://pages \
file://citadel-documentation.desktop \
"
do_install() {
install -m 0755 -d ${D}${datadir}/citadel-documentation
install -m 0755 -d ${D}${datadir}/applications
install -m 0644 ${WORKDIR}/pages/*.page ${D}${datadir}/citadel-documentation
install -m 0644 ${WORKDIR}/citadel-documentation.desktop ${D}${datadir}/applications
}
FILES_${PN} = "/"

9
meta-citadel/recipes-citadel/citadel-documentation/files/citadel-documentation.desktop Normal file
View File

@ -0,0 +1,9 @@
[Desktop Entry]
Name=Citadel Documentation
Keywords=documentation;information;manual;help;
Categories=Core;Documentation;
Icon=help-browser
Exec=/usr/libexec/citadel-run yelp /opt/share/citadel-documentation
Type=Application
Terminal=false
StartupNotify=true

66
meta-citadel/recipes-citadel/citadel-documentation/files/pages/boot.page Normal file
View File

@ -0,0 +1,66 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="boot">
<info>
<link type="guide" xref="index#internals"/>
</info>
<title>Booting Citadel </title>
<section>
<title>Disk Layout</title>
<p>When Citadel is installed two disk partitions are created on the target disk.</p>
<screen>sda 8:0 0 477G 0 disk
├─sda1 8:1 0 511M 0 part
└─sda2 8:2 0 476.5G 0 part</screen>
<p>The first partition is an EFI boot partition and the second partition is LUKS encrypted
and contains multiple LVM volumes when decrypted.</p>
<screen>
/dev/sda1 /dev/sda2
[EFI ESP Boot partition] [ LUKS encrypted partition filling remainder of disk ]
. .
. .
. | .
. | .
. V .
. .
[ rootfsA ] [ rootfsB ] [ citadel-storage ]
</screen>
<p>There are three logical volumes. Two root filesystem partitions so that one partition
can be updated while the other one is in use, and the remaining space is contained
in a volume called 'storage'.</p>
<screen type="sh"># lvs
LV VG Attr LSize
rootfsA citadel -wi-a----- 2.00g
rootfsB citadel -wi-ao---- 2.00g
storage citadel -wi-ao---- 472.43g</screen>
<section>
<title>Bootloader</title>
<section>
<title>LUKS</title>
<p>The kernel initramfs has an /etc/crypttab file which guides the discovery of the LUKS partition.
The UUID of the LUKS partition is hardcoded to the value listed below. If citadel is installed
on more than one device on the system, the intended LUKS partition may not be chosen correctly.
This problem can be addressed by changing the UUID of other citadel LUKS partitions and passing
the UUID on kernel commandline to override /etc/crypttab. See systemd-cryptsetup-generator(8).</p>
<screen type="sh"># cat /etc/crypttab
luks UUID=683a17fc-4457-42cc-a946-cde67195a101 - discard</screen>
</section>
<section>
<title>Mounting rootfs</title>
<p>The initramfs boot stage is orchestrated by various systemd unit files which can be found
in the citadel source tree at:</p>
<screen>citadel/meta-citadel/recipes-initrd/citadel-initramfs</screen>
<p>The same kernel and initramfs is used for the installer image. One task of these unit files
is to set up a live mode boot when a certain kernel command line option is set. For a regular
boot, a pair of unit files will attempt to mount the root filesystem partition when it becomes
available:</p>
<screen>citadel-rootfs-mount.path
citadel-rootfs-mount.service</screen>
<p>The .path unit triggers every time /dev/mapper changes and the corresponding .service unit is
activated only when all of the LVM volumes inside</p>
<screen>ConditionPathExists=/dev/mapper/citadel-rootfsA
ConditionPathExists=/dev/mapper/citadel-rootfsB
ConditionPathExists=/dev/mapper/citadel-storage</screen>
</section>
</section>
</section>
</page>

57
meta-citadel/recipes-citadel/citadel-documentation/files/pages/citadel.page Normal file
View File

@ -0,0 +1,57 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="citadel">
<info>
<link type="guide" xref="index"/>
<desc>Introduction to Subgraph Citadel</desc>
</info>
<title>Subgraph Citadel</title>
<section>
<title>What is Citadel?</title>
<p>Citadel is the base operating system of the new version of Subgraph OS.</p>
<p>Citadel runs the GNOME desktop session and a few basic system services and
nothing else. It is built and distributed as a single static disk image
rather than as a collection of software packages like a traditional Linux
distribution such as Ubuntu or Fedora. Citadel disk images are built entirely
from the source code of the individual software components. This gives us
complete control over what is included and how each component is configured.</p>
<note style="advanced">
<p>Citadel is a modern desktop operating system based on the GNOME desktop, but if you
prefer we also include an tiling window manager called Sway as an alternative.</p>
</note>
<p>Since the Citadel root filesystem is immutable it is not possible to install
applications such as a web browser or text editor directly into Citadel.
Instead applications are run in a separate isolated environment called a Realm.</p>
<p>When Citadel is first installed a single primary Realm is created and while running
a single realm the system resembles and behaves similar to any other desktop Linux
system. The separation between Citadel and the realm in which user applications are
launched is mostly transparent to the user. However, a user may create as many new
realms as they like and each new realm behaves like a freshly installed Debian Linux
environment where the user may install packages and store files.</p>
<p>Realms are implemented in Subgraph OS as either containers or as virtual machines
running in a custom KVM hypervisor. Both approaches have advantages so the user is
free to choose either option for each realm they create.</p>
<note style="advanced">
<p>Hypervisor isolation is stronger and more secure, but container isolation uses
less system resources and makes it possible to access hardware devices and other
system features directly. A Citadel user can decide which configuration makes
more sense for each Realm they create.</p>
</note>
<section>
<title>Stateless Foundation</title>
<p>In the architecture of Citadel the building blocks of the system are
immutable filesystem images rather than packages. These images are mounted
read-only and this property is enforced with a Linux kernel feature (dm-verity)
which efficiently guarantees each block loaded from disk has a valid
cryptographic checksum. This means that Citadel always loads exactly the
operating system software prepared by Subgraph and rebooting the system will
always brings the computer into a known consistent state.</p>
<p>When Citadel is updated an entirely new image is loaded rather than applying
a set of changes on top of an existing filesystem. By atomically updating the
entire system from one version to the next there is only ever a single software
configuration to consider and the system can never end up in an inconsistent state.
System upgrades cannot break your computer in mysterious ways and even if an
upgrade fails to boot for some reason, the system simply reverts to the
previously working version.</p>
</section>
</section>
</page>

24
meta-citadel/recipes-citadel/citadel-documentation/files/pages/developer.page Normal file
View File

@ -0,0 +1,24 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="developer">
<info>
<link type="guide" xref="index#internals"/>
</info>
<title>Developer Guide</title>
<section>
<title>Make Root Filesystem Writable</title>
<p>Sometimes it can be useful to make changes directly to the citadel root filesystem to
experiment with changes or to debug a problem.</p>
<p>First <code>citadel.noverity</code> must be added to the kernel commandline. After booting with
this command line option verify that dm-verity has been disabled with the <code>dmsetup</code>
command.</p>
<screen># dmsetup status rootfs
0 4194304 linear</screen>
<p>If the output displays <code>verity</code> instead of <code>linear</code> then dm-verity is enabled
and the disk cannot be safely written to.</p>
<p>Next remount the root filesystem with read-write flag.</p>
<screen># mount -oremount,rw,noatime /</screen>
</section>
<section>
<title>Debugging GNOME startup</title>
</section>
</page>

184
meta-citadel/recipes-citadel/citadel-documentation/files/pages/disk-layout.page Normal file
View File

@ -0,0 +1,184 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="disk-layout">
<info>
<link type="guide" xref="index#internals"/>
<desc>A Hands-on guide the Citadel Disk and Filesystem Layout</desc>
</info>
<title>Disk Layout</title>
<section>
<title>Partitions</title>
<p>During installation, two partitions are created on the disk chosen as
the target of the install.</p>
<p>For example, if the installation disk is <code>/dev/sda</code>:</p>
<terms>
<item>
<title><code>/dev/sda1</code></title>
<p>512MB EFI System Partition</p>
</item>
<item>
<title><code>/dev/sda2</code></title>
<p>Remainder of the disk</p>
</item>
</terms>
<p>The partition layout of a running system can be viewed by running the <code>lsblk</code> command.</p>
<screen>citadel:~ # lsblk /dev/sda
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 477G 0 disk
├─sda1 8:1 0 511M 0 part
└─sda2 8:2 0 476.5G 0 part
└─luks 252:0 0 476.4G 0 crypt
├─citadel-rootfsA 252:1 0 2G 0 lvm
│ └─rootfs 252:4 0 354M 1 crypt /
├─citadel-rootfsB 252:2 0 2G 0 lvm
└─citadel-storage 252:3 0 472.4G 0 lvm /storage</screen>
<p>Several further block devices are created during boot when the main disk partition
is decrypted.</p>
<screen>sda
├─sda1 (a) /boot partition
└─sda2 (b) LUKS encrypted partition
└─citadel (c) LVM volume group
├─citadel-rootfsA (d1) rootfs partition A (Read Only)
│ └─rootfs (e) The dm-verity device created for rootfsA
├─citadel-rootfsB (d2) rootfs partition B (Read Only)
└─citadel-storage (f) mounted as /storage (Read/Write)</screen>
<terms>
<item>
<title><code>(a) /boot partition</code></title>
<p>EFI boot partition</p>
</item>
<item>
<title><code>(b) LUKS encrypted partition</code></title>
<p>Remainder of disk is an encrypted volume</p>
</item>
<item>
<title><code>(c) LVM volume group</code></title>
<p>Main partition contains several LVM volumes</p>
</item>
<item>
<title><code>(d) citadel-rootfs(A/B)</code></title>
<p>Two root partitions so one can be updated while other is in use.</p>
</item>
<item>
<title><code>(e) /dev/mapper/rootfs</code></title>
<p>verity mapper device for mounted root partion</p>
</item>
<item>
<title><code>(f) /dev/mapper/citadel-storage</code></title>
<p>The writable filesystem</p>
</item>
</terms>
</section>
<section>
<title>Citadel Filesystem Layout</title>
<code>/
├─ /run/citadel/images/
│ │
│ ├─ modules.mountpoint/ (modules image mounted here)
│ └─ extra.mountpoint/ (extra image mounted here)
│
└─ /storage
│
├─ resources/dev (resource images for channel 'dev')
│ │
│ ├─base-realmfs.img
│ └─main-realmfs.img
│
├─ /realms (/realms is a bind mount of /storage/realms)
│ ├─skel/
│ └─config
│
├─ /realms/realmfs-images
│ │
│ ├─citadel-kernel-5.7-dev-001.img
│ └─citadel-extra-dev-001.img
│
└─ /realms/realm-main
├─ home
└─ config</code>
</section>
<section>
<title>Resource Image Mounts</title>
<p>Resource images are mounted into the system by creating loop devices. These devices can be
viewed by running the 'losetup' command inside Citadel.</p>
<screen>citadel:~ # losetup -ONAME,OFFSET,RO,BACK-FILE
NAME OFFSET RO BACK-FILE
/dev/loop1 4096 1 /storage/resources/dev/citadel-extra-dev-001.img
/dev/loop2 4096 1 /storage/realms/realmfs-images/main-realmfs.img
/dev/loop0 4096 1 /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img</screen>
<p>Resource image files are protected against accidental changes or malicious tampering by
using dm-verity so that the kernel verifies a cryptographic checksum of each block loaded
from the image.</p>
<p>You can view the verity device mapper node associated with each loop device with
the <code>lsblk</code> command.</p>
<screen>citadel:~ # lsblk /dev/loop0 /dev/loop1 /dev/loop4
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
loop0 7:0 0 116.9M 1 loop
└─verity-kernel 252:5 0 116M 1 crypt /run/citadel/images/kernel.mountpoint
loop1 7:1 0 938.9M 1 loop
└─verity-extra 252:6 0 931.5M 1 crypt /run/citadel/images/extra.mountpoint
loop2 7:2 0 4G 1 loop
└─verity-realmfs-main-11922f31 252:9 0 4G 1 crypt /run/citadel/realmfs/realmfs-main-11922f31.mountpoint</screen>
<p>Parameters of each dm-verity instance can be viewed with the veritysetup command.</p>
<screen>citadel:~ # veritysetup status verity-kernel
/dev/mapper/verity-kernel is active and is in use.
type: VERITY
status: verified
hash type: 1
data block: 4096
hash block: 4096
hash name: sha256
salt: fa430cb7887de60dca6fd1974868036ea39cf5017eb55f02e3a76f82a12a0431
data device: /dev/loop0
data loop: /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
size: 237536 sectors
mode: readonly
hash device: /dev/loop0
hash loop: /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
hash offset: 237544 sectors</screen>
<p>When a resource image file is mounted, a file in the root directory called 'manifest' lists
bind mounts to perform to integrate the image into the Citadel root filesystem.</p>
<p>Each line of this file is a directory to bind mount from the mounted image to the root
filesystem. If a directory should be mounted to a location which is different than
the source directory the source and target directories are both listed on a single
line and separated by the ':' character. In the 'extra' image below, the directory
/usr/share from the resource image is mounted to /opt/share on the Citadel filesystem.</p>
<screen>citadel:~ # cat /run/citadel/images/kernel.mountpoint/manifest
/usr/lib/modules
citadel:~ # cat /run/citadel/images/extra.mountpoint/manifest
/usr/lib/firmware
/usr/share:/opt/share</screen>
<p>The citadel-image utility can be used to view the metainfo variables stored in the header
section of a resource image file.</p>
<screen>citadel:~ # citadel-image metainfo /storage/resources/dev/citadel-extra-dev-001.img
image-type = "extra"
channel = "dev"
version = 1
timestamp = "20190331172025"
nblocks = 195924
shasum = "04e6f58afa6f608aff2d6cbb47cbe704f8ab0995f4dfe8e1c03655dc9bb6635a"
verity-salt = "7bf3eec3c51ffd2e82329a9fc6fe42915743874d7c5af43589e589c037ae81e5"
verity-root = "b94eb3431c4fb95e5b9bd62b4505d089414ae660d75eee0fce54b8483d3f9571"
citadel:~ # citadel-image metainfo /storage/resources/dev/citadel-kernel-5.0.6-dev-000.img
image-type = "kernel"
kernel-version = "5.0.6"
kernel-id = "36b7a960dcd51d1649f83a7361f9eb5c2af5741ce6cc53689b411347aa1298b6"
channel = "dev"
version = 1
timestamp = "20190407002748"
nblocks = 29692
shasum = "c988bd7d468c409eb6cd3af8fa9e17b0a75a72d6ad765ad1749d15628a9096be"
verity-salt = "fa430cb7887de60dca6fd1974868036ea39cf5017eb55f02e3a76f82a12a0431"
verity-root = "f4c4fbaebb59d348bd44cfb1cdef54a813728aabc5acc439c2e739b63c1b8370"</screen>
<p>RealmFS images also have a resource image header with a slightly different set of
metainfo variables.</p>
<screen>citadel:~ # citadel-image metainfo /storage/realms/realmfs-images/main-realmfs.img
image-type = "realmfs"
realmfs-name = "main"
nblocks = 1048575
channel = "realmfs-user"
verity-salt = "ad254e6dd385c0392ed8a6a41b849cfd4ef98ec3643e186feb011d5aa4f1d194"
verity-root = "11922f311b5a9141d65b7ef82e1c9159d75e413d1b420a7e3302ec8ec0ad8593"</screen>
</section>
</page>

10
meta-citadel/recipes-citadel/citadel-documentation/files/pages/index.page Normal file
View File

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
<title>Citadel Help</title>
<section id="user" style="2column">
<title>User Guide</title>
</section>
<section id="internals" style="2column">
<title>Citadel Internals</title>
</section>
</page>

33
meta-citadel/recipes-citadel/citadel-documentation/files/pages/kernel-cmdline.page Normal file
View File

@ -0,0 +1,33 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="kernel-cmdline">
<info>
<link type="guide" xref="index#internals"/>
</info>
<title>Kernel Command Line Options</title>
<list>
<item>
<p>citadel.noverity</p>
</item>
<item>
<p>citadel.nosignatures</p>
</item>
<item>
<p>citadel.install</p>
</item>
<item>
<p>citadel.overlay</p>
</item>
<item>
<p>citadel.channel</p>
</item>
<item>
<p>citadel.verbose</p>
</item>
<item>
<p>citadel.debug</p>
</item>
<item>
<p>citadel.sway</p>
</item>
</list>
</page>

123
meta-citadel/recipes-citadel/citadel-documentation/files/pages/realm-config.page Normal file
View File

@ -0,0 +1,123 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="realm-config">
<info>
<link type="guide" xref="index#user"/>
<desc>Realm configuration file reference</desc>
</info>
<title>Configuring Realms</title>
<p>Realms are usually configured with the tools for managing realms, but the configuration
is stored in a TOML file in the realm directory and can also be edited by hand.</p>
<section>
<title>Options</title>
<terms>
<item>
<title><code>use-wayland</code></title>
<p>If 'true' access to Wayland display will be permitted in realm by
adding wayland socket /run/user/1000/wayland-0</p>
</item>
<item>
<title><code>use-x11</code></title>
<p>If 'true' access to X11 server will be added to realm by bind mounting directory
/tmp/.X11-unix</p>
</item>
<item>
<title><code>use-sound</code></title>
<p>If 'true' allows the use of sound inside realm. The following items will
be added to realm:</p>
<list>
<item>
<p>/dev/snd</p>
</item>
<item>
<p>/dev/shm</p>
</item>
<item>
<p>/run/user/1000/pulse</p>
</item>
</list>
</item>
<item>
<title><code>use-kvm</code></title>
<p>If enabled, /dev/kvm will be added to the realm.
This option is only available for nspawn realms.</p>
</item>
<item>
<title><code>use-shared-dir</code></title>
<p>If enabled the directory /realms/Shared will be bind mounted into the home directory of the realm.
This directory is shared between all running realms that have this option enabled as a
convenient way to move files between realms.</p>
</item>
<item>
<title><code>use-ephemeral-home</code></title>
<p>If 'true' the home directory of this realm will be set up in ephemeral mode.
The ephemeral home directory is set up with the following steps</p>
<steps>
<item>
<p>Home directory is mounted as tmpfs</p>
</item>
<item>
<p>Any files in /realms/skel are copied into home directory</p>
</item>
<item>
<p>Any files in /realms/realm-${name}/skel are copied into home directory</p>
</item>
<item>
<p>Any directories listed in <code>ephemeral-persistent-dirs</code> are bind mounted
from /realms/realm-${name}/home into ephemeral home directory.</p>
</item>
</steps>
</item>
<item>
<title><code>ephemeral-persistent-dirs</code> default: ["Documents"]</title>
<p>A list of subdirectories of /realms/realm-${name}/home to bind mount into realm
home directory when <code>ephemeral-home</code> is enabled.</p>
</item>
<item>
<title><code>use-network</code></title>
<p>network</p>
</item>
<item>
<title><code>network-zone</code> default: "clear"</title>
<p>network zone</p>
</item>
<item>
<title><code>use-gpu</code></title>
<p>Enables hardware graphics acceleration in relam.
if 'true' render node device /dev/dri/renderD128 will be added to realm.</p>
</item>
<item>
<title><code>use-gpu-card0</code></title>
<p>If 'true' and <code>use-gpu</code> is also enabled, privileged device /dev/dri/card0
will be added to realm.</p>
</item>
<item>
<title><code>realmfs</code> default: "base"</title>
<p>name of realmfs image</p>
</item>
<item>
<title><code>overlay</code> default: "storage"</title>
<p>type of overlay to use</p>
</item>
<item>
<title><code>terminal-scheme</code></title>
<p>terminal color scheme</p>
</item>
<item>
<title><code>extra-bindmounts</code></title>
<p>bind mounts</p>
</item>
<item>
<title><code>extra-bindmounts-ro</code></title>
<p>read-only bind mounts</p>
</item>
<item>
<title><code>system-realm</code> default: false</title>
<p>system realm</p>
</item>
<item>
<title><code>autostart</code> default: false</title>
<p>autostart realm</p>
</item>
</terms>
</section>
</page>

140
meta-citadel/recipes-citadel/citadel-documentation/files/pages/realmfs.page Normal file
View File

@ -0,0 +1,140 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="realmfs">
<info>
<link type="guide" xref="index#user"/>
<desc>Realm root filesystem images</desc>
</info>
<title>RealmFS Images</title>
<p>A RealmFS image contains a root filesystem for one or more realm instances.
Similar to resource images, RealmFS images are signed and mounted with dm-verity
to prevent tampering with the data on the root filesystem such as the
installation of malware or backdoors. The keys used to sign RealmFS images are
controlled by the user which makes it possible to upgrade software and install
new packages on the image.</p>
<p>RealmFS images are always mounted as read-only and this property is enforced
with dm-verity. Since RealmFS images are immutable a single image can be shared
between multiple running realm instances. By default, when a realm is launched a
temporary overlay is added to the root filesystem so that changes can be
performed that will last only until the realm is stopped or restarted. This
allows experimenting with the system configuration or installing new software
temporarily. The root filesystem can then be reverted to the original state by
simply restarting the realm.</p>
<section>
<title>Updates</title>
<p>Since the root filesystem of realms are stored on read-only disk images,
packages cannot be permanently installed or upgraded in the usual way. Changes
to the root filesystem will succeed inside a realm, but these changes will be
lost as soon as the realm is stopped or restarted.</p>
<p>To make persistent changes to a RealmFS image, the image is first copied, then
changes are applied to the copy. After applying changes a new dm-verity hash
tree is generated for the image and the RealmFS image header is updated and
signed.</p>
<note style="advanced">
<p>The process of generating a signature and a dm-verity hash tree for a RealmFS image
after applying some changes such as updating packages is called <em style="strong">Sealing</em>
the image.</p>
</note>
<section>
<title>Apt-Cacher NG Realm</title>
<p>Upon booting a system utility realm is started which runs an Apt-Cacher NG
instance. Each realm is configured to use this realm as a proxy for package
installation.</p>
<code>/etc/apt/apt.conf.d/000apt-cacher-ng-proxy
Acquire::http::Proxy "http://172.17.0.213:3142/";</code>
<p>The apt source lines use the special Apt-Cacher NG syntax.</p>
<code>/etc/apt/sources.list
deb http://HTTPS///deb.debian.org/debian buster main contrib non-free</code>
<p>Using a package cache avoids downloading and storing packages multiple times
when updating multiple RealmFS images. It also makes it possible to download and
cache packages while connected to a network before booting the system into a
safe mode without enabling the network to perform upgrades of realm packages.</p>
</section>
<section>
<title>Updates (Container method)</title>
<p>First the RealmFS image is copied to a temporary file. On a filesystem such as
btrfs, the image file will be cloned as a reflink rather than copying the file.
The copy of the RealmFS will then be mounted as writable so that changes can be
made. A systemd-nspawn container is launched and a root shell opened so that the
user can update packages, install new software, or perform any other
modifications to the root filesystem.</p>
<p>Once the shell is exited a prompt asks the user if they would like to save the
current changes or discard them. If the user chooses to save the changes, the
copied image is then sealed by generating a dm-verity hash tree and the header
of the image is signed with the user RealmFS sealing key.</p>
</section>
<section>
<title>Updates with pH Hypervisor</title>
<p>When a realm is launched with pH, the overlay is managed by the emulated disk
device of the hypervisor which tracks changes to blocks of the disk and stores
the changed blocks in memory. Since the hypervisor is tracking all of the
changes to the disk, it can also transparently apply the changes and generate a
new sealed RealmFS image and then discard the changed blocks and start directly
using the new image.</p>
<p>This process is initiated by the user when they decide they would like to commit
any changes they have made to the root filesystem in the running realm
permanently to the underlying RealmFS image.</p>
<steps>
<item>
<p>The user makes changes to the root filesystem of the realm and pH tracks the blocks that have changed.</p>
</item>
<item>
<p>A user request is made to pH to apply the changes to the RealmFS image.</p>
</item>
<item>
<p>pH opens a prompt on the desktop to ask the user to confirm that they really did make this request.</p>
</item>
<item>
<p>A copy (or reflink) of the current RealmFS is made, and pH applies the changed blocks to this copy.</p>
</item>
<item>
<p>The copy is then sealed with the RealmFS key of the user.</p>
</item>
<item>
<p>Now pH can quietly swap in the new version of the RealmFS image and discard all of the tracked block changes.</p>
</item>
</steps>
</section>
</section>
<section>
<title>Signing RealmFS Images</title>
<p>A secret key for signing RealmFS images is generated during installation and
stored on disk in an encrypted file called the User Keyring. During boot
when the user enters a passphrase to decrypt the disk, this passphrase is also
used to decrypt the keyring file and the public and secret key pair is
loaded into the kernel key storage.</p>
<p>The risk exists that an attacker who is able to compromise the kernel may
recover this secret key. This would allow the attacker to modify sealed RealmFS
images and install backdoors or other malware into realm root filesystems. Even
without obtaining the signing key an attacker who has compromised Citadel could
wait for the user to perform an update and make malicious changes at the same
time which the user will then sign.</p>
<p>For these reasons, it is also possible to configure the system so that only
the public key is retained in the kernel upon boot and the user must boot
into a special mode so that the private key is available to perform updates.</p>
<section>
<title>Safe Mode</title>
<p>If upgrades are performed in normal operating mode, an attacker who has
compromised citadel can persistently backdoor the upgraded realmfs images.
Safe mode is a way to boot citadel without starting any realms or enabling the
network device. Since the integrity of the Citadel root filesystem is enforced
by dm-verity and no realms are running, even if the system had become compromised
at some point in the past it is assumed to now be in a safe state for performing
updates and signing them with the user sealing keys.</p>
<p>Since the network is not available in safe mode, the packages to be installed or
upgraded must be stored somewhere. By either performing the packge updates with
the <code>--download-only</code> flag or installing them to the temporary overlay of a realm
the user will cause them to be stored on the Apt-Cache NG service realm so that
they are available for install in safe mode.</p>
</section>
</section>
<section>
<title>Base RealmFS image</title>
<p>Citadel ships with a RealmFS image called <code>base-realmfs.img</code>. There is nothing
special about this image other than that it is initially signed by Subgraph until
the user modifies or updates it. During installation, a copy of this RealmFS is
created with the name <code>main-realmfs.img</code> and sealed with the newly generated
user keys.</p>
</section>
</page>

51
meta-citadel/recipes-citadel/citadel-documentation/files/pages/realms.page Normal file
View File

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="realms">
<info>
<link type="guide" xref="index#user"/>
</info>
<title>Citadel Realms</title>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<section>
<title>The <em>current</em> realm</title>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section>
<title>Realm directory layout</title>
<p>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.</p>
<screen>/realms
config
/Shared
/skel
/default.realm -> realm-main
/realm-main
/realm-project
/realm-testing</screen>
<section>
<title>/realms/config</title>
<p>This is the global realm configuration file. Options set in this file apply to every realm
unless the same option has been overridden with a different value in the config file for
a realm.</p>
</section>
<section>
<title>/realms/Shared</title>
<p>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.</p>
</section>
</section>
</page>

361
meta-citadel/recipes-citadel/citadel-documentation/files/pages/resource-image.page Normal file
View File

@ -0,0 +1,361 @@
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="resource-image">
<info>
<link type="guide" xref="index#internals"/>
</info>
<title>Citadel Resource Images</title>
<p>Resource images are disk image files that are mounted read-only to create
the citadel filesystem. The first block (4096 bytes) of the image file
contains a header and immediately following the header is the raw disk
image contents.</p>
<p>The header contains information about the image including parameters for
configuring dm-verity to enforce the immutability of the image. The header
also contains a public key signature over the image information so that
the authenticity of the header information can be verified.</p>
<p>The root filesystem of citadel is also distributed as a resource image, and
this image will be installed to a disk partition for normal operation.</p>
<p>Resource images other than the root filesystem are mounted by creating loop
devices on the image file. Prior to mounting the image dm-verity is configured
on the loop device or the rootfs partition.</p>
<section>
<title>Resource Image Types</title>
<p>Currently the following image types are defined for use in Citadel:</p>
<section>
<title>1) Base Root Filesystem ("rootfs")</title>
<p>The base rootfs image is the only image type which is installed to a
partition. It is mounted as the root of the Citadel filesystem. When an
image is installed on a partition the 4906 byte header block is stored in
the last block (8 sectors) of the partition.</p>
<p>Citadel uses two partitions (A &amp; B) for the root filesystem. This allows
updating one partition while the other one is being used. Then the system
can be rebooted into the updated rootfs partition. If the system fails to
boot after updating it will be reverted to use the working partition.</p>
</section>
<section>
<title>2) Kernel Image ("kernel")</title>
<p>The kernel modules for the running kernel are stored in a resource image
so that the root filesystem is independent from the running kernel.</p>
<p>During boot, this image is mounted and the kernel modules and a bind mount
is created over /usr/lib/modules on the Citadel root filesystem.</p>
</section>
<section>
<title>3) Extra Resource Image ("extra")</title>
<p>This image type contains additional directories of files which are mounted
during boot on the Citadel root filesystem. It contains files such as
firmware files and desktop icons which occupy substantial space but do not
need to be updated frequently.</p>
<p>By placing these files into a separate image the size of the root filesystem
image is reduced. This makes the more frequently updated rootfs image
smaller.</p>
</section>
<section>
<title>4) Realm Filesystem Image ("realmfs")</title>
<p>This type of image contains the entire root filesystem for running a realm
container or VM. Unlike the other types of resource images, these images can
be modified and then signed with keys controlled by the user. This allows
updates and installation of software while still preserving the read-only
property.</p>
</section>
<section>
<title>Image Layout</title>
<p>Each resource image file reserves an initial 4096 byte block where a header is
stored. This is the maximum length of the header, which is generally much
smaller than this size.</p>
<p>Following the header is a raw disk filesystem image which may optionally be
compressed with xz compression algorithm. The disk image filesystem is ext4,
but this is an implementation detail which may change in the future. A header
flag (FLAG_DATA_COMPRESSED) indicates if an image is compressed and if so the
image must be decompressed before being used. Image updates are distributed in
compressed form and are decompressed once during installation.</p>
<p>When dm-verity is used a hash tree must be generated for the image. When an
image is installed it is first decompressed and then the dm-verity hash data
is generated. This hash data is stored in the image file immediately following
the image data and the flag FLAG_HASH_TREE is set to indicate this data is
present.</p>
<p>Image file:</p>
<code> [ Header ][ Ext4 Disk Image ][ dm-verity hash data ]</code>
<p>Partition:</p>
<code> [ Ext4 Disk Image ][ dm-verity hash data ][ unused space ][ Header ]</code>
</section>
</section>
<section>
<title>Image Header</title>
<p>The image header contains the following fields.</p>
<table>
<tr>
<th>
<p>Field</p>
</th>
<th>
<p>Size</p>
</th>
<th>
<p>Content</p>
</th>
</tr>
<tr>
<td>
<p>MAGIC</p>
</td>
<td>
<p>4 bytes</p>
</td>
<td>
<p>('S', 'G', 'O', 'S')</p>
</td>
</tr>
<tr>
<td>
<p>status</p>
</td>
<td>
<p>1 byte</p>
</td>
<td>
<p>Used by images installed to partition</p>
</td>
</tr>
<tr>
<td>
<p>flags</p>
</td>
<td>
<p>1 byte</p>
</td>
<td>
<p>Various flag values</p>
</td>
</tr>
<tr>
<td>
<p>metainfo-len</p>
</td>
<td>
<p>2 bytes</p>
</td>
<td>
<p>16 bit big-endian length</p>
</td>
</tr>
<tr>
<td>
<p>metainfo</p>
</td>
<td>
<p>(metainfo-len) bytes</p>
</td>
<td>
<p>TOML document containing key-value pairs</p>
</td>
</tr>
<tr>
<td>
<p>signature</p>
</td>
<td>
<p>64 bytes</p>
</td>
<td>
<p>ed25519 signature over metainfo field</p>
</td>
</tr>
</table>
<section>
<title>Header Fields</title>
<section>
<title>MAGIC</title>
<p>The initial 4 bytes are always set to the ascii bytes 'SGOS' so that a
valid image file can easily be identified.</p>
</section>
<section>
<title>status</title>
<p>The `status` field is used only on base rootfs image installed on a partition.
It must be set to 0 for all other images. The field is used to make decisions
about which parition to attempt to boot.</p>
<p>The status value is stored in the low nibble (4 bits) of this field and the
high nibble is reserved for counting boot attempts in `STATUS_TRY_BOOT` state.</p>
<p>The defined status values are:</p>
<table>
<tr>
<th>
<p>status</p>
</th>
<th>
<p>value</p>
</th>
<th>
<p>description</p>
</th>
</tr>
<tr>
<td>
<p>STATUS_INVALID</p>
</td>
<td>
<p>0</p>
</td>
<td>
<p>Partition does not contain a valid image</p>
</td>
</tr>
<tr>
<td>
<p>STATUS_NEW</p>
</td>
<td>
<p>1</p>
</td>
<td>
<p>Newly written partition which has not yet been booted</p>
</td>
</tr>
<tr>
<td>
<p>STATUS_TRY_BOOT</p>
</td>
<td>
<p>2</p>
</td>
<td>
<p>Set when booting a partition for the first time</p>
</td>
</tr>
<tr>
<td>
<p>STATUS_GOOD</p>
</td>
<td>
<p>3</p>
</td>
<td>
<p>Partition has been successfully booted at least once</p>
</td>
</tr>
<tr>
<td>
<p>STATUS_FAILED</p>
</td>
<td>
<p>4</p>
</td>
<td>
<p>Partition has failed to boot</p>
</td>
</tr>
<tr>
<td>
<p>STATUS_BAD_SIG</p>
</td>
<td>
<p>5</p>
</td>
<td>
<p>Signature verification on metainfo failed</p>
</td>
</tr>
<tr>
<td>
<p>STATUS_BAD_META</p>
</td>
<td>
<p>6</p>
</td>
<td>
<p>Parsing metainfo field failed</p>
</td>
</tr>
</table>
</section>
<section>
<title>flags</title>
<table>
<tr>
<th>
<p>flag</p>
</th>
<th>
<p>value</p>
</th>
<th>
<p>description</p>
</th>
</tr>
<tr>
<td>
<p>FLAG_PREFERRED_BOOT</p>
</td>
<td>
<p>0x01</p>
</td>
<td>
<p>Override boot choice to boot from this partition</p>
</td>
</tr>
<tr>
<td>
<p>FLAG_HASH_TREE</p>
</td>
<td>
<p>0x02</p>
</td>
<td>
<p>Image contains an appended dm-verity hash tree</p>
</td>
</tr>
<tr>
<td>
<p>FLAG_DATA_COMPRESSED</p>
</td>
<td>
<p>0x04</p>
</td>
<td>
<p>Image is compressed with xz</p>
</td>
</tr>
</table>
</section>
<section>
<title>metainfo-len</title>
<p>Length in bytes of the `metainfo` field.</p>
<p>Since header page has a fixed size of one block (4096 bytes), and all other
header fields have fixed sizes the maximum length of the `metainfo` field is
4096 - (4 + 2 + 2 + 64) = 4024 bytes</p>
</section>
<section>
<title>metainfo</title>
</section>
<section>
<title>signature</title>
<p>When the rootfs partition is chosen to mount, an attempt will be made to verify
the signature before configuring dm-verity. If this signature verification
fails, the partition status will be changed to `STATUS_BAD_SIG`</p>
</section>
</section>
<section>
<title>Booting</title>
<p>During boot of Citadel, the initramfs sets up the Citadel root filesystem. The
filesystem is built by locating and mounting three components:</p>
<list>
<item>
<p>Base root filesystem</p>
</item>
<item>
<p>Kernel modules</p>
</item>
<item>
<p>Extra resources</p>
</item>
</list>
<p>The base root filesystem is stored on a partition unless running in certain
special modes such as installer and live disk. During installation the same
base root filesystem image is mounted from a loop mounted image file. This same
file will eventually be written to a partition during installation.</p>
<p>Kernel modules and extra resources are stored in file images which are
loop mounted during boot.</p>
<p>An additional type of resource image called a sealed application image exists
for the creation of immutable application image filesystems.</p>
<p>Resource images can optionally have dm-verity enabled when mounted.</p>
</section>
</section>
</page>

4
meta-citadel/recipes-citadel/images/citadel-extra-image.bb
View File

@ -14,6 +14,7 @@ PACKAGE_INSTALL = "\
adwaita-icon-theme-symbolic \
adwaita-icon-theme-symbolic-hires \
"
CITADEL_IMAGE_VERSION = "${CITADEL_IMAGE_VERSION_extra}"
CITADEL_IMAGE_TYPE = "extra"
@ -23,8 +24,11 @@ inherit citadel-image
ROOTFS_POSTPROCESS_COMMAND += "write_manifest_file; "
write_manifest_file() {
install -m 0755 -d ${IMAGE_ROOTFS}/usr/share/citadel-documentation
cat > ${IMAGE_ROOTFS}/manifest << EOF
/usr/lib/firmware
/usr/share:/opt/share
/sysroot/usr/share/citadel-documentation:/opt/share/citadel-documentation
EOF
}

1
meta-citadel/recipes-citadel/packagegroups/packagegroup-citadel.bb
View File

@ -10,4 +10,5 @@ RDEPENDS_${PN} = "\
citadel-tools \
citadel-tools-realms \
citadel-tools-boot \
citadel-documentation \
"

2
realmfs-builder/basic-image.conf
View File

@ -1 +1 @@
PACKAGES="man manpages vim-nox iputils-ping tmux vifm gnome-terminal firefox nautilus eog evince unzip x264"
PACKAGES="man manpages vim-nox iputils-ping tmux vifm gnome-terminal firefox nautilus eog evince unzip x264 yelp"