Debian Codegraph @

upstream/debian-unstable/man5/sysusers.d.5

raw
1 '\" t
2 .TH "SYSUSERS\&.D" "5" "" "systemd 261~rc3" "sysusers.d"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sysusers.d \- Declarative allocation of system users and groups
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/sysusers\&.d/*\&.conf
28 .RE
29 .RS 4
30 /run/sysusers\&.d/*\&.conf
31 .RE
32 .RS 4
33 /usr/local/lib/sysusers\&.d/*\&.conf
34 .RE
35 .RS 4
36 /usr/lib/sysusers\&.d/*\&.conf
37 .RE
38 .sp
39 .nf
40 #Type Name ID GECOS Home directory Shell
41 u user_name uid "User Description" /home/dir /path/to/shell
42 u user_name uid:gid "User Description" /home/dir /path/to/shell
43 u user_name /file/owned/by/user "User Description" /home/dir /path/to/shell
44 g group_name gid
45 g group_name /file/owned/by/group
46 m user_name group_name
47 r \- lowest\-highest
48 .fi
49 .SH "DESCRIPTION"
50 .PP
51 \fBsystemd\-sysusers\fR
52 uses the files from
53 sysusers\&.d
54 directory to create system users and groups and to add users to groups, at package installation or boot time\&. This tool may be used to allocate system users and groups only, it is not useful for creating non\-system (i\&.e\&. regular, "human") users and groups, as it accesses
55 /etc/passwd
56 and
57 /etc/group
58 directly, bypassing any more complex user databases, for example any database involving NIS or LDAP\&.
59 .SH "CONFIGURATION DIRECTORIES AND PRECEDENCE"
60 .PP
61 Each configuration file shall be named in the style of
62 \fIpackage\fR\&.conf
63 or
64 \fIpackage\fR\-\fIpart\fR\&.conf\&. The second variant should be used when it is desirable to make it easy to override just this part of configuration\&.
65 .PP
66 Files in
67 /etc/sysusers\&.d
68 override files with the same name in
69 /usr/lib/sysusers\&.d
70 and
71 /run/sysusers\&.d\&. Files in
72 /run/sysusers\&.d
73 override files with the same name in
74 /usr/lib/sysusers\&.d\&. Packages should install their configuration files in
75 /usr/lib/sysusers\&.d\&. Files in
76 /etc/sysusers\&.d
77 are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same path, the entry in the file with the lexicographically earliest name will be applied\&. All later entries for the same user and group names will be logged as warnings\&.
78 .PP
79 If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to
80 /dev/null
81 in
82 /etc/sysusers\&.d/
83 bearing the same filename\&.
84 .SH "CONFIGURATION FILE FORMAT"
85 .PP
86 The file format is one line per user or group containing name, ID, GECOS field description, home directory, and login shell:
87 .sp
88 .if n \{\
89 .RS 4
90 .\}
91 .nf
92 #Type Name ID GECOS Home directory Shell
93 u! httpd 404 "HTTP User"
94 u! _authd /usr/bin/authd "Authorization user"
95 u! postgres \- "Postgresql Database" /var/lib/pgsql /usr/libexec/postgresdb
96 g input \- \-
97 m _authd input
98 u root 0 "Superuser" /root /bin/zsh
99 r \- 500\-900
100 .fi
101 .if n \{\
102 .RE
103 .\}
104 .PP
105 Empty lines and lines beginning with the
106 "#"
107 character are ignored, and may be used for commenting\&.
108 .SS "Type"
109 .PP
110 The type consists of a single letter\&. The following line types are understood:
111 .PP
112 \fIu\fR
113 .RS 4
114 Create a system user and group of the specified name should they not exist yet\&. The user\*(Aqs primary group will be set to the group bearing the same name unless the ID field specifies it\&. The account will be created disabled, so that logins are not allowed\&.
115 .sp
116 Added in version 215\&.
117 .sp
118 Type
119 \fIu\fR
120 may be suffixed with an exclamation mark ("u!") to create a fully locked account\&. This is recommended, since logins should typically not be allowed for system users\&. With or without the exclamation mark an invalid password is set\&. For
121 "u!", the account is also locked, which makes a difference for non\-password forms of authentication, such as SSH or similar\&.
122 .sp
123 Added in version 257\&.
124 .RE
125 .PP
126 \fIg\fR
127 .RS 4
128 Create a system group of the specified name should it not exist yet\&. Note that
129 \fIu\fR
130 implicitly creates a matching group\&. The group will be created with no password set\&.
131 .sp
132 Added in version 215\&.
133 .RE
134 .PP
135 \fIm\fR
136 .RS 4
137 Add a user to a group\&. If the user or group do not exist yet, they will be implicitly created\&.
138 .sp
139 Added in version 215\&.
140 .RE
141 .PP
142 \fIr\fR
143 .RS 4
144 Add a range of numeric UIDs/GIDs to the pool to allocate new UIDs and GIDs from\&. If no line of this type is specified, the range of UIDs/GIDs is set to some compiled\-in default\&. Note that both UIDs and GIDs are allocated from the same pool, in order to ensure that users and groups of the same name are likely to carry the same numeric UID and GID\&.
145 .sp
146 Added in version 216\&.
147 .RE
148 .SS "Name"
149 .PP
150 The name field specifies the user or group name\&. The specified name must consist only of the characters a\-z, A\-Z, 0\-9,
151 "_"
152 and
153 "\-", except for the first character which must be one of a\-z, A\-Z or
154 "_"
155 (i\&.e\&. numbers and
156 "\-"
157 are not permitted as first character)\&. The user/group name must have at least one character, and at most 31\&.
158 .PP
159 For further details about the syntax of user/group names, see
160 \m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[1]\d\s+2\&.
161 .PP
162 It is strongly recommended to pick user and group names that are unlikely to clash with normal users created by the administrator\&. A good scheme to guarantee this is by prefixing all system and group names with the underscore, and avoiding too generic names\&.
163 .PP
164 For
165 \fIm\fR
166 lines, this field should contain the user name to add to a group\&.
167 .PP
168 For lines of type
169 \fIr\fR, this field should be set to
170 "\-"\&.
171 .SS "ID"
172 .PP
173 For
174 \fIu\fR
175 and
176 \fIg\fR, the numeric 32\-bit UID or GID of the user/group\&. Do not use IDs 65535 or 4294967295, as they have special placeholder meanings\&. Specify
177 "\-"
178 for automatic UID/GID allocation for the user or group (this is strongly recommended unless it is strictly necessary to use a specific UID or GID)\&. Alternatively, specify an absolute path in the file system\&. In this case, the UID/GID is read from the path\*(Aqs owner/group\&. This is useful to create users whose UID/GID match the owners of pre\-existing files (such as SUID or SGID binaries)\&. The syntaxes
179 "\fIuid\fR:\fIgid\fR"
180 and
181 "\fIuid\fR:\fIgroupname\fR"
182 are supported to allow creating users with specific primary groups\&. The given group must be created explicitly, or it must already exist\&. Specifying
183 "\-"
184 for the UID in these syntaxes is also supported\&.
185 .PP
186 For
187 \fIm\fR
188 lines, this field should contain the group name to add to a user to\&.
189 .PP
190 For lines of type
191 \fIr\fR, this field should be set to a UID/GID range in the format
192 "FROM\-TO", where both values are formatted as decimal ASCII numbers\&. Alternatively, a single UID/GID may be specified formatted as decimal ASCII numbers\&.
193 .SS "GECOS"
194 .PP
195 A short, descriptive string for users to be created, enclosed in quotation marks\&. Note that this field may not contain colons\&.
196 .PP
197 Only applies to lines of type
198 \fIu\fR
199 and should otherwise be left unset (or
200 "\-")\&.
201 .SS "Home Directory"
202 .PP
203 The home directory for a new system user\&. If omitted, defaults to the root directory\&.
204 .PP
205 Only applies to lines of type
206 \fIu\fR
207 and should otherwise be left unset (or
208 "\-")\&. It is recommended to omit this, unless software strictly requires a home directory to be set\&.
209 .PP
210 \fBsystemd\-sysusers\fR
211 only sets the home directory record in the user database\&. To actually create the directory, consider adding a corresponding
212 \fBtmpfiles.d\fR(5)
213 fragment\&.
214 .SS "Shell"
215 .PP
216 The login shell of the user\&. If not specified, this will be set to
217 /usr/sbin/nologin, except if the UID of the user is 0, in which case
218 /bin/sh
219 will be used\&.
220 .PP
221 Only applies to lines of type
222 \fIu\fR
223 and should otherwise be left unset (or
224 "\-")\&. It is recommended to omit this, unless a shell different
225 /usr/sbin/nologin
226 must be used\&.
227 .SH "SPECIFIERS"
228 .PP
229 Specifiers can be used in the
230 "Name",
231 "ID",
232 "GECOS",
233 "Home directory", and
234 "Shell"
235 fields\&. An unknown or unresolvable specifier is treated as invalid configuration\&. The following expansions are understood:
236 .sp
237 .it 1 an-trap
238 .nr an-no-space-flag 1
239 .nr an-break-flag 1
240 .br
241 .B Table\ \&1.\ \&Specifiers available
242 .TS
243 allbox tab(:);
244 lB lB lB.
245 T{
246 Specifier
247 T}:T{
248 Meaning
249 T}:T{
250 Details
251 T}
252 .T&
253 l l l
254 l l l
255 l l l
256 l l l
257 l l l
258 l l l
259 l l l
260 l l l
261 l l l
262 l l l
263 l l l
264 l l l
265 l l l
266 l l l
267 l l l
268 l l l.
269 T{
270 "%a"
271 T}:T{
272 Architecture
273 T}:T{
274 A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&.
275 T}
276 T{
277 "%A"
278 T}:T{
279 Operating system image version
280 T}:T{
281 The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
282 T}
283 T{
284 "%b"
285 T}:T{
286 Boot ID
287 T}:T{
288 The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&.
289 T}
290 T{
291 "%B"
292 T}:T{
293 Operating system build ID
294 T}:T{
295 The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
296 T}
297 T{
298 "%H"
299 T}:T{
300 Host name
301 T}:T{
302 The hostname of the running system\&.
303 T}
304 T{
305 "%l"
306 T}:T{
307 Short host name
308 T}:T{
309 The hostname of the running system, truncated at the first dot to remove any domain component\&.
310 T}
311 T{
312 "%m"
313 T}:T{
314 Machine ID
315 T}:T{
316 The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&.
317 T}
318 T{
319 "%M"
320 T}:T{
321 Operating system image identifier
322 T}:T{
323 The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
324 T}
325 T{
326 "%o"
327 T}:T{
328 Operating system ID
329 T}:T{
330 The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&.
331 T}
332 T{
333 "%q"
334 T}:T{
335 Pretty host name
336 T}:T{
337 The pretty hostname of the running system, as read from the \fIPRETTY_HOSTNAME=\fR field of /etc/machine\-info\&. If not set, resolves to the short hostname\&. See \fBmachine-info\fR(5) for more information\&.
338 T}
339 T{
340 "%T"
341 T}:T{
342 Directory for temporary files
343 T}:T{
344 This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
345 T}
346 T{
347 "%v"
348 T}:T{
349 Kernel release
350 T}:T{
351 Identical to \fBuname \-r\fR output\&.
352 T}
353 T{
354 "%V"
355 T}:T{
356 Directory for larger and persistent temporary files
357 T}:T{
358 This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
359 T}
360 T{
361 "%w"
362 T}:T{
363 Operating system version ID
364 T}:T{
365 The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
366 T}
367 T{
368 "%W"
369 T}:T{
370 Operating system variant ID
371 T}:T{
372 The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
373 T}
374 T{
375 "%%"
376 T}:T{
377 Single percent sign
378 T}:T{
379 Use "%%" in place of "%" to specify a single percent sign\&.
380 T}
381 .TE
382 .sp 1
383 .SH "IDEMPOTENCE"
384 .PP
385 Note that
386 \fBsystemd\-sysusers\fR
387 will do nothing if the specified users or groups already exist or the users are members of specified groups, so normally there is no reason to override
388 sysusers\&.d
389 vendor configuration, except to block certain users or groups from being created\&.
390 .SH "SEE ALSO"
391 .PP
392 \fBsystemd\fR(1), \fBsystemd-sysusers\fR(8)
393 .SH "NOTES"
394 .IP " 1." 4
395 User/Group Name Syntax
396 .RS 4
397 \%https://systemd.io/USER_NAMES
398 .RE