man/systemd.system-credentials.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.system-credentials" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>systemd.system-credentials</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd.system-credentials</refentrytitle>
  15     <manvolnum>7</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd.system-credentials</refname>
  20     <refpurpose>System Credentials</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Description</title>
  25
  26     <para><ulink url="https://systemd.io/CREDENTIALS">System and Service Credentials</ulink> are data objects
  27     that may be passed into booted systems or system services as they are invoked. They can be acquired from
  28     various external sources, and propagated into the system and from there into system services. Credentials
  29     may optionally be encrypted with a machine-specific key and/or locked to the local TPM2 device, and are
  30     only decrypted when the consuming service is invoked.</para>
  31
  32     <para>System credentials may be used to provision and configure various aspects of the system. Depending
  33     on the consuming component credentials are only used on initial invocations or are needed for all
  34     invocations.</para>
  35
  36     <para>Credentials may be used for any kind of data, binary or text, and may carry passwords, secrets,
  37     certificates, cryptographic key material, identity information, configuration, and more.</para>
  38   </refsect1>
  39
  40   <refsect1>
  41     <title>Well known system credentials</title>
  42
  43     <variablelist class='system-credentials'>
  44       <varlistentry>
  45         <term><varname>firstboot.keymap</varname></term>
  46         <listitem>
  47           <para>The console key mapping to set (e.g. <literal>de</literal>).  Read by
  48           <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  49           and only honoured if no console keymap has been configured before.</para>
  50
  51         <xi:include href="version-info.xml" xpointer="v252"/>
  52         </listitem>
  53       </varlistentry>
  54
  55       <varlistentry>
  56         <term><varname>firstboot.locale</varname></term>
  57         <term><varname>firstboot.locale-messages</varname></term>
  58         <listitem>
  59           <para>The system locale to set (e.g. <literal>de_DE.UTF-8</literal>). Read by
  60           <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  61           and only honoured if no locale has been configured before. <varname>firstboot.locale</varname> sets
  62           <literal>LANG</literal>, while <varname>firstboot.locale-message</varname> sets
  63           <literal>LC_MESSAGES</literal>.</para>
  64
  65         <xi:include href="version-info.xml" xpointer="v252"/>
  66         </listitem>
  67       </varlistentry>
  68
  69       <varlistentry>
  70         <term><varname>firstboot.timezone</varname></term>
  71         <listitem>
  72           <para>The system timezone to set (e.g. <literal>Europe/Berlin</literal>).  Read by
  73           <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  74           and only honoured if no system timezone has been configured before.</para>
  75
  76         <xi:include href="version-info.xml" xpointer="v252"/>
  77         </listitem>
  78       </varlistentry>
  79
  80       <varlistentry>
  81         <term><varname>login.issue</varname></term>
  82         <listitem>
  83           <para>The data of this credential is written to
  84           <filename>/etc/issue.d/50-provision.conf</filename>, if the file doesn't exist yet.
  85           <citerefentry project='man-pages'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  86           reads this file and shows its contents at the login prompt of terminal logins. See
  87           <citerefentry project='man-pages'><refentrytitle>issue</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  88           for details.</para>
  89
  90           <para>Consumed by <filename>/usr/lib/tmpfiles.d/provision.conf</filename>, see
  91           <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  92
  93           <xi:include href="version-info.xml" xpointer="v252"/>
  94         </listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term><varname>login.motd</varname></term>
  99         <listitem>
 100           <para>The data of this credential is written to <filename>/etc/motd.d/50-provision.conf</filename>,
 101           if the file doesn't exist yet.
 102           <citerefentry project='man-pages'><refentrytitle>pam_motd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 103           reads this file and shows its contents as "message of the day" during terminal logins. See
 104           <citerefentry project='man-pages'><refentrytitle>motd</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 105           for details.</para>
 106
 107           <para>Consumed by <filename>/usr/lib/tmpfiles.d/provision.conf</filename>, see
 108           <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 109
 110           <xi:include href="version-info.xml" xpointer="v252"/>
 111         </listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><varname>network.hosts</varname></term>
 116         <listitem>
 117           <para>The data of this credential is written to <filename>/etc/hosts</filename>, if the file
 118           doesn't exist yet. See
 119           <citerefentry project='man-pages'><refentrytitle>hosts</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 120           for details.</para>
 121
 122           <para>Consumed by <filename>/usr/lib/tmpfiles.d/provision.conf</filename>, see
 123           <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 124
 125           <xi:include href="version-info.xml" xpointer="v252"/>
 126         </listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><varname>network.dns</varname></term>
 131         <term><varname>network.search_domains</varname></term>
 132         <listitem>
 133           <para>DNS server information and search domains. Read by
 134           <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 135
 136           <xi:include href="version-info.xml" xpointer="v253"/>
 137         </listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><varname>network.netdev.*</varname></term>
 142         <term><varname>network.link.*</varname></term>
 143         <term><varname>network.network.*</varname></term>
 144         <listitem>
 145           <para>Configures network devices. Read by
 146           <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. These
 147           credentials directly translate to a matching <filename>*.netdev</filename>,
 148           <filename>*.link</filename> or <filename>*.network</filename> file. Example: the contents of a
 149           credential <filename>network.link.50-foobar</filename> will be copied into a file
 150           <filename>50-foobar.link</filename>. See
 151           <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 152           <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 153           <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 154           for details.</para>
 155
 156           <para>Note that the resulting files are created world-readable, it's hence recommended to not include
 157           secrets in these credentials, but supply them via separate credentials directly to
 158           <filename>systemd-networkd.service</filename>.</para>
 159
 160           <xi:include href="version-info.xml" xpointer="v256"/>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term><varname>passwd.hashed-password.root</varname></term>
 166         <term><varname>passwd.plaintext-password.root</varname></term>
 167         <listitem>
 168           <para>May contain the password (either in UNIX hashed format, or in plaintext) for the root users.
 169           Read by both
 170           <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 171           and
 172           <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 173           and only honoured if no root password has been configured before.</para>
 174
 175           <xi:include href="version-info.xml" xpointer="v252"/>
 176         </listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><varname>passwd.shell.root</varname></term>
 181         <listitem>
 182           <para>The path to the shell program (e.g. <literal>/bin/bash</literal>) for the root user.  Read by
 183           both
 184           <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 185           and
 186           <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 187           and only honoured if no root shell has been configured before.</para>
 188
 189         <xi:include href="version-info.xml" xpointer="v252"/>
 190         </listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><varname>ssh.authorized_keys.root</varname></term>
 195         <listitem>
 196           <para>The data of this credential is written to <filename>/root/.ssh/authorized_keys</filename>, if
 197           the file doesn't exist yet. This allows provisioning SSH access for the system's root user.</para>
 198
 199           <para>Consumed by <filename>/usr/lib/tmpfiles.d/provision.conf</filename>, see
 200           <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 201
 202           <xi:include href="version-info.xml" xpointer="v252"/>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><varname>sysusers.extra</varname></term>
 208         <listitem>
 209           <para>Additional
 210           <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 211           lines to process during boot.</para>
 212
 213           <xi:include href="version-info.xml" xpointer="v252"/>
 214         </listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><varname>sysctl.extra</varname></term>
 219         <listitem>
 220           <para>Additional
 221           <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> lines
 222           to process during boot.</para>
 223
 224           <xi:include href="version-info.xml" xpointer="v252"/>
 225         </listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><varname>tmpfiles.extra</varname></term>
 230         <listitem>
 231           <para>Additional
 232           <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 233           lines to process during boot.</para>
 234
 235           <xi:include href="version-info.xml" xpointer="v252"/>
 236         </listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term><varname>fstab.extra</varname></term>
 241
 242         <listitem>
 243           <para>Additional mounts to establish at boot. For details, see
 244           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 245
 246           <xi:include href="version-info.xml" xpointer="v254"/>
 247         </listitem>
 248       </varlistentry>
 249
 250       <varlistentry>
 251         <term><varname>vconsole.keymap</varname></term>
 252         <term><varname>vconsole.keymap_toggle</varname></term>
 253         <term><varname>vconsole.font</varname></term>
 254         <term><varname>vconsole.font_map</varname></term>
 255         <term><varname>vconsole.font_unimap</varname></term>
 256         <listitem>
 257           <para>Console settings to apply, see
 258           <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.</para>
 259
 260           <xi:include href="version-info.xml" xpointer="v253"/>
 261         </listitem>
 262       </varlistentry>
 263
 264       <varlistentry>
 265         <term><varname>getty.ttys.serial</varname></term>
 266         <term><varname>getty.ttys.container</varname></term>
 267
 268         <listitem><para>Used for spawning additional login prompts, see
 269         <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.</para>
 270
 271         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 272       </varlistentry>
 273
 274       <varlistentry>
 275         <term><varname>vmm.notify_socket</varname></term>
 276         <listitem>
 277           <para>Configures an
 278           <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 279           compatible <constant>AF_VSOCK</constant> socket the service manager will report status information,
 280           ready notification and exit status on. For details see
 281           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 282
 283           <xi:include href="version-info.xml" xpointer="v253"/>
 284         </listitem>
 285       </varlistentry>
 286
 287       <varlistentry>
 288         <term><varname>system.machine_id</varname></term>
 289         <listitem>
 290           <para>Takes a 128bit ID to initialize the machine ID from (if it is not set yet). Interpreted by
 291           the service manager (PID 1). For details see
 292           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 293
 294           <xi:include href="version-info.xml" xpointer="v254"/>
 295         </listitem>
 296       </varlistentry>
 297
 298       <varlistentry>
 299         <term><varname>home.create.*</varname></term>
 300         <listitem>
 301           <para>Creates a home area for the specified user with the user record data passed in. For details see
 302           <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 303
 304           <xi:include href="version-info.xml" xpointer="v256"/>
 305         </listitem>
 306       </varlistentry>
 307     </variablelist>
 308   </refsect1>
 309
 310   <refsect1>
 311       <title>See Also</title>
 312       <para><simplelist type="inline">
 313         <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 314         <member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 315         <member><citerefentry><refentrytitle>smbios-type-11</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 316       </simplelist></para>
 317   </refsect1>
 318
 319 </refentry>