mirror of
https://github.com/systemd/systemd
synced 2024-07-21 02:05:05 +00:00
man: document the new credentials features
This commit is contained in:
Lennart Poettering
parent
05eb896f3f
commit
72267a55a1
|
|
@ -73,6 +73,8 @@
|
|||
<term><varname>systemd.machine_id=</varname></term>
|
||||
<term><varname>systemd.unified_cgroup_hierarchy</varname></term>
|
||||
<term><varname>systemd.legacy_systemd_cgroup_controller</varname></term>
|
||||
<term><varname>systemd.set_credential=</varname></term>
|
||||
<term><varname>systemd.import_credentials=</varname></term>
|
||||
<listitem>
|
||||
<para>Parameters understood by the system and service
|
||||
manager to control system behavior. For details, see
|
||||
|
|
|
|||
|
|
@ -3039,20 +3039,31 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
|
|||
is absolute it is opened as regular file and the credential data is read from it. If the absolute
|
||||
path refers to an <constant>AF_UNIX</constant> stream socket in the file system a connection is made
|
||||
to it (only once at unit start-up) and the credential data read from the connection, providing an
|
||||
easy IPC integration point for dynamically providing credentials from other services. If the
|
||||
specified path is not absolute and itself qualifies as valid credential identifier it is understood
|
||||
to refer to a credential that the service manager itself received via the
|
||||
<varname>$CREDENTIALS_DIRECTORY</varname> environment variable, which may be used to propagate
|
||||
credentials from an invoking environment (e.g. a container manager that invoked the service manager)
|
||||
into a service. The contents of the file/socket may be arbitrary binary or textual data, including
|
||||
newline characters and <constant>NUL</constant> bytes. If the file system path is omitted it is
|
||||
chosen identical to the credential name, i.e. this is a terse way do declare credentials to inherit
|
||||
from the service manager into a service. This option may be used multiple times, each time defining
|
||||
an additional credential to pass to the unit. Alternatively, if the path is a directory, every file
|
||||
in that directory will be loaded as a separate credential. The ID for each credential will be the
|
||||
easy IPC integration point for dynamically transferring credentials from other services.</para>
|
||||
|
||||
<para>If the specified path is not absolute and itself qualifies as valid credential identifier it is
|
||||
attempted to find a credential that the service manager itself received under the specified name —
|
||||
which may be used to propagate credentials from an invoking environment (e.g. a container manager
|
||||
that invoked the service manager) into a service. If no matching system credential is found, the
|
||||
directories <filename>/etc/credstore/</filename>, <filename>/run/credstore/</filename> and
|
||||
<filename>/usr/lib/credstore/</filename> are searched for files under the credential's name — which
|
||||
hence are recommended locations for credential data on disk. If
|
||||
<varname>LoadCredentialEncrypted=</varname> is used <filename>/run/credstore.encrypted/</filename>,
|
||||
<filename>/etc/credstore.encrypted/</filename>, and
|
||||
<filename>/usr/lib/credstore.encrypted/</filename> are searched as well.</para>
|
||||
|
||||
<para>If the file system path is omitted it is chosen identical to the credential name, i.e. this is
|
||||
a terse way to declare credentials to inherit from the service manager into a service. This option
|
||||
may be used multiple times, each time defining an additional credential to pass to the unit.</para>
|
||||
|
||||
<para>If an absolute path referring to a directory is specified, every file in that directory
|
||||
(recursively) will be loaded as a separate credential. The ID for each credential will be the
|
||||
provided ID suffixed with <literal>_$FILENAME</literal> (e.g., <literal>Key_file1</literal>). When
|
||||
loading from a directory, symlinks will be ignored.</para>
|
||||
|
||||
<para>The contents of the file/socket may be arbitrary binary or textual data, including newline
|
||||
characters and <constant>NUL</constant> bytes.</para>
|
||||
|
||||
<para>The <varname>LoadCredentialEncrypted=</varname> setting is identical to
|
||||
<varname>LoadCredential=</varname>, except that the credential data is decrypted and authenticated
|
||||
before being passed on to the executed processes. Specifically, the referenced path should refer to a
|
||||
|
|
@ -3077,10 +3088,23 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
|
|||
|
||||
<para>In order to reference the path a credential may be read from within a
|
||||
<varname>ExecStart=</varname> command line use <literal>${CREDENTIALS_DIRECTORY}/mycred</literal>,
|
||||
e.g. <literal>ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred</literal>.</para>
|
||||
e.g. <literal>ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred</literal>. In order to reference the path
|
||||
a credential may be read from within a <varname>Environment=</varname> line use
|
||||
<literal>%d/mycred</literal>, e.g. <literal>Environment=MYCREDPATH=%d/mycred</literal>.</para>
|
||||
|
||||
<para>Currently, an accumulated credential size limit of 1 MB per unit is enforced.</para>
|
||||
|
||||
<para>The service manager itself may receive system credentials that can be propagated to services
|
||||
from a hosting container manager or VM hypervisor. See the <ulink
|
||||
url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> documentation for details
|
||||
about the former. For the latter, use the <command>qemu</command> <literal>fw_cfg</literal> node
|
||||
<literal>opt/io.systemd.credentials/</literal>. Example qemu switch: <literal>-fw_cfg
|
||||
name=opt/io.systemd.credentials/mycred,string=supersecret</literal>. They may also be specified on
|
||||
the kernel command line using the <literal>systemd.set_credential=</literal> switch (see
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
|
||||
and from the UEFI firmware environment via
|
||||
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
|
||||
|
||||
<para>If referencing an <constant>AF_UNIX</constant> stream socket to connect to, the connection will
|
||||
originate from an abstract namespace socket, that includes information about the unit and the
|
||||
credential ID in its socket name. Use <citerefentry
|
||||
|
|
|
|||
|
|
@ -944,6 +944,26 @@
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>systemd.set_credential=</varname></term>
|
||||
|
||||
<listitem><para>Sets a system credential, which can then be propagated to system services using the
|
||||
<varname>LoadCredential=</varname> setting, see
|
||||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||||
details. Takes a pair of credential name and value, separated by a colon. Note that the kernel
|
||||
command line is typically accessible by unprivileged programs in
|
||||
<filename>/proc/cmdline</filename>. Thus, this mechanism is not suitable for transferring sensitive
|
||||
data. Use it only for data that is not sensitive (e.g. public keys/certificates, rather than private
|
||||
keys), or in testing/debugging environments.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>systemd.import_credentials=</varname></term>
|
||||
|
||||
<listitem><para>Takes a boolean argument. If false disables importing credentials from the kernel
|
||||
command line, qemu_fw_cfg subsystem or the kernel command line.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>quiet</varname></term>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue