]>
Commit | Line | Data |
---|---|---|
b05e1220 LP |
1 | --- |
2 | title: systemd-homed and JSON User/Group Record Support in Desktop Environments | |
5fe63895 | 3 | category: Users, Groups and Home Directories |
b05e1220 | 4 | layout: default |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
b05e1220 LP |
6 | --- |
7 | ||
8 | # `systemd-homed` and JSON User/Group Record Support in Desktop Environments | |
9 | ||
10 | Starting with version 245, systemd supports a new subsystem | |
11 | [`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html) | |
d85c8335 | 12 | for managing regular ("human") users and their home directories. |
13 | Along with it a new concept `userdb` got merged that brings rich, extensible JSON user/group | |
14 | records, extending the classic UNIX/glibc NSS `struct passwd`/`struct group` structures. | |
15 | Both additions are added in a fully backwards compatible way, accessible through `getpwnam()`/`getgrnam()`/… (i.e. libc NSS) and PAM as | |
b05e1220 | 16 | usual, meaning that for basic support no changes in the upper layers of the |
d85c8335 | 17 | stack (in particular desktop environments, such as GNOME or KDE) have to be made. |
18 | However, for better support a number of changes to desktop environments are recommended. | |
19 | A few areas where that applies are discussed below. | |
b05e1220 LP |
20 | |
21 | Before reading on, please read up on the basic concepts, specifically: | |
22 | ||
0d592a5e FS |
23 | * [Home Directories](/HOME_DIRECTORY) |
24 | * [JSON User Records](/USER_RECORD) | |
25 | * [JSON Group Records](/GROUP_RECORD) | |
26 | * [User/Group Record Lookup API via Varlink](/USER_GROUP_API) | |
b05e1220 LP |
27 | |
28 | ## Support for Suspending Home Directory Access during System Suspend | |
29 | ||
30 | One key feature of `systemd-homed` managed encrypted home directories is the | |
31 | ability that access to them can be suspended automatically during system sleep, | |
d85c8335 | 32 | removing any cryptographic key material from memory while doing so. |
33 | This is important in a world where most laptop users seldom shut down their computers | |
34 | but most of the time just suspend them instead. | |
35 | Previously, the encryption keys for the home directories remained in memory during system suspend, so that | |
36 | sufficiently equipped attackers could read them from there and gain full access to the device. | |
37 | By removing the key material from memory before suspend, and re-requesting it on resume this attack vector can be closed down effectively. | |
b05e1220 LP |
38 | |
39 | Supporting this mechanism requires support in the desktop environment, since | |
40 | the encryption keys (i.e. the user's login password) need to be reacquired on | |
d85c8335 | 41 | system resume, from a lock screen or similar. |
42 | This lock screen must run in system context, and cannot run in the user's own context, since otherwise it | |
b05e1220 LP |
43 | might end up accessing the home directory of the user even though access to it |
44 | is temporarily suspended and thus will hang if attempted. | |
45 | ||
46 | It is suggested that desktop environments that implement lock screens run them | |
47 | from system context, for example by switching back to the display manager, and | |
48 | only revert back to the session after re-authentication via this system lock | |
49 | screen (re-authentication in this case refers to passing the user's login | |
d85c8335 | 50 | credentials to the usual PAM authentication hooks). |
51 | Or in other words, when going into system suspend it is recommended that GNOME Shell switches back to | |
b05e1220 LP |
52 | the GNOME Display Manager login screen which now should double as screen lock, |
53 | and only switches back to the shell's UI after the user re-authenticated there. | |
54 | ||
55 | Note that this change in behavior is a good idea in any case, and does not | |
d85c8335 | 56 | create any dependencies on `systemd-homed` or systemd-specific APIs. |
57 | It's simply a change of behavior regarding use of existing APIs, not a suggested hook-up to any new APIs. | |
b05e1220 LP |
58 | |
59 | A display manager which supports this kind of out-of-context screen lock | |
60 | operation needs to inform systemd-homed about this so that systemd-homed knows | |
d85c8335 | 61 | that it is safe to suspend the user's home directory on suspend. |
62 | This is done via the `suspend=` argument to the | |
b05e1220 | 63 | [`pam_systemd_home`](https://www.freedesktop.org/software/systemd/man/pam_systemd_home.html) |
d85c8335 | 64 | PAM module. |
65 | A display manager should hence change its PAM stack configurationto set this parameter to on. | |
66 | `systemd-homed` will not suspend home directories if there's at least one active session of the user that does not support | |
b05e1220 LP |
67 | suspending, as communicated via this parameter. |
68 | ||
69 | ## User Management UIs | |
70 | ||
71 | The rich user/group records `userdb` and `systemd-homed` support carry various | |
d85c8335 | 72 | fields of relevance to UIs that manage the local user database or parts thereof. |
73 | In particular, most of the metadata `accounts-daemon` (also see below) | |
74 | supports is directly available in these JSON records. | |
75 | Hence it makes sense for any user management UI to expose them directly. | |
b05e1220 LP |
76 | |
77 | `systemd-homed` exposes APIs to add, remove and make changes to local users via | |
d85c8335 | 78 | D-Bus, with full [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) hook-up. |
79 | On the command line this is exposed via the `homectl` command. A graphical UI that exposes similar functionality would be | |
b05e1220 LP |
80 | very useful, exposing the various new account settings, and in particular |
81 | providing a stream-lined UI for enrolling new-style authentication tokens such | |
d85c8335 | 82 | as PKCS#11/YubiKey-style devices. |
83 | (Ideally, if the user plugs in an uninitialized YubiKey during operation it might be nice if the Desktop would | |
b05e1220 LP |
84 | automatically ask if a key pair shall be written to it and the local account be |
85 | bound to it, `systemd-homed` provides enough YubiKey/PKCS#11 support to make | |
86 | this a reality today; except that it will not take care of token | |
87 | initialization). | |
88 | ||
d85c8335 | 89 | A strong point of `systemd-homed` is per-user resource management. |
90 | In particular disk space assignments are something that most likely should be | |
b05e1220 | 91 | exposed in a user management UI. Various metadata fields are supplied allowing |
d85c8335 | 92 | exposure of disk space assignment "slider" UI. |
93 | Note however that the file system back-ends of `systemd-homed.service` have different feature sets. | |
94 | Specifically, only btrfs has online file system shrinking support, ext4 only offline file | |
b05e1220 | 95 | system shrinking support, and xfs no shrinking support at all (all three file |
d85c8335 | 96 | systems support online file system growing however). |
97 | This means if the LUKS back-end is used, disk space assignment cannot be instant for logged in users, unless btrfs is used. | |
98 | ||
99 | Note that only `systemd-homed` provides an API for modifying/creating/deleting users. | |
100 | The generic `userdb` subsystem (which might have other back-ends, besides | |
101 | `systemd-homed`, for example LDAP or Windows) exclusively provides a read-only interface. | |
102 | (This is unlikely to change, as the other back-ends might have very | |
103 | different concepts of adding or modifying users, i.e. might not even have any local concept for that at all). | |
104 | This means any user management UI that intends to change (and not just view) user accounts should talk directly to | |
b05e1220 LP |
105 | `systemd-homed` to make use of its features; there's no abstraction available |
106 | to support other back-ends under the same API. | |
107 | ||
d85c8335 | 108 | Unfortunately there's currently no documentation for the `systemd-homed` D-Bus API. |
109 | Consider using the `homectl` sources as guidelines for implementing a user management UI. | |
110 | The JSON user/records are well documented however, see above, | |
b05e1220 LP |
111 | and the D-Bus API provides limited introspection. |
112 | ||
113 | ## Relationship to `accounts-daemon` | |
114 | ||
115 | For a long time `accounts-daemon` has been included in Linux distributions | |
d85c8335 | 116 | providing richer user accounts. |
117 | The functionality of this daemon overlaps in many areas with the functionality of `systemd-homed` or `userdb`, but there are | |
b05e1220 | 118 | systematic differences, which means that `systemd-homed` cannot replace |
d85c8335 | 119 | `accounts-daemon` fully. |
120 | Most importantly: `accounts-daemon` provides "side-car" metadata for *any* type of user account, while `systemd-homed` only | |
121 | provides additional metadata for the users it defines itself. | |
122 | In other words: `accounts-daemon` will augment foreign accounts; `systemd-homed` cannot be used | |
123 | to augment users defined elsewhere, for example in LDAP or as classic `/etc/passwd` records. | |
b05e1220 LP |
124 | |
125 | This probably means that for the time being, a user management UI (or other UI) | |
126 | that wants to support rich user records with compatibility with the status quo | |
127 | ante should probably talk to both `systemd-homed` and `accounts-daemon` at the | |
d85c8335 | 128 | same time, and ignore `accounts-daemon`'s records if `systemd-homed` defines them. |
129 | While I (Lennart) personally believe in the long run `systemd-homed` is | |
b05e1220 LP |
130 | the way to go for rich user records, any UI that wants to manage and support |
131 | rich records for classic records has to support `accounts-daemon` in parallel | |
132 | for the time being. | |
133 | ||
134 | In the short term, it might make sense to also expose the `userdb` provided | |
135 | records via `accounts-daemon`, so that clients of the latter can consume them | |
136 | without changes. However, I think in the long run `accounts-daemon` should | |
137 | probably be removed from the general stack, hence this sounds like a temporary | |
138 | solution only. | |
139 | ||
140 | In case you wonder, there's no automatic mechanism for converting existing | |
d85c8335 | 141 | users registered in `/etc/passwd` or LDAP to users managed by `systemd-homed`. |
142 | There's documentation for doing this manually though, see | |
0d592a5e | 143 | [Converting Existing Users to systemd-homed managed Users](/CONVERTING_TO_HOMED). |
b05e1220 LP |
144 | |
145 | ## Future Additions | |
146 | ||
d85c8335 | 147 | JSON user/group records are extensible, hence we can easily add any additional fields desktop environments require. |
148 | For example, pattern-based authentication is likely very useful on touch-based devices, | |
149 | and the user records should hence learn them natively. | |
150 | Fields for other authentication mechanisms, such as fingerprint authentication should be provided as well, eventually. | |
b05e1220 LP |
151 | |
152 | It is planned to extend the `userdb` Varlink API to support look-ups by partial | |
153 | user name and real name (GECOS) data, so that log-in screens can optionally | |
154 | implement simple complete-as-you-type login screens. | |
155 | ||
156 | It is planned to extend the `systemd-homed` D-Bus API to instantly inform clients | |
157 | about hardware associated with a specific user being plugged in, to which login | |
d85c8335 | 158 | screens can listen in order to initiate authentication. |
159 | Specifically, any YubiKey-like security token plugged in that is associated with a local user | |
b05e1220 LP |
160 | record should initiate authentication for that user, making typing in of the |
161 | username unnecessary. |