Merge pull request #29926 from poettering/man-fixes
Various documentation fixes
This commit is contained in:
Lennart Poettering
@@ -2243,6 +2243,8 @@ Features:
|
||||
avatar/photo or so. This data should be stored along with the user record,
|
||||
but probably shouldn't be part of the record itself, since it might be
|
||||
large.
|
||||
- add "homectl unbind" command to remove local user record of an inactive
|
||||
home dir
|
||||
|
||||
* add a new switch --auto-definitions=yes/no or so to systemd-repart. If
|
||||
specified, synthesize a definition automatically if we can: enlarge last
|
||||
|
||||
+26
-14
@@ -704,28 +704,40 @@ for other purposes too.
|
||||
|
||||
The `perMachine` field in the top-level object is an array of objects. When
|
||||
processing the user record first the various fields on the top-level object
|
||||
should be used. Then this array should be iterated in order, and the various
|
||||
settings be applied that match either the indicated machine ID or host
|
||||
name. There may be multiple array entries that match a specific system, in
|
||||
which case all the object's setting should be applied. If the same option is
|
||||
set in the top-level object as in a per-machine object the latter wins and
|
||||
entirely undoes the setting in the top-level object (i.e. no merging of
|
||||
properties that are arrays themselves is done). If the same option is set in
|
||||
multiple per-machine objects the one specified later in the array wins (and
|
||||
here too no merging of individual fields is done, the later field always wins
|
||||
in full).
|
||||
should be parsed. Then, the `perMachine` array should be iterated in order, and
|
||||
the various settings within each contained object should be applied that match
|
||||
either the indicated machine ID or host name, overriding any corresponding
|
||||
settings previously parsed from the top-level object. There may be multiple
|
||||
array entries that match a specific system, in which case all settings should
|
||||
be applied. If the same option is set in the top-level object as in a
|
||||
per-machine object then the per-machine setting wins and entirely undoes the
|
||||
setting in the top-level object (i.e. no merging of properties that are arrays
|
||||
is done). If the same option is set in multiple per-machine objects the one
|
||||
specified later in the array wins (and here too no merging of individual fields
|
||||
is done, the later field always wins in full). To summarize, the order of
|
||||
application is (last one wins):
|
||||
|
||||
1. Settings in the top-level object
|
||||
2. Settings in the first matching `perMachine` array entry
|
||||
3. Settings in the second matching `perMachine` array entry
|
||||
4. …
|
||||
5. Settings in the last matching `perMachine` array entry
|
||||
|
||||
The following fields are defined in this section:
|
||||
|
||||
`matchMachineId` → An array of strings that are formatted 128-bit IDs in
|
||||
hex. If any of the specified IDs match the system's local machine ID
|
||||
(i.e. matches `/etc/machine-id`) the fields in this object are honored.
|
||||
(i.e. matches `/etc/machine-id`) the fields in this object are honored. (As a
|
||||
special case, if only a single machine ID is listed this field may be a single
|
||||
string rather than an array of strings.)
|
||||
|
||||
`matchHostname` → An array of strings that are valid hostnames. If any of
|
||||
the specified hostnames match the system's local hostname, the fields in this
|
||||
`matchHostname` → An array of strings that are valid hostnames. If any of the
|
||||
specified hostnames match the system's local hostname, the fields in this
|
||||
object are honored. If both `matchHostname` and `matchMachineId` are used
|
||||
within the same array entry, the object is honored when either match succeeds,
|
||||
i.e. the two match types are combined in OR, not in AND.
|
||||
i.e. the two match types are combined in OR, not in AND. (As a special case, if
|
||||
only a single machine ID is listed this field may be a single string rather
|
||||
than an array of strings.)
|
||||
|
||||
These two are the only two fields specific to this section. All other fields
|
||||
that may be used in this section are identical to the equally named ones in the
|
||||
|
||||
@@ -269,6 +269,11 @@
|
||||
owned by a different UID when logging in, the home directory and everything underneath it will have
|
||||
its ownership changed automatically before login completes.</para>
|
||||
|
||||
<para>Note that changing this option for existing home directories generally has no effect on home
|
||||
directories that already have been registered locally (have a local <emphasis>binding</emphasis>), as
|
||||
the UID used for an account on the local system is determined when the home directory is first
|
||||
activated on it, and then remains in effect until the home directory is removed.</para>
|
||||
|
||||
<para>Note that users managed by <command>systemd-homed</command> always have a matching group
|
||||
associated with the same name as well as a GID matching the UID of the user. Thus, configuring the
|
||||
GID separately is not permitted.</para>
|
||||
|
||||
@@ -305,9 +305,14 @@ node /org/freedesktop/home1 {
|
||||
user record with the new passwords/authentication token data is specified as empty the existing user
|
||||
record's settings are propagated down to the home directory storage. This is typically used after a
|
||||
user record is updated using <function>UpdateHome()</function> in order to propagate the
|
||||
secrets/authentication tokens down to the storage. This method is equivalent to
|
||||
<function>ChangePassword()</function> on the <classname>org.freedesktop.home1.Home</classname>
|
||||
interface.</para>
|
||||
secrets/authentication tokens down to the storage. Background: depending on the backend the user's
|
||||
authentication credentials are stored at multiple places: the user record kept on the host, the user
|
||||
record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on
|
||||
a different machined temporarily, and the password is changed there, and then is moved back to the
|
||||
original host, the passwords of the three might get out of sync. By issuing
|
||||
<function>ChangePasswordHome()</function> the three locations are updated to match the newest
|
||||
information. This method is equivalent to <function>ChangePassword()</function> on the
|
||||
<classname>org.freedesktop.home1.Home</classname> interface.</para>
|
||||
|
||||
<para><function>LockHome()</function> temporarily suspends access to a home directory, flushing out any
|
||||
cryptographic keys from memory. This is only supported on some back-ends, and usually done during system
|
||||
|
||||
@@ -107,6 +107,13 @@
|
||||
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
for details of how search and route-only domains are used.</para>
|
||||
|
||||
<para>Note that configuring the MulticastDNS domain <literal>local</literal> as search or routing
|
||||
domain has the effect of routing lookups for this domain to classic unicast DNS. This may be used to
|
||||
provide compatibility with legacy installations that use this domain in a unicast DNS context,
|
||||
against the IANA assignment of this domain to pure MulticastDNS purposes. Search and routing domains
|
||||
are a unicast DNS concept, they <emphasis>cannot</emphasis> be used to resolve single-label lookups
|
||||
via MulticastDNS.</para>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v229"/>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
+33
-14
@@ -223,6 +223,18 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>COREDUMP_CGROUP=</varname></term>
|
||||
|
||||
<listitem><para>The primary cgroup of the unit of the crashed process.</para>
|
||||
|
||||
<para>When the crashed process was in a container, this is the full path, as seen outside of the
|
||||
container.</para>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v248"/>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>COREDUMP_PROC_CGROUP=</varname></term>
|
||||
<listitem><para>Control group information in the format used in
|
||||
<filename>/proc/self/cgroup</filename>. On systems with the unified cgroup hierarchy, this is a
|
||||
single path prefixed with <literal>0::</literal>, and multiple paths prefixed with controller numbers
|
||||
@@ -238,9 +250,10 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
|
||||
<varlistentry>
|
||||
<term><varname>COREDUMP_OWNER_UID=</varname></term>
|
||||
<term><varname>COREDUMP_USER_UNIT=</varname></term>
|
||||
<term><varname>COREDUMP_SESSION=</varname></term>
|
||||
<listitem><para>The numerical UID of the user owning the login session or systemd user unit of the
|
||||
crashed process, and the user manager unit. Both fields are only present for user processes.
|
||||
</para>
|
||||
crashed process, the user manager unit, and the sesion identifier. All three fields are only present
|
||||
for user processes.</para>
|
||||
|
||||
<para>When the crashed process was in container, those are the values <emphasis>outside</emphasis>,
|
||||
in the main system.</para>
|
||||
@@ -315,23 +328,29 @@ flags: ...
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>COREDUMP_CMDLINE=</varname></term>
|
||||
<term><varname>COREDUMP_COMM=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_STATUS=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_MAPS=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_LIMITS=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_MOUNTINFO=</varname></term>
|
||||
<term><varname>COREDUMP_ENVIRON=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_AUXV=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_LIMITS=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_MAPS=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_MOUNTINFO=</varname></term>
|
||||
<term><varname>COREDUMP_PROC_STATUS=</varname></term>
|
||||
|
||||
<listitem><para>Fields that map the per-process entries in the <filename>/proc/</filename>
|
||||
filesystem: <filename>/proc/<replaceable>pid</replaceable>/comm</filename> (the command name
|
||||
associated with the process), <filename>/proc/<replaceable>pid</replaceable>/exe</filename> (the
|
||||
filename of the executed command), <filename>/proc/<replaceable>pid</replaceable>/status</filename>
|
||||
(various metadata about the process), <filename>/proc/<replaceable>pid</replaceable>/maps</filename>
|
||||
(memory regions visible to the process and their access permissions),
|
||||
filesystem: <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename> (the command line of
|
||||
the crashed process), <filename>/proc/<replaceable>pid</replaceable>/comm</filename> (the command
|
||||
name associated with the process), <filename>/proc/<replaceable>pid</replaceable>/environ</filename>
|
||||
(the environment block of the crashed process),
|
||||
<filename>/proc/<replaceable>pid</replaceable>/auxv</filename> (the auxiliary vector of the crashed
|
||||
process, see <citerefentry
|
||||
project='man-pages'><refentrytitle>getauxval</refentrytitle><manvolnum>3</manvolnum></citerefentry>),
|
||||
<filename>/proc/<replaceable>pid</replaceable>/limits</filename> (the soft and hard resource limits),
|
||||
<filename>/proc/<replaceable>pid</replaceable>/mountinfo</filename> (mount points in the process's
|
||||
mount namespace), <filename>/proc/<replaceable>pid</replaceable>/environ</filename>
|
||||
(the environment block of the crashed process).</para>
|
||||
<filename>/proc/<replaceable>pid</replaceable>/maps</filename> (memory regions visible to the process
|
||||
and their access permissions), <filename>/proc/<replaceable>pid</replaceable>/mountinfo</filename>
|
||||
(mount points in the process's mount namespace),
|
||||
<filename>/proc/<replaceable>pid</replaceable>/status</filename> (various metadata about the
|
||||
process).</para>
|
||||
|
||||
<para>See
|
||||
<citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
|
||||
@@ -475,7 +475,7 @@ SetCredentialEncrypted=mysql-password: \
|
||||
<filename>xyz.service</filename>:</para>
|
||||
|
||||
<programlisting># mkdir -p /etc/systemd/system/xyz.service.d
|
||||
# systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - >/etc/systemd/system/xyz.service.d/50-password.conf
|
||||
# systemd-ask-password -n | ( echo "[Service]" && systemd-creds encrypt --name=mysql-password -p - - ) >/etc/systemd/system/xyz.service.d/50-password.conf
|
||||
# systemctl daemon-reload
|
||||
# systemctl restart xyz.service</programlisting>
|
||||
</example>
|
||||
|
||||
@@ -235,6 +235,30 @@
|
||||
limitation does not apply to PKCS#11 tokens.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<para>Security technology both in systemd and in the general industry constantly evolves. In order to
|
||||
provide best security guarantees, the way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated
|
||||
in newer versions of systemd. Whenever this happens the following compatibility guarantees are given:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Old enrollments continue to be supported and may be unlocked with newer versions of
|
||||
<citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
|
||||
|
||||
<listitem><para>The opposite is not guaranteed however: it might not be possible to unlock volumes with
|
||||
enrollments done with a newer version of <command>systemd-cryptenroll</command> with an older version
|
||||
of <command>systemd-cryptsetup</command>.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>That said, it is generally recommended to use matching versions of
|
||||
<command>systemd-cryptenroll</command> and <command>systemd-cryptsetup</command>, since this is best
|
||||
tested and supported.</para>
|
||||
|
||||
<para>It might be advisable to re-enroll existing enrollments to take benefit of newer security features,
|
||||
as they are added to systemd.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Options</title>
|
||||
|
||||
|
||||
+18
-7
@@ -1064,14 +1064,25 @@
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>NonBlocking=</varname></term>
|
||||
<listitem><para>Set the <constant>O_NONBLOCK</constant> flag for all file descriptors passed via socket-based
|
||||
activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed
|
||||
in via the file descriptor storage logic (see <varname>FileDescriptorStoreMax=</varname> for details), will
|
||||
have the <constant>O_NONBLOCK</constant> flag set and hence are in non-blocking mode. This option is only
|
||||
<listitem><para>Set the <constant>O_NONBLOCK</constant> flag for all file descriptors passed via
|
||||
socket-based activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr),
|
||||
excluding those passed in via the file descriptor storage logic (see
|
||||
<varname>FileDescriptorStoreMax=</varname> for details), will have the
|
||||
<constant>O_NONBLOCK</constant> flag set and hence are in non-blocking mode. This option is only
|
||||
useful in conjunction with a socket unit, as described in
|
||||
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> and has no
|
||||
effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to
|
||||
false.</para></listitem>
|
||||
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
and has no effect on file descriptors which were previously saved in the file-descriptor store for
|
||||
example. Defaults to false.</para>
|
||||
|
||||
<para>Note that if the same socket unit is configured to be passed to multiple service units (via the
|
||||
<varname>Sockets=</varname> setting, see below), and these services have different
|
||||
<varname>NonBlocking=</varname> configurations, the precise state of <constant>O_NONBLOCK</constant>
|
||||
depends on the order in which these services are invoked, and will possibly change after service code
|
||||
already took possession of the socket file descriptor, simply because the
|
||||
<constant>O_NONBLOCK</constant> state of a socket is shared by all file descriptors referencing
|
||||
it. Hence it is essential that all services sharing the same socket use the same
|
||||
<varname>NonBlocking=</varname> configuration, and do not change the flag in service code
|
||||
either.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
|
||||
+8
-6
@@ -574,9 +574,10 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
|
||||
removed unless applied to a directory. This functionality is particularly useful in conjunction with
|
||||
<varname>Z</varname>.</para>
|
||||
|
||||
<para>Optionally, if prefixed with <literal>:</literal>, the configured access mode is only used when
|
||||
creating new inodes. If the inode the line refers to already exists, its access mode is left in place
|
||||
unmodified.</para>
|
||||
<para>By default the access mode of listed inodes is set to the specified mode regardless if it is
|
||||
created anew, or already existed. Optionally, if prefixed with <literal>:</literal>, the configured
|
||||
access mode is only applied when creating new inodes, and if the inode the line refers to
|
||||
already exists, its access mode is left in place unmodified.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
@@ -599,9 +600,10 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
|
||||
Resolvability of User and Group Names</ulink> for more information on requirements on system user/group
|
||||
definitions.</para>
|
||||
|
||||
<para>Optionally, if prefixed with <literal>:</literal>, the configured user/group information is only
|
||||
used when creating new inodes. If the inode the line refers to already exists, its user/group is left
|
||||
in place unmodified.</para>
|
||||
<para>By default the ownership of listed inodes is set to the specified user/group regardless if it is
|
||||
created anew, or already existed. Optionally, if prefixed with <literal>:</literal>, the configured
|
||||
user/group information is only applied when creating new inodes, and if the inode the line refers to
|
||||
already exists, its user/group is left in place unmodified.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
|
||||
Reference in New Issue
Block a user