Debian Codegraph @

upstream/debian-unstable/man7/systemd.system-credentials.7

raw
1 '\" t
2 .TH "SYSTEMD\&.SYSTEM\-CREDENTIALS" "7" "" "systemd 261~rc3" "systemd.system-credentials"
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 systemd.system-credentials \- System Credentials
24 .SH "DESCRIPTION"
25 .PP
26 \m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[1]\d\s+2
27 are data objects that may be passed into booted systems or system services as they are invoked\&. They can be acquired from various external sources, and propagated into the system and from there into system services\&. Credentials may optionally be encrypted with a machine\-specific key and/or locked to the local TPM2 device, and are only decrypted when the consuming service is invoked\&.
28 .PP
29 System credentials may be used to provision and configure various aspects of the system\&. Depending on the consuming component credentials are only used on initial invocations or are needed for all invocations\&.
30 .PP
31 Credentials may be used for any kind of data, binary or text, and may carry passwords, secrets, certificates, cryptographic key material, identity information, configuration, and more\&.
32 .SH "WELL KNOWN SYSTEM CREDENTIALS"
33 .PP
34 \fIfirstboot\&.keymap\fR
35 .RS 4
36 The console key mapping to set (e\&.g\&.
37 "de")\&. Read by
38 \fBsystemd-firstboot\fR(1), and only honoured if no console keymap has been configured before\&.
39 .sp
40 Added in version 252\&.
41 .RE
42 .PP
43 \fIfirstboot\&.hostname\fR
44 .RS 4
45 This credential specifies the static system hostname to set during first boot\&. The user will not be prompted for the hostname\&. Note that this controls the static hostname, not the transient hostname, and only has an effect on first boot, unlike
46 \fIsystem\&.hostname\fR
47 (see below)\&. Read by
48 \fBsystemd-firstboot\fR(1)
49 and only honoured if no static hostname has been configured before\&.
50 .sp
51 Added in version 261\&.
52 .RE
53 .PP
54 \fIfirstboot\&.locale\fR, \fIfirstboot\&.locale\-messages\fR
55 .RS 4
56 The system locale to set (e\&.g\&.
57 "de_DE\&.UTF\-8")\&. Read by
58 \fBsystemd-firstboot\fR(1), and only honoured if no locale has been configured before\&.
59 \fIfirstboot\&.locale\fR
60 sets
61 "LANG", while
62 \fIfirstboot\&.locale\-message\fR
63 sets
64 "LC_MESSAGES"\&.
65 .sp
66 Added in version 252\&.
67 .RE
68 .PP
69 \fIfirstboot\&.timezone\fR
70 .RS 4
71 The system timezone to set (e\&.g\&.
72 "Europe/Berlin")\&. Read by
73 \fBsystemd-firstboot\fR(1), and only honoured if no system timezone has been configured before\&.
74 .sp
75 Added in version 252\&.
76 .RE
77 .PP
78 \fIfirstboot\&.machine\-tags\fR
79 .RS 4
80 The machine tags to set, as a colon\-separated list (e\&.g\&.
81 "webserver:frontend:berlin")\&. Read by
82 \fBsystemd-firstboot\fR(1), and only honoured if
83 /etc/machine\-info
84 has not been configured before\&. Written into the
85 \fITAGS=\fR
86 field of that file, see
87 \fBmachine-info\fR(5)
88 for details\&.
89 .sp
90 Added in version 261\&.
91 .RE
92 .PP
93 \fIlogin\&.issue\fR
94 .RS 4
95 The data of this credential is written to
96 /etc/issue\&.d/50\-provision\&.conf, if the file does not exist yet\&.
97 \fBagetty\fR(8)
98 reads this file and shows its contents at the login prompt of terminal logins\&. See
99 \fBissue\fR(5)
100 for details\&.
101 .sp
102 Consumed by
103 /usr/lib/tmpfiles\&.d/provision\&.conf, see
104 \fBtmpfiles.d\fR(5)\&.
105 .sp
106 Added in version 252\&.
107 .RE
108 .PP
109 \fIlogin\&.motd\fR
110 .RS 4
111 The data of this credential is written to
112 /etc/motd\&.d/50\-provision\&.conf, if the file does not exist yet\&.
113 \fBpam_motd\fR(8)
114 reads this file and shows its contents as "message of the day" during terminal logins\&. See
115 \fBmotd\fR(5)
116 for details\&.
117 .sp
118 Consumed by
119 /usr/lib/tmpfiles\&.d/provision\&.conf, see
120 \fBtmpfiles.d\fR(5)\&.
121 .sp
122 Added in version 252\&.
123 .RE
124 .PP
125 \fInetwork\&.hosts\fR
126 .RS 4
127 The data of this credential is written to
128 /etc/hosts, if the file does not exist yet\&. See
129 \fBhosts\fR(5)
130 for details\&.
131 .sp
132 Consumed by
133 /usr/lib/tmpfiles\&.d/provision\&.conf, see
134 \fBtmpfiles.d\fR(5)\&.
135 .sp
136 Added in version 252\&.
137 .RE
138 .PP
139 \fInetwork\&.dns\fR, \fInetwork\&.search_domains\fR
140 .RS 4
141 DNS server information and search domains\&. Read by
142 \fBsystemd-resolved.service\fR(8)\&.
143 .sp
144 Added in version 253\&.
145 .RE
146 .PP
147 \fInetwork\&.conf\&.*\fR, \fInetwork\&.link\&.*\fR, \fInetwork\&.netdev\&.*\fR, \fInetwork\&.network\&.*\fR
148 .RS 4
149 Configures network devices\&. Read by
150 \fBsystemd-network-generator.service\fR(8)\&. These credentials should contain valid
151 \fBnetworkd.conf\fR(5),
152 \fBsystemd.link\fR(5),
153 \fBsystemd.netdev\fR(5),
154 \fBsystemd.network\fR(5)
155 configuration data\&. From each matching credential a separate file is created\&. Example: the contents of a credential
156 network\&.link\&.50\-foobar
157 will be copied into a file
158 50\-foobar\&.link\&.
159 .sp
160 Note that the resulting files are created world\-readable, it is hence recommended to not include secrets in these credentials, but supply them via separate credentials directly to
161 systemd\-networkd\&.service, e\&.g\&.
162 \fInetwork\&.wireguard\&.*\fR
163 as described below\&.
164 .sp
165 Added in version 256\&.
166 .RE
167 .PP
168 \fInetwork\&.wireguard\&.*\fR
169 .RS 4
170 Configures secrets for WireGuard netdevs\&. Read by
171 \fBsystemd-networkd.service\fR(8)\&. For more information, refer to the
172 \fB[WireGuard]\fR
173 section of
174 \fBsystemd.netdev\fR(5)\&.
175 .sp
176 Added in version 256\&.
177 .RE
178 .PP
179 \fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR
180 .RS 4
181 May contain the password (either in UNIX hashed format, or in plaintext) for the root users\&. Read by both
182 \fBsystemd-firstboot\fR(1)
183 and
184 \fBsystemd-sysusers\fR(8), and only honoured if no root password has been configured before\&.
185 .sp
186 Added in version 252\&.
187 .RE
188 .PP
189 \fIpasswd\&.shell\&.root\fR
190 .RS 4
191 The path to the shell program (e\&.g\&.
192 "/bin/bash") for the root user\&. Read by both
193 \fBsystemd-firstboot\fR(1)
194 and
195 \fBsystemd-sysusers\fR(8), and only honoured if no root shell has been configured before\&.
196 .sp
197 Added in version 252\&.
198 .RE
199 .PP
200 \fIssh\&.ephemeral\-authorized_keys\-all\fR
201 .RS 4
202 Provides additional public keys, given in the customary
203 authorized_keys
204 format, for all users, for incoming connections via the generated
205 \fBAF_VSOCK\fR
206 and
207 \fBAF_UNIX\fR
208 socket units\&.
209 .sp
210 The intended use of this is for a host system (in either VM or container configurations) to generate a keypair and inject the public key into the guest, using the private key to connect to any user account on the guest via ssh, without further authentication\&.
211 .sp
212 Consumed by
213 \fBsystemd-ssh-generator\fR(8)\&.
214 .sp
215 Added in version 256\&.
216 .RE
217 .PP
218 \fIssh\&.authorized_keys\&.root\fR
219 .RS 4
220 The data of this credential is written to
221 /root/\&.ssh/authorized_keys, if the file does not exist yet\&. This allows provisioning SSH access for the system\*(Aqs root user\&.
222 .sp
223 Consumed by
224 /usr/lib/tmpfiles\&.d/provision\&.conf, see
225 \fBtmpfiles.d\fR(5)\&.
226 .sp
227 Added in version 252\&.
228 .RE
229 .PP
230 \fIssh\&.listen\fR
231 .RS 4
232 May be used to configure SSH sockets the system shall be reachable on\&. See
233 \fBsystemd-ssh-generator\fR(8)
234 for details\&.
235 .sp
236 Added in version 256\&.
237 .RE
238 .PP
239 \fIsysusers\&.extra\fR
240 .RS 4
241 Additional
242 \fBsysusers.d\fR(5)
243 lines to process during boot\&.
244 .sp
245 Added in version 252\&.
246 .RE
247 .PP
248 \fIsysctl\&.extra\fR
249 .RS 4
250 Additional
251 \fBsysctl.d\fR(5)
252 lines to process during boot\&.
253 .sp
254 Added in version 252\&.
255 .RE
256 .PP
257 \fItmpfiles\&.extra\fR
258 .RS 4
259 Additional
260 \fBtmpfiles.d\fR(5)
261 lines to process during boot\&.
262 .sp
263 Added in version 252\&.
264 .RE
265 .PP
266 \fIfstab\&.extra\fR
267 .RS 4
268 Additional mounts to establish at boot\&. For details, see
269 \fBsystemd-fstab-generator\fR(8)\&.
270 .sp
271 Added in version 254\&.
272 .RE
273 .PP
274 \fIvconsole\&.keymap\fR, \fIvconsole\&.keymap_toggle\fR, \fIvconsole\&.font\fR, \fIvconsole\&.font_map\fR, \fIvconsole\&.font_unimap\fR
275 .RS 4
276 Console settings to apply, see
277 \fBsystemd-vconsole-setup.service\fR(8)
278 for details\&.
279 .sp
280 Added in version 253\&.
281 .RE
282 .PP
283 \fIgetty\&.auto\fR
284 .RS 4
285 Used for controlling the execution mode of
286 systemd\-getty\-generator\&. See
287 \fBsystemd-getty-generator\fR(8)
288 for details\&.
289 .sp
290 Added in version 258\&.
291 .RE
292 .PP
293 \fIgetty\&.ttys\&.serial\fR, \fIgetty\&.ttys\&.container\fR
294 .RS 4
295 Used for spawning additional login prompts, see
296 \fBsystemd-getty-generator\fR(8)
297 for details\&.
298 .sp
299 Added in version 254\&.
300 .RE
301 .PP
302 \fIjournal\&.forward_to_socket\fR
303 .RS 4
304 Used by
305 \fBsystemd-journald\fR(8)
306 to determine where to forward log messages for socket forwarding, see
307 \fBjournald.conf\fR(5)
308 for details\&.
309 .sp
310 Added in version 256\&.
311 .RE
312 .PP
313 \fIjournal\&.storage\fR
314 .RS 4
315 Used by
316 \fBsystemd-journald\fR(8)
317 to determine where to store journal files, see
318 \fBjournald.conf\fR(5)
319 for details\&.
320 .sp
321 Added in version 256\&.
322 .RE
323 .PP
324 \fIvmm\&.notify_socket\fR
325 .RS 4
326 Configures an
327 \fBsd_notify\fR(3)
328 compatible
329 \fBAF_VSOCK\fR
330 socket the service manager will report status information, ready notification and exit status on\&. For details see
331 \fBsystemd\fR(1)\&.
332 .sp
333 Added in version 253\&.
334 .RE
335 .PP
336 \fIshell\&.prompt\&.prefix\fR, \fIshell\&.prompt\&.suffix\fR
337 .RS 4
338 Defines strings to prefix and suffix any interactive UNIX shell prompt with\&. For details see
339 \fBpam_systemd\fR(8)\&.
340 .sp
341 Added in version 257\&.
342 .RE
343 .PP
344 \fIshell\&.welcome\fR
345 .RS 4
346 Define a string to print when an interactive UNIX shell initializes\&. For details see
347 \fBpam_systemd\fR(8)\&.
348 .sp
349 Added in version 257\&.
350 .RE
351 .PP
352 \fIsystem\&.machine_id\fR
353 .RS 4
354 Takes a 128bit ID to initialize the machine ID from (if it is not set yet)\&. Interpreted by the service manager (PID 1)\&. For details see
355 \fBsystemd\fR(1)\&.
356 .sp
357 Added in version 254\&.
358 .RE
359 .PP
360 \fIsystem\&.hostname\fR
361 .RS 4
362 Accepts a (transient) hostname to configure during early boot\&. The static hostname specified in
363 /etc/hostname, if configured, takes precedence over this setting\&. Interpreted by the service manager (PID 1)\&. For details see
364 \fBsystemd\fR(1)\&. Also see
365 \fIfirstboot\&.hostname\fR
366 above\&.
367 .sp
368 Added in version 254\&.
369 .RE
370 .PP
371 \fIhome\&.add\-signing\-key\&.*\fR
372 .RS 4
373 Adds a new signing key for user records to the system\&. The credential contents should contain a user signing key, for example as reported by
374 \fBhomectl get\-signing\-key\fR\&. Multiple keys may be specified, and they will be put in place under the name of the credential name suffix (which must itself carry the
375 \&.public
376 suffix)\&. For details see
377 \fBhomectl\fR(1)\&.
378 .sp
379 Added in version 258\&.
380 .RE
381 .PP
382 \fIhome\&.create\&.*\fR
383 .RS 4
384 Creates a new home area for the specified user with the user record data passed in\&. For details see
385 \fBhomectl\fR(1)\&.
386 .sp
387 Added in version 256\&.
388 .RE
389 .PP
390 \fIhome\&.register\&.*\fR
391 .RS 4
392 Registers an existing home area for the specified user with the user record data passed in\&. For details see
393 \fBhomectl\fR(1)\&.
394 .sp
395 Added in version 258\&.
396 .RE
397 .PP
398 \fIcryptsetup\&.passphrase\fR, \fIcryptsetup\&.tpm2\-pin\fR, \fIcryptsetup\&.fido2\-pin\fR, \fIcryptsetup\&.pkcs11\-pin\fR, \fIcryptsetup\&.luks2\-pin\fR
399 .RS 4
400 Specifies the passphrase/PINs to use for unlock encrypted storage volumes\&. For details see
401 \fBsystemd-cryptsetup\fR(8)\&.
402 .sp
403 Added in version 256\&.
404 .RE
405 .PP
406 \fIsystemd\&.extra\-unit\&.*\fR, \fIsystemd\&.unit\-dropin\&.*\fR
407 .RS 4
408 These credentials specify extra units and drop\-ins to add to the system\&. For details see
409 \fBsystemd-debug-generator\fR(8)\&.
410 .sp
411 Added in version 256\&.
412 .RE
413 .PP
414 \fIudev\&.conf\&.*\fR, \fIudev\&.rules\&.*\fR
415 .RS 4
416 Configures udev configuration file and udev rules\&. Read by
417 systemd\-udev\-load\-credentials\&.service, which invokes
418 \fBudevadm control \-\-load\-credentials\fR\&. These credentials directly translate to a matching
419 \fBudev.conf\fR(5)
420 or
421 \fBudev\fR(7)
422 rules file\&. Example: the contents of a credential
423 udev\&.conf\&.50\-foobar
424 will be copied into a file
425 /run/udev/udev\&.conf\&.d/50\-foobar\&.conf, and
426 udev\&.rules\&.50\-foobar
427 will be copied into a file
428 /run/udev/rules\&.d/50\-foobar\&.rules\&. See
429 \fBudev\fR(7),
430 \fBudev.conf\fR(5), and
431 \fBudevadm\fR(8)
432 for details\&.
433 .sp
434 Added in version 256\&.
435 .RE
436 .PP
437 \fIimport\&.pull\fR
438 .RS 4
439 Specified disk images (tarballs and DDIs) to automatically download and install at boot\&. For details see
440 \fBsystemd-import-generator\fR(8)\&.
441 .sp
442 Added in version 257\&.
443 .RE
444 .PP
445 \fIuserdb\&.user\&.*\fR, \fIuserdb\&.group\&.*\fR, \fIuserdb\&.transient\&.user\&.*\fR, \fIuserdb\&.transient\&.group\&.*\fR
446 .RS 4
447 Configure JSON user and group records\&. Read by
448 systemd\-userdb\-load\-credentials\&.service, which invokes
449 \fBuserdbctl load\-credentials\fR\&. These credentials directly translate to matching
450 \m[blue]\fBJSON User\fR\m[]\&\s-2\u[2]\d\s+2
451 and
452 \m[blue]\fBJSON Group\fR\m[]\&\s-2\u[3]\d\s+2
453 records\&. Example: the contents of a credential
454 userdb\&.user\&.foobar
455 will be copied into a file
456 /etc/userdb/foobar\&.user, and
457 userdb\&.group\&.foobar
458 will be copied into a file
459 /etc/userdb/foobar\&.group\&. Symlinks for the uid/gid will also be created in
460 /etc/userdb/, as well as the corresponding\&.membership
461 files\&. See
462 \fBsystemd-userdbd.service\fR(7),
463 \fBnss-systemd\fR(8), and
464 \fBuserdbctl\fR(1)
465 for details\&.
466 .sp
467 Any passed user records must contain uid and gid fields\&. Any passed group records must contain a gid field\&. For both user and group records, the credential suffix (for
468 "userdb\&.user\&.foobar"
469 the suffix is
470 "foobar") must match the user or group name field from the user or group record\&.
471 .sp
472 Note that the records created for
473 \fIuserdb\&.user\&.*\fR
474 and
475 \fIuserdb\&.group\&.*\fR
476 credentials are created in
477 /etc/userdb/
478 and the records created for
479 \fIuserdb\&.transient\&.user\&.*\fR
480 and
481 \fIuserdb\&.transient\&.group\&.*\fR
482 are created in
483 /run/userdb/
484 (/etc/passwd
485 and
486 /etc/group
487 are not modified)\&.
488 .sp
489 Added in version 258\&.
490 .RE
491 .PP
492 \fIfsck\&.*\fR
493 .RS 4
494 Read by
495 systemd\-fsck@\&.service,
496 systemd\-fsck\-root\&.service, and
497 systemd\-fsck\-usr\&.service\&. See
498 \[email protected]\fR(8)
499 for more details\&.
500 .sp
501 Added in version 258\&.
502 .RE
503 .PP
504 \fIquotacheck\&.*\fR
505 .RS 4
506 Read by
507 systemd\-quotacheck@\&.service
508 and
509 systemd\-quotacheck\-root\&.service\&. See
510 \fBsystemd-quotacheck\fR(8)
511 for more details\&.
512 .sp
513 Added in version 258\&.
514 .RE
515 .PP
516 \fIimds\&.*\fR
517 .RS 4
518 Read by
519 \[email protected]\fR(8)\&.
520 .sp
521 Added in version 261\&.
522 .RE
523 .SH "SEE ALSO"
524 .PP
525 \fBsystemd\fR(1), \fBkernel-command-line\fR(7), \fBsmbios-type-11\fR(7)
526 .SH "NOTES"
527 .IP " 1." 4
528 System and Service Credentials
529 .RS 4
530 \%https://systemd.io/CREDENTIALS
531 .RE
532 .IP " 2." 4
533 JSON User
534 .RS 4
535 \%https://systemd.io/USER_RECORD
536 .RE
537 .IP " 3." 4
538 JSON Group
539 .RS 4
540 \%https://systemd.io/GROUP_RECORD
541 .RE