]>
Commit | Line | Data |
---|---|---|
4006b98d AV |
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 | |
0d592a5e | 11 | otherwise be stored in [JSON User Records](/USER_RECORD). For instance, |
4006b98d AV |
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 | |
1b466c09 AV |
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 | |
4006b98d AV |
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. |