docs/USER_RECORD_BLOB_DIRS.md

   1 ---
   2 title: User Record Blob Directories
   3 category: Users, Groups and Home Directories
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # User Record Blob Directories
   9
  10 The blob directories are for storing binary or unstructured data that would
  11 otherwise be stored in [JSON User Records](/USER_RECORD). For instance,
  12 this includes image files such as the user's avatar picture. This data,
  13 like most of the user record, will be made publicly available to the
  14 system.
  15
  16 The JSON User Record specifies the location of the blob directory via the
  17 `blobDirectory` field. If the field is unset, then there is no blob directory
  18 and thus no blob files to look for.  Note that `blobDirectory` can exist in the
  19 `regular`, `perMachine`, and `status` sections. The blob directory is completely
  20 owned and managed by the service that owns the rest of the user record (as
  21 specified in the `service` field).
  22
  23 For consistency, blob directories have certain restrictions placed on them
  24 that may be enforced by their owning service. Services implementing blob
  25 directories are free to ignore these restrictions, but software that wishes
  26 to store some of its data in blob directories must adhere to the following:
  27
  28 * The directory only contains regular files; no sub-directories or any special
  29   files are permitted.
  30
  31 * Filenames inside of the directory are restricted to
  32   [URI Unreserved Characters](https://www.rfc-editor.org/rfc/rfc3986#section-2.3)
  33   (alphanumeric, `-`, `.`, `_`, and `~`), and must not start with a dot.
  34
  35 * The total size of the directory should not exceed 64M.
  36
  37 * File ownership and permissions will not be preserved. The service may reset
  38   the mode of the files to 0644, and ownership to whatever it wishes.
  39
  40 * Timestamps, xattrs, ACLs, or any other metadata on the files will not be preserved.
  41
  42 Services are required to ensure that the directory and its contents are
  43 world-readable. Aside from this requirement, services are free to provide
  44 the directory and its contents in whatever manner they like, including but
  45 not limited to synthesizing the directory at runtime using external data
  46 or keeping around multiple copies. Thus, only the service that owns the
  47 directory is permitted to write to this directory in any way: for all
  48 other software the directory is strictly read-only.
  49
  50 Services may choose to provide some way to change user records. Services
  51 that provide this functionality should support changing the blob directory also.
  52 Care must be taken to avoid exposing sensitive data to malicious clients. This
  53 includes but is not limited to disallowing symlinks and using file descriptors
  54 (excluding O_PATH!) to ensure that the client actually has permission to access
  55 the data it wants the service to publish.
  56
  57 Services that make use of the `signature` section in the records they manage
  58 should enforce `blobManifest`. This ensures that the contents of the blob directory
  59 are part of the cryptographically signed data.
  60
  61 ## Known Files
  62
  63 Various files in the blob directories have known semantic meanings.
  64 The following files are currently defined:
  65
  66 `avatar` → An image file that should be used as the user's avatar picture.
  67 The exact file type and resolution of this image are left unspecified,
  68 and requirements will depend on the capabilities of the components that will
  69 display it. However, we suggest the use of commonly-supported picture formats
  70 (i.e. PNG or JPEG) and a resolution of 512 x 512. This image should not have any
  71 transparency. If missing, of an incompatible file type, or otherwise unusable,
  72 then the user does not have a profile picture and a default will be used instead.
  73
  74 `login-background` → An image file that will be used as the user's background on the
  75 login screen (i.e. in GDM). The exact file type and resolution are left unspecified
  76 and are ultimately up to the components that will render this background image. This
  77 image should not have any transparency. If missing, of an incompatible file type, or
  78 otherwise unusable, a fallback background of some kind will be used.
  79
  80 ## Extending These Directories
  81
  82 Like JSON User Records, the blob directories are intended to be extendable for
  83 various applications. In general, subsystems are free to introduce their own
  84 files, as long as:
  85
  86 * The requirements listed above are all met.
  87
  88 * Care is taken to avoid namespace clashes. Please prefix your file names with
  89   a short identifier of your project to avoid ambiguities and incompatibilities.
  90
  91 * This specification is supposed to be a living specification. If you need
  92   additional files, please consider defining them upstream for inclusion in
  93   this specification. If they are reasonably universally useful, it would be
  94   best to list them here.
  95
  96 ## Examples
  97
  98 The simplest way to define a user record is via the drop-in directories (as documented
  99 in [nss-systemd(8)](https://www.freedesktop.org/software/systemd/man/latest/nss-systemd.html)
 100 and [systemd-userdb.service(8)](https://www.freedesktop.org/software/systemd/man/latest/systemd-userdbd.service.html)).
 101 Such records can have blob directories by simply referring to some persistent
 102 place from the record, possibly next to the record itself. For instance,
 103 `/etc/userdb/grobie.user` may contain:
 104
 105 ```json
 106 {
 107         "userName": "grobie",
 108         "disposition": "regular",
 109         "homeDirectory": "/home/grobie",
 110         "blobDirectory": "/etc/userdb/grobie.blob/",
 111 }
 112 ```
 113
 114 In this case, `/etc/userdb/grobie.blob/` will be the blob directory for the
 115 user `grobie`.
 116
 117 A more complicated case is a home directory managed by `systemd-homed.service`.
 118 When it manages a home directory, it maintains and synchronizes two separate
 119 blob directories: one belonging to the system in `/var/cache/systemd/home`,
 120 and another belonging to the home directory in `~/.identity-blob`. The system
 121 blob directory ensures that the blob data is available while the home directory
 122 is encrypted or otherwise unavailable, and the home blob directory ensures that
 123 the user account remains portable between systems. To implement this behavior,
 124 `systemd-homed.service` always sets `blobDirectory` to the system blob directory
 125 in the `binding` section of the user record (i.e. this is _not_ persisted to
 126 `~/.identity`). If some client tries to update the user record with a new blob
 127 directory, `systemd-homed.service` will copy the updated blob directory into both
 128 the system and home blob locations.