shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

docs: Improve HOME_DIRECTORY.md

Browse Source
This commit is contained in:
adrian5 2022-02-08 12:42:19 +01:00 committed by Yu Watanabe
parent 0c7649c2aa
commit fa16642f4a
1 changed files with 25 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
docs/HOME_DIRECTORY.md
View File

@ -9,11 +9,11 @@ SPDX-License-Identifier: LGPL-2.1-or-later
[`systemd-homed.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html) [`systemd-homed.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html)
manages home directories of regular ("human") users. Each directory it manages manages home directories of regular ("human") users. Each directory it manages
encapsulates both the data store and the user record of the user so that it encapsulates both the data store and the user record of the user, so that it
comprehensively describes the user account, and is thus naturally portable comprehensively describes the user account, and is thus naturally portable
between systems without any further, external metadata. This document describes between systems without any further, external metadata. This document describes
the format used by these home directories, in context of the storage mechanism the format used by these home directories, in the context of the storage
used. mechanism used.
## General Structure ## General Structure
@ -22,7 +22,7 @@ user record of the user. It follows the format defined in [`JSON User
Records`](https://systemd.io/USER_RECORD). It is recommended to bring the Records`](https://systemd.io/USER_RECORD). It is recommended to bring the
record into 'normalized' form (i.e. all objects should contain their fields record into 'normalized' form (i.e. all objects should contain their fields
sorted alphabetically by their key) before storing it there, though this is not sorted alphabetically by their key) before storing it there, though this is not
required nor enforced. Since the user record is cryptographically signed the required nor enforced. Since the user record is cryptographically signed, the
user cannot make modifications to the file on their own (at least not without user cannot make modifications to the file on their own (at least not without
corrupting it, or knowing the private key used for signing the record). Note corrupting it, or knowing the private key used for signing the record). Note
that user records are stored here without their `binding`, `status` and that user records are stored here without their `binding`, `status` and
@ -35,13 +35,13 @@ If the plain directory or `btrfs` subvolume storage mechanism of
`systemd-homed` is used (i.e. `--storage=directory` or `--storage=subvolume` on `systemd-homed` is used (i.e. `--storage=directory` or `--storage=subvolume` on
the the
[`homectl(1)`](https://www.freedesktop.org/software/systemd/man/homectl.html) [`homectl(1)`](https://www.freedesktop.org/software/systemd/man/homectl.html)
command line) the home directory requires no special set-up besides including command line) the home directory requires no special setup besides including
the user record in the `~/.identity` file. the user record in the `~/.identity` file.
It is recommended to name home directories managed this way by It is recommended to name home directories managed this way by
`systemd-homed.service` by the user name, suffixed with `.homedir` (example: `systemd-homed.service` by the user name, suffixed with `.homedir` (example:
`lennart.homedir` for a user `lennart`) but this is not enforced. When the user `lennart.homedir` for a user `lennart`) but this is not enforced. When the user
is logged in the directory is generally mounted to `/home/$USER` (in our is logged in, the directory is generally mounted to `/home/$USER` (in our
example: `/home/lennart`), thus dropping the suffix while the home directory is example: `/home/lennart`), thus dropping the suffix while the home directory is
active. `systemd-homed` will automatically discover home directories named this active. `systemd-homed` will automatically discover home directories named this
way in `/home/*.homedir` and synthesize NSS user records for them as they show way in `/home/*.homedir` and synthesize NSS user records for them as they show
@ -54,19 +54,19 @@ mechanism, except that the home directory is encrypted using `fscrypt`. (Use
`--storage=fscrypt` on the `homectl` command line.) Key management is `--storage=fscrypt` on the `homectl` command line.) Key management is
implemented via extended attributes on the directory itself: for each password implemented via extended attributes on the directory itself: for each password
an extended attribute `trusted.fscrypt_slot0`, `trusted.fscrypt_slot1`, an extended attribute `trusted.fscrypt_slot0`, `trusted.fscrypt_slot1`,
`trusted.fscrypt_slot2`, … is maintained. It's value contains a colon-separated `trusted.fscrypt_slot2`, … is maintained. Its value contains a colon-separated
pair of Base64 encoded data fields. The first field contains a salt value, the pair of Base64 encoded data fields. The first field contains a salt value, the
second field the encrypted volume key. The latter is encrypted using AES256 in second field the encrypted volume key. The latter is encrypted using AES256 in
counter mode, using a key derived from the password via PBKDF2-HMAC-SHA512 counter mode, using a key derived from the password via PBKDF2-HMAC-SHA512,
together with the salt value. The construction is similar to what LUKS does for together with the salt value. The construction is similar to what LUKS does for
`dm-crypt` encrypted volumes. Note that extended attributes are not encrypted `dm-crypt` encrypted volumes. Note that extended attributes are not encrypted
by `fscrypt` and hence are suitable for carry the key slots. Moreover, by using by `fscrypt` and hence are suitable for carrying the key slots. Moreover, by
extended attributes the slots are directly attached to the directory and an using extended attributes, the slots are directly attached to the directory and
independent sidecar key database is not required. an independent sidecar key database is not required.
## Storage Mechanism: `cifs` Home Directories ## Storage Mechanism: `cifs` Home Directories
In this storage mechanism the home directory is mounted from a CIFS server and In this storage mechanism, the home directory is mounted from a CIFS server and
service at login, configured inside the user record. (Use `--storage=cifs` on service at login, configured inside the user record. (Use `--storage=cifs` on
the `homectl` command line.) The local password of the user is used to log into the `homectl` command line.) The local password of the user is used to log into
the CIFS service. The directory share needs to contain the user record in the CIFS service. The directory share needs to contain the user record in
@ -85,7 +85,7 @@ media). (Use `--storage=luks` on the `homectl` command line.) Specifically:
* The image contains a GPT partition table. For now it should only contain a * The image contains a GPT partition table. For now it should only contain a
single partition, and that partition must have the type UUID single partition, and that partition must have the type UUID
`773f91ef-66d4-49b5-bd83-d683bf40ad16`. It's partition label must be the `773f91ef-66d4-49b5-bd83-d683bf40ad16`. Its partition label must be the
user name. user name.
* This partition must contain a LUKS2 volume, whose label must be the user * This partition must contain a LUKS2 volume, whose label must be the user
@ -106,24 +106,24 @@ media). (Use `--storage=luks` on the `homectl` command line.) Specifically:
contains a second copy of the user record in the `~/.identity` file, like in contains a second copy of the user record in the `~/.identity` file, like in
the other storage mechanisms. the other storage mechanisms.
The image file should either reside in a directory `/home/` on the system, The image file should reside in a directory `/home/` on the system,
named after the user, suffixed with `.home`. When activated the container home named after the user, suffixed with `.home`. When activated, the container home
directory is mounted to the same path, though with the `.home` suffix dropped — directory is mounted to the same path, though with the `.home` suffix dropped —
unless a different mount point is defined in the user record. (e.g.: the unless a different mount point is defined in the user record. (e.g.: the
loopback file `/home/waldo.home` is mounted to `/home/waldo` while activated.) loopback file `/home/waldo.home` is mounted to `/home/waldo` while activated.)
When the image is stored on removable media (such as a USB stick) the image When the image is stored on removable media (such as a USB stick), the image
file can be directly `dd`'ed onto it, the format is unchanged. The GPT envelope file can be directly `dd`'ed onto it; the format is unchanged. The GPT envelope
should ensure the image is properly recognizable as a home directory both when should ensure the image is properly recognizable as a home directory both when
used in a loopback file and on a removable USB stick. (Note that when mounting used in a loopback file and on a removable USB stick. (Note that when mounting
a home directory from an USB stick it too defaults to a directory in `/home/`, a home directory from an USB stick, it too defaults to a directory in `/home/`,
named after the username, with no further suffix.) named after the username, with no further suffix.)
Rationale for the GPT partition table envelope: this way the image is nicely Rationale for the GPT partition table envelope: this way the image is nicely
discoverable and recognizable already by partition managers as a home discoverable and recognizable already by partition managers as a home
directory. Moreover, when copied onto a USB stick the GPT envelope makes sure directory. Moreover, when copied onto a USB stick the GPT envelope makes sure
the stick is properly recognizable as a portable home directory the stick is properly recognizable as a portable home directory
medium. (Moreover it allows to embed additional partitions later on, for medium. (Moreover, it allows embedding additional partitions later on, for
example for allowing a multi-purpose USB stick that contains both a home example on a multi-purpose USB stick that contains both a home
directory and a generic storage volume.) directory and a generic storage volume.)
Rationale for including the encrypted user record in the LUKS2 header: Rationale for including the encrypted user record in the LUKS2 header:
@ -133,7 +133,7 @@ images can be used as attack vectors, exploiting the kernel. Thus it is
necessary to validate the home directory image *before* mounting it and necessary to validate the home directory image *before* mounting it and
establishing a minimal level of trust. Since the user record data is establishing a minimal level of trust. Since the user record data is
cryptographically signed and user records not signed with a recognized private cryptographically signed and user records not signed with a recognized private
key are not accepted a minimal level of trust between the system and the home key are not accepted, a minimal level of trust between the system and the home
directory image is established. directory image is established.
Rationale for storing the home directory one level below to root directory of Rationale for storing the home directory one level below to root directory of
@ -145,10 +145,10 @@ do not show up in the user's home directory.
Regardless of the storage mechanism used, an activated home directory Regardless of the storage mechanism used, an activated home directory
necessarily involves a mount point to be established. In case of the necessarily involves a mount point to be established. In case of the
directory-based storage mechanisms (`directory`, `subvolume` and `fscrypt`) directory-based storage mechanisms (`directory`, `subvolume` and `fscrypt`)
this is a bind mount, in case of `cifs` this is a CIFS network mount, and in this is a bind mount. In case of `cifs` this is a CIFS network mount, and in
case of the LUKS2 backend a regular block device mount of the file system case of the LUKS2 backend a regular block device mount of the file system
contained in the LUKS2 image. By requiring a mount for all cases (even for contained in the LUKS2 image. By requiring a mount for all cases (even for
those that already are a directory) a clear logic is defined to distinguish those that already are a directory), a clear logic is defined to distinguish
active and inactive home directories, so that the directories become active and inactive home directories, so that the directories become
inaccessible under their regular path the instant they are inaccessible under their regular path the instant they are
deactivated. Moreover, the `nosuid`, `nodev` and `noexec` flags configured in deactivated. Moreover, the `nosuid`, `nodev` and `noexec` flags configured in
@ -161,7 +161,7 @@ compared. Activation is only permitted if they match the same user and are
signed by a recognized key. When the three instances differ in `lastChangeUSec` signed by a recognized key. When the three instances differ in `lastChangeUSec`
field, the newest record wins, and is propagated to the other two locations. field, the newest record wins, and is propagated to the other two locations.
During activation the file system checker (`fsck`) appropriate for the During activation, the file system checker (`fsck`) appropriate for the
selected file system is automatically invoked, ensuring the file system is in a selected file system is automatically invoked, ensuring the file system is in a
healthy state before it is mounted. healthy state before it is mounted.
@ -169,7 +169,7 @@ If the UID assigned to a user does not match the owner of the home directory in
the file system, the home directory is automatically and recursively `chown()`ed the file system, the home directory is automatically and recursively `chown()`ed
to the correct UID. to the correct UID.
Depending on the `luksDiscard` setting of the user record either the backing Depending on the `luksDiscard` setting of the user record, either the backing
loopback file is `fallocate()`ed during activation, or the mounted file system loopback file is `fallocate()`ed during activation, or the mounted file system
is `FITRIM`ed after mounting, to ensure the setting is correctly enforced. is `FITRIM`ed after mounting, to ensure the setting is correctly enforced.