citadel/docs/duck/disk-layout.duck

199 lines
7.4 KiB
Plaintext
Raw Normal View History

2020-12-07 17:24:22 -05:00
= 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"