]>
Commit | Line | Data |
---|---|---|
c3e270f4 FB |
1 | --- |
2 | title: Users, Groups, UIDs and GIDs on `systemd` Systems | |
3 | --- | |
4 | ||
c1d3483d | 5 | # Users, Groups, UIDs and GIDs on `systemd` Systems |
39972553 LP |
6 | |
7 | Here's a summary of the requirements `systemd` (and Linux) make on UID/GID | |
8 | assignments and their ranges. | |
9 | ||
10 | Note that while in theory UIDs and GIDs are orthogonal concepts they really | |
11 | aren't IRL. With that in mind, when we discuss UIDs below it should be assumed | |
12 | that whatever we say about UIDs applies to GIDs in mostly the same way, and all | |
13 | the special assignments and ranges for UIDs always have mostly the same | |
14 | validity for GIDs too. | |
15 | ||
16 | ## Special Linux UIDs | |
17 | ||
18 | In theory, the range of the C type `uid_t` is 32bit wide on Linux, | |
19 | i.e. 0…4294967295. However, four UIDs are special on Linux: | |
20 | ||
21 | 1. 0 → The `root` super-user | |
22 | ||
23 | 2. 65534 → The `nobody` UID, also called the "overflow" UID or similar. It's | |
2e276b1d LP |
24 | where various subsystems map unmappable users to, for example file systems |
25 | only supporting 16bit UIDs, NFS or user namespacing. (The latter can be | |
26 | changed with a sysctl during runtime, but that's not supported on | |
27 | `systemd`. If you do change it you void your warranty.) Because Fedora is a | |
28 | bit confused the `nobody` user is called `nfsnobody` there (and they have a | |
29 | different `nobody` user at UID 99). I hope this will be corrected eventually | |
30 | though. (Also, some distributions call the `nobody` group `nogroup`. I wish | |
31 | they didn't.) | |
39972553 LP |
32 | |
33 | 3. 4294967295, aka "32bit `(uid_t) -1`" → This UID is not a valid user ID, as | |
9e4b8893 LP |
34 | `setresuid()`, `chown()` and friends treat -1 as a special request to not |
35 | change the UID of the process/file. This UID is hence not available for | |
36 | assignment to users in the user database. | |
39972553 | 37 | |
9e4b8893 LP |
38 | 4. 65535, aka "16bit `(uid_t) -1`" → Before Linux kernel 2.4 `uid_t` used to be |
39 | 16bit, and programs compiled for that would hence assume that `(uid_t) -1` | |
40 | is 65535. This UID is hence not usable either. | |
39972553 LP |
41 | |
42 | The `nss-systemd` glibc NSS module will synthesize user database records for | |
43 | the UIDs 0 and 65534 if the system user database doesn't list them. This means | |
44 | that any system where this module is enabled works to some minimal level | |
45 | without `/etc/passwd`. | |
46 | ||
47 | ## Special Distribution UID ranges | |
48 | ||
49 | Distributions generally split the available UID range in two: | |
50 | ||
51 | 1. 1…999 → System users. These are users that do not map to actual "human" | |
52 | users, but are used as security identities for system daemons, to implement | |
53 | privilege separation and run system daemons with minimal privileges. | |
54 | ||
55 | 2. 1000…65533 and 65536…4294967294 → Everything else, i.e. regular (human) users. | |
56 | ||
57 | Note that most distributions allow changing the boundary between system and | |
58 | regular users, even during runtime as user configuration. Moreover, some older | |
59 | systems placed the boundary at 499/500, or even 99/100. In `systemd`, the | |
60 | boundary is configurable only during compilation time, as this should be a | |
61 | decision for distribution builders, not for users. Moreover, we strongly | |
62 | discourage downstreams to change the boundary from the upstream default of | |
63 | 999/1000. | |
64 | ||
65 | Also note that programs such as `adduser` tend to allocate from a subset of the | |
66 | available regular user range only, usually 1000..60000. And it's also usually | |
67 | user-configurable, too. | |
68 | ||
69 | Note that systemd requires that system users and groups are resolvable without | |
70 | networking available — a requirement that is not made for regular users. This | |
71 | means regular users may be stored in remote LDAP or NIS databases, but system | |
72 | users may not (except when there's a consistent local cache kept, that is | |
73 | available during earliest boot, including in the initial RAM disk). | |
74 | ||
75 | ## Special `systemd` GIDs | |
76 | ||
77 | `systemd` defines no special UIDs beyond what Linux already defines (see | |
78 | above). However, it does define some special group/GID assignments, which are | |
79 | primarily used for `systemd-udevd`'s device management. The precise list of the | |
80 | currently defined groups is found in this `sysusers.d` snippet: | |
81 | [basic.conf](https://raw.githubusercontent.com/systemd/systemd/master/sysusers.d/basic.conf.in) | |
82 | ||
83 | It's strongly recommended that downstream distributions include these groups in | |
84 | their default group databases. | |
85 | ||
86 | Note that the actual GID numbers assigned to these groups do not have to be | |
87 | constant beyond a specific system. There's one exception however: the `tty` | |
88 | group must have the GID 5. That's because it must be encoded in the `devpts` | |
89 | mount parameters during earliest boot, at a time where NSS lookups are not | |
90 | possible. (Note that the actual GID can be changed during `systemd` build time, | |
91 | but downstreams are strongly advised against doing that.) | |
92 | ||
93 | ## Special `systemd` UID ranges | |
94 | ||
95 | `systemd` defines a number of special UID ranges: | |
96 | ||
97 | 1. 61184…65519 → UIDs for dynamic users are allocated from this range (see the | |
98 | `DynamicUser=` documentation in | |
99 | [`systemd.exec(5)`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html)). This | |
100 | range has been chosen so that it is below the 16bit boundary (i.e. below | |
101 | 65535), in order to provide compatibility with container environments that | |
102 | assign a 64K range of UIDs to containers using user namespacing. This range | |
103 | is above the 60000 boundary, so that its allocations are unlikely to be | |
104 | affected by `adduser` allocations (see above). And we leave some room | |
105 | upwards for other purposes. (And if you wonder why precisely these numbers: | |
106 | if you write them in hexadecimal, they might make more sense: 0xEF00 and | |
107 | 0xFFEF). The `nss-systemd` module will synthesize user records implicitly | |
108 | for all currently allocated dynamic users from this range. Thus, NSS-based | |
109 | user record resolving works correctly without those users being in | |
110 | `/etc/passwd`. | |
111 | ||
112 | 2. 524288…1879048191 → UID range for `systemd-nspawn`'s automatic allocation of | |
113 | per-container UID ranges. When the `--private-users=pick` switch is used (or | |
114 | `-U`) then it will automatically find a so far unused 16bit subrange of this | |
115 | range and assign it to the container. The range is picked so that the upper | |
116 | 16bit of the 32bit UIDs are constant for all users of the container, while | |
117 | the lower 16bit directly encode the 65536 UIDs assigned to the | |
118 | container. This mode of allocation means that the upper 16bit of any UID | |
119 | assigned to a container are kind of a "container ID", while the lower 16bit | |
120 | directly expose the container's own UID numbers. If you wonder why precisely | |
121 | these numbers, consider them in hexadecimal: 0x00080000…0x6FFFFFFF. This | |
122 | range is above the 16bit boundary. Moreover it's below the 31bit boundary, | |
123 | as some broken code (specifically: the kernel's `devpts` file system) | |
124 | erroneously considers UIDs signed integers, and hence can't deal with values | |
125 | above 2^31. The `nss-mymachines` glibc NSS module will synthesize user | |
126 | database records for all UIDs assigned to a running container from this | |
127 | range. | |
128 | ||
129 | Note for both allocation ranges: when an UID allocation takes place NSS is | |
130 | checked for collisions first, and a different UID is picked if an entry is | |
131 | found. Thus, the user database is used as synchronization mechanism to ensure | |
132 | exclusive ownership of UIDs and UID ranges. To ensure compatibility with other | |
133 | subsystems allocating from the same ranges it is hence essential that they | |
134 | ensure that whatever they pick shows up in the user/group databases, either by | |
135 | providing an NSS module, or by adding entries directly to `/etc/passwd` and | |
136 | `/etc/group`. For performance reasons, do note that `systemd-nspawn` will only | |
137 | do an NSS check for the first UID of the range it allocates, not all 65536 of | |
138 | them. Also note that while the allocation logic is operating, the glibc | |
139 | `lckpwdf()` user database lock is taken, in order to make this logic race-free. | |
140 | ||
141 | ## Figuring out the system's UID boundaries | |
142 | ||
143 | The most important boundaries of the local system may be queried with | |
144 | `pkg-config`: | |
145 | ||
146 | ``` | |
147 | $ pkg-config --variable=systemuidmax systemd | |
148 | 999 | |
149 | $ pkg-config --variable=dynamicuidmin systemd | |
150 | 61184 | |
151 | $ pkg-config --variable=dynamicuidmax systemd | |
152 | 65519 | |
153 | $ pkg-config --variable=containeruidbasemin systemd | |
154 | 524288 | |
155 | $ pkg-config --variable=containeruidbasemax systemd | |
156 | 1878982656 | |
157 | ``` | |
158 | ||
159 | (Note that the latter encodes the maximum UID *base* `systemd-nspawn` might | |
160 | pick — given that 64K UIDs are assigned to each container according to this | |
161 | allocation logic, the maximum UID used for this range is hence | |
162 | 1878982656+65535=1879048191.) | |
163 | ||
164 | Note that systemd does not make any of these values runtime-configurable. All | |
165 | these boundaries are chosen during build time. That said, the system UID/GID | |
166 | boundary is traditionally configured in /etc/login.defs, though systemd won't | |
167 | look there during runtime. | |
168 | ||
169 | ## Considerations for container managers | |
170 | ||
171 | If you hack on a container manager, and wonder how and how many UIDs best to | |
172 | assign to your containers, here are a few recommendations: | |
173 | ||
174 | 1. Definitely, don't assign less than 65536 UIDs/GIDs. After all the `nobody` | |
175 | user has magic properties, and hence should be available in your container, and | |
176 | given that it's assigned the UID 65534, you should really cover the full 16bit | |
177 | range in your container. Note that systemd will — as mentioned — synthesize | |
178 | user records for the `nobody` user, and assumes its availability in various | |
179 | other parts of its codebase, too, hence assigning fewer users means you lose | |
180 | compatibility with running systemd code inside your container. And most likely | |
181 | other packages make similar restrictions. | |
182 | ||
183 | 2. While it's fine to assign more than 65536 UIDs/GIDs to a container, there's | |
184 | most likely not much value in doing so, as Linux distributions won't use the | |
185 | higher ranges by default (as mentioned neither `adduser` nor `systemd`'s | |
186 | dynamic user concept allocate from above the 16bit range). Unless you actively | |
187 | care for nested containers, it's hence probably a good idea to allocate exactly | |
188 | 65536 UIDs per container, and neither less nor more. A pretty side-effect is | |
189 | that by doing so, you expose the same number of UIDs per container as Linux 2.2 | |
190 | supported for the whole system, back in the days. | |
191 | ||
192 | 3. Consider allocating UID ranges for containers so that the first UID you | |
193 | assign has the lower 16bits all set to zero. That way, the upper 16bits become | |
194 | a container ID of some kind, while the lower 16bits directly encode the | |
195 | internal container UID. This is the way `systemd-nspawn` allocates UID ranges | |
e5988600 | 196 | (see above). Following this allocation logic ensures best compatibility with |
39972553 LP |
197 | `systemd-nspawn` and all other container managers following the scheme, as it |
198 | is sufficient then to check NSS for the first UID you pick regarding conflicts, | |
199 | as that's what they do, too. Moreover, it makes `chown()`ing container file | |
200 | system trees nicely robust to interruptions: as the external UID encodes the | |
201 | internal UID in a fixed way, it's very easy to adjust the container's base UID | |
202 | without the need to know the original base UID: to change the container base, | |
203 | just mask away the upper 16bit, and insert the upper 16bit of the new container | |
204 | base instead. Here are the easy conversions to derive the internal UID, the | |
205 | external UID, and the container base UID from each other: | |
206 | ||
207 | ``` | |
208 | INTERNAL_UID = EXTERNAL_UID & 0x0000FFFF | |
209 | CONTAINER_BASE_UID = EXTERNAL_UID & 0xFFFF0000 | |
210 | EXTERNAL_UID = INTERNAL_UID | CONTAINER_BASE_UID | |
211 | ``` | |
212 | ||
213 | 4. When picking a UID range for containers, make sure to check NSS first, with | |
214 | a simple `getpwuid()` call: if there's already a user record for the first UID | |
215 | you want to pick, then it's already in use: pick a different one. Wrap that | |
216 | call in a `lckpwdf()` + `ulckpwdf()` pair, to make allocation | |
217 | race-free. Provide an NSS module that makes all UIDs you end up taking show up | |
218 | in the user database, and make sure that the NSS module returns up-to-date | |
219 | information before you release the lock, so that other system components can | |
220 | safely use the NSS user database as allocation check, too. Note that if you | |
221 | follow this scheme no changes to `/etc/passwd` need to be made, thus minimizing | |
222 | the artifacts the container manager persistently leaves in the system. | |
223 | ||
224 | ## Summary | |
225 | ||
226 | | UID/GID | Purpose | Defined By | Listed in | | |
227 | |-----------------------|-----------------------|---------------|-------------------------------| | |
228 | | 0 | `root` user | Linux | `/etc/passwd` + `nss-systemd` | | |
229 | | 1…4 | System users | Distributions | `/etc/passwd` | | |
230 | | 5 | `tty` group | `systemd` | `/etc/passwd` | | |
231 | | 6…999 | System users | Distributions | `/etc/passwd` | | |
232 | | 1000…60000 | Regular users | Distributions | `/etc/passwd` + LDAP/NIS/… | | |
233 | | 60001…61183 | Unused | | | | |
234 | | 61184…65519 | Dynamic service users | `systemd` | `nss-systemd` | | |
235 | | 65520…65533 | Unused | | | | |
236 | | 65534 | `nobody` user | Linux | `/etc/passwd` + `nss-systemd` | | |
237 | | 65535 | 16bit `(uid_t) -1` | Linux | | | |
238 | | 65536…524287 | Unused | | | | |
239 | | 524288…1879048191 | Container UID ranges | `systemd` | `nss-mymachines` | | |
a305eda3 LP |
240 | | 1879048191…2147483647 | Unused | | | |
241 | | 2147483648…4294967294 | HIC SVNT LEONES | | | | |
39972553 LP |
242 | | 4294967295 | 32bit `(uid_t) -1` | Linux | | |
243 | ||
244 | Note that "Unused" in the table above doesn't meant that these ranges are | |
245 | really unused. It just means that these ranges have no well-established | |
246 | pre-defined purposes between Linux, generic low-level distributions and | |
247 | `systemd`. There might very well be other packages that allocate from these | |
248 | ranges. | |
bf613f7a | 249 | |
a305eda3 LP |
250 | Note that the range 2147483648…4294967294 (i.e. 2^31…2^32-2) should be handled |
251 | with care. Various programs (including kernel file systems, see `devpts`) have | |
252 | trouble with UIDs outside of the signed 32bit range, i.e any UIDs equal to or | |
253 | above 2147483648. It is thus strongly recommended to stay away from this range | |
254 | in order to avoid complications. This range should be considered reserved for | |
255 | future, special purposes. | |
256 | ||
bf613f7a LP |
257 | ## Notes on resolvability of user and group names |
258 | ||
259 | User names, UIDs, group names and GIDs don't have to be resolvable using NSS | |
260 | (i.e. getpwuid() and getpwnam() and friends) all the time. However, systemd | |
261 | makes the following requirements: | |
262 | ||
263 | System users generally have to be resolvable during early boot already. This | |
264 | means they should not be provided by any networked service (as those usually | |
265 | become available during late boot only), except if a local cache is kept that | |
266 | makes them available during early boot too (i.e. before networking is | |
267 | up). Specifically, system users need to be resolvable at least before | |
268 | `systemd-udevd.service` and `systemd-tmpfiles.service` are started, as both | |
269 | need to resolve system users — but note that there might be more services | |
270 | requiring full resolvability of system users than just these two. | |
271 | ||
272 | Regular users do not need to be resolvable during early boot, it is sufficient | |
273 | if they become resolvable during late boot. Specifically, regular users need to | |
274 | be resolvable at the point in time the `nss-user-lookup.target` unit is | |
275 | reached. This target unit is generally used as synchronization point between | |
276 | providers of the user database and consumers of it. Services that require that | |
277 | the user database is fully available (for example, the login service | |
278 | `systemd-logind.service`) are ordered *after* it, while services that provide | |
279 | parts of the user database (for example an LDAP user database client) are | |
280 | ordered *before* it. Note that `nss-user-lookup.target` is a *passive* unit: in | |
281 | order to minimize synchronization points on systems that don't need it the unit | |
282 | is pulled into the initial transaction only if there's at least one service | |
283 | that really needs it, and that means only if there's a service providing the | |
284 | local user database somehow through IPC or suchlike. Or in other words: if you | |
285 | hack on some networked user database project, then make sure you order your | |
286 | service `Before=nss-user-lookup.target` and that you pull it in with | |
287 | `Wants=nss-user-lookup.target`. However, if you hack on some project that needs | |
288 | the user database to be up in full, then order your service | |
289 | `After=nss-user-lookup.target`, but do *not* pull it in via a `Wants=` | |
290 | dependency. |