view release on metacpan or  search on metacpan

lib/Config/Model/models/Systemd/Common/Exec.pl  view on Meta::CPAN

in the above two cases, a missing credential is not considered fatal.

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 C<_\$FILENAME> (e.g., C<Key_file1>). When
loading from a directory, symlinks will be ignored.

The contents of the file/socket may be arbitrary binary or textual data, including newline
characters and C<NUL> bytes.

The C<LoadCredentialEncrypted> setting is identical to
C<LoadCredential>, 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
file or socket with an encrypted credential, as implemented by
L<systemd-creds(1)>. This
credential is loaded, decrypted, authenticated and then passed to the application in plaintext form,
in the same way a regular credential specified via C<LoadCredential> would be. A
credential configured this way may be symmetrically encrypted/authenticated with a secret key derived
from the system's TPM2 security chip, or with a secret key stored in
C</var/lib/systemd/credential.secret>, or with both. Using encrypted and
authenticated credentials improves security as credentials are not stored in plaintext and only
authenticated and decrypted into plaintext the moment a service requiring them is started. Moreover,
credentials may be bound to the local hardware and installations, so that they cannot easily be
analyzed offline, or be generated externally. See
L<systemd.resource-control(5)>
for the details about C<DevicePolicy> or C<DeviceAllow>.

Note that encrypted credentials targeted for services of the per-user service manager must be
encrypted with systemd-creds encrypt --user, and those for the system service
manager without the C<--user> switch. Encrypted credentials are always targeted to a
specific user or the system as a whole, and it is ensured that per-user service managers cannot
decrypt secrets intended for the system or for other users.

The credential files/IPC sockets must be accessible to the service manager, but do not have to
be directly accessible to the unit's processes: the credential data is read and copied into separate,
read-only copies for the unit that are accessible to appropriately privileged processes. This is
particularly useful in combination with C<DynamicUser> as this way privileged data
can be made available to processes running under a dynamic UID (i.e. not a previously known one)
without having to open up access to all users.

In order to reference the path a credential may be read from within a
C<ExecStart> command line use C<\${CREDENTIALS_DIRECTORY}/mycred>,
e.g. C<ExecStart=cat \${CREDENTIALS_DIRECTORY}/mycred>. In order to reference the path
a credential may be read from within a C<Environment> line use
C<%d/mycred>, e.g. C<Environment=MYCREDPATH=%d/mycred>. For system
services the path may also be referenced as
C</run/credentials/UNITNAME> in cases where no
interpolation is possible, e.g. configuration files of software that does not yet support credentials
natively. C<\$CREDENTIALS_DIRECTORY> is considered the primary interface to look for
credentials, though, since it also works for user services.

Currently, an accumulated credential size limit of 1 MB per unit is enforced.

The service manager itself may receive system credentials that can be propagated to services
from a hosting container manager or VM hypervisor. See the L<Container
Interface|https://systemd.io/CONTAINER_INTERFACE> documentation for details
about the former. For the latter, pass L<DMI/SMBIOS|https://www.dmtf.org/standards/smbios> OEM string table entries
(field type
11) with a prefix of C<io.systemd.credential:> or
C<io.systemd.credential.binary:>. In both cases a key/value pair separated by
C<=> is expected. In the latter case, the right-hand side is Base64 decoded when
parsed (thus permitting binary data to be passed in). Example
L<qemu|https://www.qemu.org/docs/master/system/index.html> switch: C<-smbios
type=11,value=io.systemd.credential:xx=yy>, or C<-smbios
type=11,value=io.systemd.credential.binary:rick=TmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXA=>. Alternatively,
use the qemu C<fw_cfg> node
C<opt/io.systemd.credentials/>. Example qemu switch:
C<-fw_cfg name=opt/io.systemd.credentials/mycred,string=supersecret>. They may also
be passed from the UEFI firmware environment via
L<systemd-stub(7)>,
from the initrd (see
L<systemd(1)>), or be
specified on the kernel command line using the C<systemd.set_credential=> and
C<systemd.set_credential_binary=> switches (see
L<systemd(1)> \x{2013} this is
not recommended since unprivileged userspace can read the kernel command line).

If referencing an C<AF_UNIX> 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 L<getpeername(2)>
to query this information. The returned socket name is formatted as C<NUL>RANDOM C</unit/> UNITC</> ID, i.e. a C<NUL>
byte (as required
for abstract namespace socket names), followed by a random string (consisting of alphadecimal
characters), followed by the literal string C</unit/>, followed by the requesting
unit name, followed by the literal character C</>, followed by the textual credential
ID requested. Example: C<\\0adf9d86b6eda275e/unit/foobar.service/credx> in case the
credential C<credx> is requested for a unit C<foobar.service>. This
functionality is useful for using a single listening socket to serve credentials to multiple
consumers.

For further information see L<System and Service
Credentials|https://systemd.io/CREDENTIALS> documentation.",
      'LoadCredentialEncrypted' => '*LoadCredential',
      'LockPersonality' => 'Takes a boolean argument. If set, locks down the L<personality(2)> system
call so that the kernel execution domain may not be changed from the default or the personality selected with
C<Personality> directive. This may be useful to improve security, because odd personality
emulations may be poorly tested and source of vulnerabilities.',
      'LogExtraFields' => 'Configures additional log metadata fields to include in all log records generated by
processes associated with this unit, including systemd. This setting takes one or more journal field
assignments in the format C<FIELD=VALUE> separated by whitespace. See
L<systemd.journal-fields(7)>
for details on the journal field concept. Even though the underlying journal implementation permits
binary field values, this setting accepts only valid UTF-8 values. To include space characters in a
journal field value, enclose the assignment in double quotes (").
The usual specifiers are expanded in all assignments (see below). Note that this setting is not only
useful for attaching additional metadata to log records of a unit, but given that all fields and
values are indexed may also be used to implement cross-unit log record matching. Assign an empty
string to reset the list.

Note that this functionality is currently only available in system services, not in per-user
services.',
      'LogFilterPatterns' => 'Define an extended regular expression to filter log messages based on the
C<MESSAGE> field of the structured message. If the first character of the pattern is
C<~>, log entries matching the pattern should be discarded. This option takes a single
pattern as an argument but can be used multiple times to create a list of allowed and denied patterns.
If the empty string is assigned, the filter is reset, and all prior assignments will have no effect.

Because the C<~> character is used to define denied patterns, it must be replaced
with C<\\x7e> to allow a message starting with C<~>. For example,
C<~foobar> would add a pattern matching C<foobar> to the deny list, while
C<\\x7efoobar> would add a pattern matching C<~foobar> to the allow list.