Config-Model-Systemd
view release on metacpan or search on metacpan
lib/Config/Model/models/Systemd/Common/Exec.pl view on Meta::CPAN
other IPC (L<mq_overview(7)>, L<svipc(7)>)\@keyringKernel keyring access (L<keyctl(2)> and related calls)\@memlockLocking
of memory in RAM (L<mlock(2)>, L<mlockall(2)> and related calls)\@moduleLoading and unloading of kernel modules
(L<init_module(2)>, L<delete_module(2)> and related calls)\@mountMounting and unmounting of file systems (L<mount(2)>,
L<chroot(2)>, and related calls)\@network-ioSocket I/O (including local AF_UNIX): L<socket(7)>,
L<unix(7)>\@obsoleteUnusual, obsolete or unimplemented (L<create_module(2)>, L<gtty(2)>, \x{2026})\@pkeySystem calls that deal
with memory protection keys (L<pkeys(7)>)\@privilegedAll system calls which need super-user capabilities
(L<capabilities(7)>)\@processProcess control, execution, namespacing operations (L<clone(2)>, L<kill(2)>,
L<namespaces(7)>, \x{2026})\@raw-ioRaw I/O port access (L<ioperm(2)>, L<iopl(2)>, pciconfig_read(), \x{2026})\@rebootSystem calls for
rebooting and reboot preparation (L<reboot(2)>, kexec(), \x{2026})\@resourcesSystem calls for changing resource limits, memory
and scheduling parameters (L<setrlimit(2)>, L<setpriority(2)>, \x{2026})\@sandboxSystem calls for sandboxing programs
(L<seccomp(2)>, Landlock system calls, \x{2026})\@setuidSystem calls for changing user ID and group ID credentials,
(L<setuid(2)>, L<setgid(2)>, L<setresuid(2)>, \x{2026})\@signalSystem calls for manipulating and handling process signals
(L<signal(2)>, L<sigprocmask(2)>, \x{2026})\@swapSystem calls for enabling/disabling swap devices (L<swapon(2)>,
L<swapoff(2)>)\@syncSynchronizing files and memory to disk (L<fsync(2)>, L<msync(2)>, and related calls)\@system-serviceA
reasonable set of system calls used by common system services, excluding any special purpose calls. This is the
recommended starting point for allow-listing system calls for system services, as it contains what is typically needed
by system services, but excludes overly specific interfaces. For example, the following APIs are excluded: C<\@clock>,
C<\@mount>, C<\@swap>, C<\@reboot>.\@timerSystem calls for scheduling operations by time (L<alarm(2)>, L<timer_create(2)>,
\x{2026})\@knownAll system calls defined by the kernel. This list is defined statically in systemd based on a kernel version
that was available when this systemd version was released. It will become progressively more out-of-date as the kernel
is updated.
lib/Config/Model/models/Systemd/Common/Exec.pl view on Meta::CPAN
},
'LoadCredential',
{
'description' => "Pass a credential to the unit. Credentials are limited-size binary or textual objects
that may be passed to unit processes. They are primarily used for passing cryptographic keys (both
public and private) or certificates, user account information or identity information from host to
services. The data is accessible from the unit's processes via the file system, at a read-only
location that (if possible and permitted) is backed by non-swappable memory. The data is only
accessible to the user associated with the unit, via the
C<User>/C<DynamicUser> settings (as well as the superuser). When
available, the location of credentials is exported as the C<\$CREDENTIALS_DIRECTORY>
environment variable to the unit's processes.
The C<LoadCredential> setting takes a textual ID to use as name for a
credential plus a file system path, separated by a colon. The ID must be a short ASCII string
suitable as filename in the filesystem, and may be chosen freely by the user. If the specified path
is absolute it is opened as regular file and the credential data is read from it. If the absolute
path refers to an C<AF_UNIX> 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 transferring credentials from other services.
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 \x{2014}
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 C</etc/credstore/>, C</run/credstore/> and
C</usr/lib/credstore/> are searched for files under the credential's name \x{2014} which
hence are recommended locations for credential data on disk. If
C<LoadCredentialEncrypted> is used C</run/credstore.encrypted/>,
C</etc/credstore.encrypted/>, and
C</usr/lib/credstore.encrypted/> are searched as well.
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.
Note that if the path is not specified or a valid credential identifier is given, i.e.
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.
lib/Config/Model/models/Systemd/Common/Exec.pl view on Meta::CPAN
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/credentials.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. When C<DevicePolicy> is set to
C<closed> or C<strict>, or set to C<auto> and
C<DeviceAllow> is set, or C<PrivateDevices> is set, then this
setting adds C</dev/tpmrm0> with C<rw> mode to
C<DeviceAllow>. 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 don't 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.",
'type' => 'leaf',
'value_type' => 'uniline'
},
'LoadCredentialEncrypted',
{
'description' => "Pass a credential to the unit. Credentials are limited-size binary or textual objects
that may be passed to unit processes. They are primarily used for passing cryptographic keys (both
public and private) or certificates, user account information or identity information from host to
services. The data is accessible from the unit's processes via the file system, at a read-only
location that (if possible and permitted) is backed by non-swappable memory. The data is only
accessible to the user associated with the unit, via the
C<User>/C<DynamicUser> settings (as well as the superuser). When
available, the location of credentials is exported as the C<\$CREDENTIALS_DIRECTORY>
environment variable to the unit's processes.
The C<LoadCredential> setting takes a textual ID to use as name for a
credential plus a file system path, separated by a colon. The ID must be a short ASCII string
suitable as filename in the filesystem, and may be chosen freely by the user. If the specified path
is absolute it is opened as regular file and the credential data is read from it. If the absolute
path refers to an C<AF_UNIX> 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 transferring credentials from other services.
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 \x{2014}
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 C</etc/credstore/>, C</run/credstore/> and
C</usr/lib/credstore/> are searched for files under the credential's name \x{2014} which
hence are recommended locations for credential data on disk. If
C<LoadCredentialEncrypted> is used C</run/credstore.encrypted/>,
C</etc/credstore.encrypted/>, and
C</usr/lib/credstore.encrypted/> are searched as well.
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.
Note that if the path is not specified or a valid credential identifier is given, i.e.
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.
lib/Config/Model/models/Systemd/Common/Exec.pl view on Meta::CPAN
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/credentials.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. When C<DevicePolicy> is set to
C<closed> or C<strict>, or set to C<auto> and
C<DeviceAllow> is set, or C<PrivateDevices> is set, then this
setting adds C</dev/tpmrm0> with C<rw> mode to
C<DeviceAllow>. 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 don't 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.",
'type' => 'leaf',
'value_type' => 'uniline'
},
'ImportCredential',
{
'description' => "Pass one or more credentials to the unit. Takes a credential name for which we'll
attempt to find a credential that the service manager itself received under the specified name \x{2014}
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 the credential name is a glob, all credentials
matching the glob are passed to the unit. Matching credentials are searched for in the system
credentials, the encrypted system credentials, and under C</etc/credstore/>,
C</run/credstore/>, C</usr/lib/credstore/>,
C</run/credstore.encrypted/>, C</etc/credstore.encrypted/>, and
C</usr/lib/credstore.encrypted/> in that order. When multiple credentials of the
same name are found, the first one found is used.
The globbing expression implements a restrictive subset of L<glob(7)>: only
a single trailing C<*> wildcard may be specified. Both C<?> and
C<[]> wildcards are not permitted, nor are C<*> wildcards anywhere
except at the end of the glob expression.
Optionally, the credential name or glob may be followed by a colon followed by a rename pattern.
If specified, all credentials matching the credential name or glob are renamed according to the given
pattern. For example, if C<ImportCredential=my.original.cred:my.renamed.cred> is
specified, the service manager will read the C<my.original.cred> credential and make
it available as the C<my.renamed.cred> credential to the service. Similarly, if
C<ImportCredential=my.original.*:my.renamed.> is specified, the service manager will
read all credentials starting with C<my.original.> and make them available as
C<my.renamed.xxx> to the service.
If C<ImportCredential> is specified multiple times and multiple credentials
end up with the same name after renaming, the first one is kept and later ones are dropped.
When multiple credentials of the same name are found, credentials found by
C<LoadCredential> and C<LoadCredentialEncrypted> take priority over
credentials found by C<ImportCredential>.",
'type' => 'leaf',
'value_type' => 'uniline'
},
'SetCredential',
{
'description' => 'The C<SetCredential> setting is similar to
C<LoadCredential> but accepts a literal value to use as data for the credential,
instead of a file system path to read the data from. Do not use this option for data that is supposed
to be secret, as it is accessible to unprivileged processes via IPC. It\'s only safe to use this for
user IDs, public key material and similar non-sensitive data. For everything else use
C<LoadCredential>. In order to embed binary data into the credential data use
C-style escaping (i.e. C<\\n> to embed a newline, or C<\\x00> to embed
a C<NUL> byte).
The C<SetCredentialEncrypted> setting is identical to
C<SetCredential> but expects an encrypted credential in literal form as value. This
allows embedding confidential credentials securely directly in unit files. Use
L<systemd-creds(1)>\'
C<-p> switch to generate suitable C<SetCredentialEncrypted> lines
directly from plaintext credentials. For further details see
C<LoadCredentialEncrypted> above.
When multiple credentials of the same name are found, credentials found by
C<LoadCredential>, C<LoadCredentialEncrypted> and
C<ImportCredential> take priority over credentials found by
C<SetCredential>. As such, C<SetCredential> will act as default if
no credentials are found by any of the former. In this case not being able to retrieve the credential
from the path specified in C<LoadCredential> or
C<LoadCredentialEncrypted> is not considered fatal.',
'type' => 'leaf',
'value_type' => 'uniline'
},
'SetCredentialEncrypted',
{
'description' => 'The C<SetCredential> setting is similar to
C<LoadCredential> but accepts a literal value to use as data for the credential,
instead of a file system path to read the data from. Do not use this option for data that is supposed
to be secret, as it is accessible to unprivileged processes via IPC. It\'s only safe to use this for
user IDs, public key material and similar non-sensitive data. For everything else use
C<LoadCredential>. In order to embed binary data into the credential data use
C-style escaping (i.e. C<\\n> to embed a newline, or C<\\x00> to embed
a C<NUL> byte).
The C<SetCredentialEncrypted> setting is identical to
C<SetCredential> but expects an encrypted credential in literal form as value. This
allows embedding confidential credentials securely directly in unit files. Use
L<systemd-creds(1)>\'
C<-p> switch to generate suitable C<SetCredentialEncrypted> lines
directly from plaintext credentials. For further details see
C<LoadCredentialEncrypted> above.
When multiple credentials of the same name are found, credentials found by
C<LoadCredential>, C<LoadCredentialEncrypted> and
C<ImportCredential> take priority over credentials found by
C<SetCredential>. As such, C<SetCredential> will act as default if
no credentials are found by any of the former. In this case not being able to retrieve the credential
from the path specified in C<LoadCredential> or
C<LoadCredentialEncrypted> is not considered fatal.',
'type' => 'leaf',
'value_type' => 'uniline'
},
'UtmpIdentifier',
{
'description' => 'Takes a four character identifier string for an L<utmp(5)> and wtmp entry
for this service. This should only be set for services such as getty implementations (such
as L<agetty(8)>) where utmp/wtmp
lib/Config/Model/models/Systemd/Section/Service.pod view on Meta::CPAN
other IPC (L<mq_overview(7)>, L<svipc(7)>)@keyringKernel keyring access (L<keyctl(2)> and related calls)@memlockLocking
of memory in RAM (L<mlock(2)>, L<mlockall(2)> and related calls)@moduleLoading and unloading of kernel modules
(L<init_module(2)>, L<delete_module(2)> and related calls)@mountMounting and unmounting of file systems (L<mount(2)>,
L<chroot(2)>, and related calls)@network-ioSocket I/O (including local AF_UNIX): L<socket(7)>,
L<unix(7)>@obsoleteUnusual, obsolete or unimplemented (L<create_module(2)>, L<gtty(2)>, …)@pkeySystem calls that deal
with memory protection keys (L<pkeys(7)>)@privilegedAll system calls which need super-user capabilities
(L<capabilities(7)>)@processProcess control, execution, namespacing operations (L<clone(2)>, L<kill(2)>,
L<namespaces(7)>, …)@raw-ioRaw I/O port access (L<ioperm(2)>, L<iopl(2)>, pciconfig_read(), …)@rebootSystem calls for
rebooting and reboot preparation (L<reboot(2)>, kexec(), …)@resourcesSystem calls for changing resource limits, memory
and scheduling parameters (L<setrlimit(2)>, L<setpriority(2)>, …)@sandboxSystem calls for sandboxing programs
(L<seccomp(2)>, Landlock system calls, …)@setuidSystem calls for changing user ID and group ID credentials,
(L<setuid(2)>, L<setgid(2)>, L<setresuid(2)>, …)@signalSystem calls for manipulating and handling process signals
(L<signal(2)>, L<sigprocmask(2)>, …)@swapSystem calls for enabling/disabling swap devices (L<swapon(2)>,
L<swapoff(2)>)@syncSynchronizing files and memory to disk (L<fsync(2)>, L<msync(2)>, and related calls)@system-serviceA
reasonable set of system calls used by common system services, excluding any special purpose calls. This is the
recommended starting point for allow-listing system calls for system services, as it contains what is typically needed
by system services, but excludes overly specific interfaces. For example, the following APIs are excluded: C<@clock>,
C<@mount>, C<@swap>, C<@reboot>.@timerSystem calls for scheduling operations by time (L<alarm(2)>, L<timer_create(2)>,
…)@knownAll system calls defined by the kernel. This list is defined statically in systemd based on a kernel version
that was available when this systemd version was released. It will become progressively more out-of-date as the kernel
is updated.
lib/Config/Model/models/Systemd/Section/Service.pod view on Meta::CPAN
=head2 LoadCredential
Pass a credential to the unit. Credentials are limited-size binary or textual objects
that may be passed to unit processes. They are primarily used for passing cryptographic keys (both
public and private) or certificates, user account information or identity information from host to
services. The data is accessible from the unit's processes via the file system, at a read-only
location that (if possible and permitted) is backed by non-swappable memory. The data is only
accessible to the user associated with the unit, via the
C<User>/C<DynamicUser> settings (as well as the superuser). When
available, the location of credentials is exported as the C<$CREDENTIALS_DIRECTORY>
environment variable to the unit's processes.
The C<LoadCredential> setting takes a textual ID to use as name for a
credential plus a file system path, separated by a colon. The ID must be a short ASCII string
suitable as filename in the filesystem, and may be chosen freely by the user. If the specified path
is absolute it is opened as regular file and the credential data is read from it. If the absolute
path refers to an C<AF_UNIX> 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 transferring credentials from other services.
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 C</etc/credstore/>, C</run/credstore/> and
C</usr/lib/credstore/> are searched for files under the credential's name — which
hence are recommended locations for credential data on disk. If
C<LoadCredentialEncrypted> is used C</run/credstore.encrypted/>,
C</etc/credstore.encrypted/>, and
C</usr/lib/credstore.encrypted/> are searched as well.
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.
Note that if the path is not specified or a valid credential identifier is given, i.e.
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.
lib/Config/Model/models/Systemd/Section/Service.pod view on Meta::CPAN
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/credentials.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. When C<DevicePolicy> is set to
C<closed> or C<strict>, or set to C<auto> and
C<DeviceAllow> is set, or C<PrivateDevices> is set, then this
setting adds C</dev/tpmrm0> with C<rw> mode to
C<DeviceAllow>. 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 don't 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)> – 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. I< Optional. Type uniline. >
=head2 LoadCredentialEncrypted
Pass a credential to the unit. Credentials are limited-size binary or textual objects
that may be passed to unit processes. They are primarily used for passing cryptographic keys (both
public and private) or certificates, user account information or identity information from host to
services. The data is accessible from the unit's processes via the file system, at a read-only
location that (if possible and permitted) is backed by non-swappable memory. The data is only
accessible to the user associated with the unit, via the
C<User>/C<DynamicUser> settings (as well as the superuser). When
available, the location of credentials is exported as the C<$CREDENTIALS_DIRECTORY>
environment variable to the unit's processes.
The C<LoadCredential> setting takes a textual ID to use as name for a
credential plus a file system path, separated by a colon. The ID must be a short ASCII string
suitable as filename in the filesystem, and may be chosen freely by the user. If the specified path
is absolute it is opened as regular file and the credential data is read from it. If the absolute
path refers to an C<AF_UNIX> 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 transferring credentials from other services.
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 C</etc/credstore/>, C</run/credstore/> and
C</usr/lib/credstore/> are searched for files under the credential's name — which
hence are recommended locations for credential data on disk. If
C<LoadCredentialEncrypted> is used C</run/credstore.encrypted/>,
C</etc/credstore.encrypted/>, and
C</usr/lib/credstore.encrypted/> are searched as well.
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.
Note that if the path is not specified or a valid credential identifier is given, i.e.
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.
lib/Config/Model/models/Systemd/Section/Service.pod view on Meta::CPAN
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/credentials.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. When C<DevicePolicy> is set to
C<closed> or C<strict>, or set to C<auto> and
C<DeviceAllow> is set, or C<PrivateDevices> is set, then this
setting adds C</dev/tpmrm0> with C<rw> mode to
C<DeviceAllow>. 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 don't 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)> – 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. I< Optional. Type uniline. >
=head2 ImportCredential
Pass one or more credentials to the unit. Takes a credential name for which we'll
attempt 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 the credential name is a glob, all credentials
matching the glob are passed to the unit. Matching credentials are searched for in the system
credentials, the encrypted system credentials, and under C</etc/credstore/>,
C</run/credstore/>, C</usr/lib/credstore/>,
C</run/credstore.encrypted/>, C</etc/credstore.encrypted/>, and
C</usr/lib/credstore.encrypted/> in that order. When multiple credentials of the
same name are found, the first one found is used.
The globbing expression implements a restrictive subset of L<glob(7)>: only
a single trailing C<*> wildcard may be specified. Both C<?> and
C<[]> wildcards are not permitted, nor are C<*> wildcards anywhere
except at the end of the glob expression.
Optionally, the credential name or glob may be followed by a colon followed by a rename pattern.
If specified, all credentials matching the credential name or glob are renamed according to the given
pattern. For example, if C<ImportCredential=my.original.cred:my.renamed.cred> is
specified, the service manager will read the C<my.original.cred> credential and make
it available as the C<my.renamed.cred> credential to the service. Similarly, if
C<ImportCredential=my.original.*:my.renamed.> is specified, the service manager will
read all credentials starting with C<my.original.> and make them available as
C<my.renamed.xxx> to the service.
If C<ImportCredential> is specified multiple times and multiple credentials
end up with the same name after renaming, the first one is kept and later ones are dropped.
When multiple credentials of the same name are found, credentials found by
C<LoadCredential> and C<LoadCredentialEncrypted> take priority over
credentials found by C<ImportCredential>. I< Optional. Type uniline. >
=head2 SetCredential
The C<SetCredential> setting is similar to
C<LoadCredential> but accepts a literal value to use as data for the credential,
instead of a file system path to read the data from. Do not use this option for data that is supposed
to be secret, as it is accessible to unprivileged processes via IPC. It's only safe to use this for
user IDs, public key material and similar non-sensitive data. For everything else use
C<LoadCredential>. In order to embed binary data into the credential data use
C-style escaping (i.e. C<\n> to embed a newline, or C<\x00> to embed
a C<NUL> byte).
The C<SetCredentialEncrypted> setting is identical to
C<SetCredential> but expects an encrypted credential in literal form as value. This
allows embedding confidential credentials securely directly in unit files. Use
L<systemd-creds(1)>'
C<-p> switch to generate suitable C<SetCredentialEncrypted> lines
directly from plaintext credentials. For further details see
C<LoadCredentialEncrypted> above.
When multiple credentials of the same name are found, credentials found by
C<LoadCredential>, C<LoadCredentialEncrypted> and
C<ImportCredential> take priority over credentials found by
C<SetCredential>. As such, C<SetCredential> will act as default if
no credentials are found by any of the former. In this case not being able to retrieve the credential
from the path specified in C<LoadCredential> or
C<LoadCredentialEncrypted> is not considered fatal. I< Optional. Type uniline. >
=head2 SetCredentialEncrypted
The C<SetCredential> setting is similar to
C<LoadCredential> but accepts a literal value to use as data for the credential,
instead of a file system path to read the data from. Do not use this option for data that is supposed
to be secret, as it is accessible to unprivileged processes via IPC. It's only safe to use this for
user IDs, public key material and similar non-sensitive data. For everything else use
C<LoadCredential>. In order to embed binary data into the credential data use
C-style escaping (i.e. C<\n> to embed a newline, or C<\x00> to embed
a C<NUL> byte).
The C<SetCredentialEncrypted> setting is identical to
C<SetCredential> but expects an encrypted credential in literal form as value. This
allows embedding confidential credentials securely directly in unit files. Use
L<systemd-creds(1)>'
C<-p> switch to generate suitable C<SetCredentialEncrypted> lines
directly from plaintext credentials. For further details see
C<LoadCredentialEncrypted> above.
When multiple credentials of the same name are found, credentials found by
C<LoadCredential>, C<LoadCredentialEncrypted> and
C<ImportCredential> take priority over credentials found by
C<SetCredential>. As such, C<SetCredential> will act as default if
no credentials are found by any of the former. In this case not being able to retrieve the credential
from the path specified in C<LoadCredential> or
C<LoadCredentialEncrypted> is not considered fatal. I< Optional. Type uniline. >
=head2 UtmpIdentifier
Takes a four character identifier string for an L<utmp(5)> and wtmp entry
for this service. This should only be set for services such as getty implementations (such
as L<agetty(8)>) where utmp/wtmp
entries must be created and cleared before and after execution, or for services that shall be executed as if
they were run by a getty process (see below). If the configured string is longer than four
lib/Config/Model/models/Systemd/Section/ServiceUnit.pod view on Meta::CPAN
are supported by a kernel, because of the widespread practice of backporting drivers, features, and
fixes from newer upstream kernels into older versions provided by distributions. Hence, this check
is inherently unportable and should not be used for units which may be used on different
distributions. I< Optional. Type list of uniline. >
=head2 ConditionCredential
C<ConditionCredential> may be used to check whether a credential
by the specified name was passed into the service manager. See L<System and Service
Credentials|https://systemd.io/CREDENTIALS> for details about
credentials. If used in services for the system service manager this may be used to conditionalize
services based on system credentials passed in. If used in services for the per-user service
manager this may be used to conditionalize services based on credentials passed into the
C<unit@.service> service instance belonging to the user. The argument must be a
valid credential name. I< Optional. Type list of uniline. >
=head2 ConditionEnvironment
C<ConditionEnvironment> may be used to check whether a specific
environment variable is set (or if prefixed with the exclamation mark — unset) in the service
manager's environment block.
The argument may be a single word, to check if the variable with this name is defined in the
environment block, or an assignment
lib/Config/Model/models/Systemd/Section/Socket.pl view on Meta::CPAN
'type' => 'leaf',
'value_type' => 'boolean',
'write_as' => [
'no',
'yes'
]
},
'PassCredentials',
{
'description' => 'Takes a boolean value. This controls the C<SO_PASSCRED> socket
option, which allows C<AF_UNIX> sockets to receive the credentials of the sending
process in an ancillary message. Defaults to C<false>.',
'type' => 'leaf',
'value_type' => 'boolean',
'write_as' => [
'no',
'yes'
]
},
'PassSecurity',
{
lib/Config/Model/models/Systemd/Section/Socket.pod view on Meta::CPAN
=head2 Broadcast
Takes a boolean value. This controls the C<SO_BROADCAST> socket
option, which allows broadcast datagrams to be sent from this socket. Defaults to
C<false>. I< Optional. Type boolean. >
=head2 PassCredentials
Takes a boolean value. This controls the C<SO_PASSCRED> socket
option, which allows C<AF_UNIX> sockets to receive the credentials of the sending
process in an ancillary message. Defaults to C<false>. I< Optional. Type boolean. >
=head2 PassSecurity
Takes a boolean value. This controls the C<SO_PASSSEC> socket
option, which allows C<AF_UNIX> sockets to receive the security context of the
sending process in an ancillary message. Defaults to C<false>. I< Optional. Type boolean. >
=head2 PassPacketInfo
lib/Config/Model/models/Systemd/Section/SocketUnit.pod view on Meta::CPAN
are supported by a kernel, because of the widespread practice of backporting drivers, features, and
fixes from newer upstream kernels into older versions provided by distributions. Hence, this check
is inherently unportable and should not be used for units which may be used on different
distributions. I< Optional. Type list of uniline. >
=head2 ConditionCredential
C<ConditionCredential> may be used to check whether a credential
by the specified name was passed into the service manager. See L<System and Service
Credentials|https://systemd.io/CREDENTIALS> for details about
credentials. If used in services for the system service manager this may be used to conditionalize
services based on system credentials passed in. If used in services for the per-user service
manager this may be used to conditionalize services based on credentials passed into the
C<unit@.service> service instance belonging to the user. The argument must be a
valid credential name. I< Optional. Type list of uniline. >
=head2 ConditionEnvironment
C<ConditionEnvironment> may be used to check whether a specific
environment variable is set (or if prefixed with the exclamation mark — unset) in the service
manager's environment block.
The argument may be a single word, to check if the variable with this name is defined in the
environment block, or an assignment
lib/Config/Model/models/Systemd/Section/TimerUnit.pod view on Meta::CPAN
are supported by a kernel, because of the widespread practice of backporting drivers, features, and
fixes from newer upstream kernels into older versions provided by distributions. Hence, this check
is inherently unportable and should not be used for units which may be used on different
distributions. I< Optional. Type list of uniline. >
=head2 ConditionCredential
C<ConditionCredential> may be used to check whether a credential
by the specified name was passed into the service manager. See L<System and Service
Credentials|https://systemd.io/CREDENTIALS> for details about
credentials. If used in services for the system service manager this may be used to conditionalize
services based on system credentials passed in. If used in services for the per-user service
manager this may be used to conditionalize services based on credentials passed into the
C<unit@.service> service instance belonging to the user. The argument must be a
valid credential name. I< Optional. Type list of uniline. >
=head2 ConditionEnvironment
C<ConditionEnvironment> may be used to check whether a specific
environment variable is set (or if prefixed with the exclamation mark — unset) in the service
manager's environment block.
The argument may be a single word, to check if the variable with this name is defined in the
environment block, or an assignment
lib/Config/Model/models/Systemd/Section/Unit.pl view on Meta::CPAN
},
'ConditionCredential',
{
'cargo' => {
'type' => 'leaf',
'value_type' => 'uniline'
},
'description' => 'C<ConditionCredential> may be used to check whether a credential
by the specified name was passed into the service manager. See L<System and Service
Credentials|https://systemd.io/CREDENTIALS> for details about
credentials. If used in services for the system service manager this may be used to conditionalize
services based on system credentials passed in. If used in services for the per-user service
manager this may be used to conditionalize services based on credentials passed into the
C<unit@.service> service instance belonging to the user. The argument must be a
valid credential name.',
'type' => 'list'
},
'ConditionEnvironment',
{
'cargo' => {
'type' => 'leaf',
'value_type' => 'uniline'
},
( run in 0.255 second using v1.01-cache-2.11-cpan-4d50c553e7e )