docs/USERDB_AND_DESKTOPS.md

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