picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #10569 from poettering/various-doc-fixes

Browse source 
various man page fixes
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-10-30 23:55:39 +01:00 committed by GitHub
parent fee04d7f3a e5b62c9bf1
commit 230072a5da
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 85 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
man/systemctl.xml
View file

@ -1058,6 +1058,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
terminating abnormally or timing out), it will automatically enter the <literal>failed</literal> state and
its exit code and status is recorded for introspection by the administrator until the service is
stopped/re-started or reset with this command.</para>
<para>In addition to resetting the <literal>failed</literal> state of a unit it also resets various other
per-unit properties: the start rate limit counter of all unit types is reset to zero, as is the restart
counter of service units. Thus, if a unit's start limit (as configured with
<varname>StartLimitIntervalSec=</varname>/<varname>StartLimitBurst=</varname>) is hit and the unit refuses
to be started again, use this command to make it startable again.</para>
</listitem>
</varlistentry>
@ -1085,6 +1091,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
<option>--after</option>, <option>--before</option>
may be used to change what types of dependencies
are shown.</para>
<para>Note that this command only lists units currently loaded into memory by the service manager. In
particular, this command is not suitable to get a comprehensive list at all reverse dependencies on a
specific unit, as it won't list the dependencies declared by units currently not loaded.</para>
</listitem>
</varlistentry>
</variablelist>

42
man/systemd.exec.xml
View file

@ -759,6 +759,11 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
<varname>RestrictRealtime=</varname> has no effect on systems that lack support for SECCOMP system call filtering,
or in containers where support for this is turned off.</para>
<para>Also note that some sandboxing functionality is generally not available in user services (i.e. services run
by the per-user service manager). Specifically, the various settings requiring file system namespacing support
(such as <varname>ProtectSystem=</varname>) are not available, as the underlying kernel functionality is only
accessible to privileged processes.</para>
<variablelist>
<varlistentry>
@ -776,9 +781,9 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
recommended to enable this setting for all long-running services, unless they are involved with system updates
or need to modify the operating system in other ways. If this option is used,
<varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This
setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding
mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see
below. Defaults to off.</para></listitem>
setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all
cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below. Defaults to
off.</para></listitem>
</varlistentry>
<varlistentry>
@ -797,11 +802,11 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
<varname>ReadOnlyPaths=</varname>, and <literal>tmpfs</literal> is mostly equivalent to
<varname>TemporaryFileSystem=</varname>.</para>
<para> It is recommended to enable this setting for all long-running services (in particular network-facing ones),
to ensure they cannot get access to private user data, unless the services actually require access to the user's
private data. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same
restrictions regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related
calls, see below.</para></listitem>
<para> It is recommended to enable this setting for all long-running services (in particular network-facing
ones), to ensure they cannot get access to private user data, unless the services actually require access to
the user's private data. This setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot
ensure protection in all cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>,
see below.</para></listitem>
</varlistentry>
<varlistentry>
@ -969,8 +974,7 @@ StateDirectory=aaa/bbb ccc</programlisting>
<varname>BindPaths=</varname>, or <varname>BindReadOnlyPaths=</varname> inside it. For a more flexible option,
see <varname>TemporaryFileSystem=</varname>.</para>
<para>Note that restricting access with these options does not extend to submounts of a directory that are
created later on. Non-directory paths may be specified as well. These options may be specified more than once,
<para>Non-directory paths may be specified as well. These options may be specified more than once,
in which case all paths listed will have limited access from within the namespace. If the empty string is
assigned to this option, the specific list is reset, and all prior assignments have no effect.</para>
@ -982,11 +986,19 @@ StateDirectory=aaa/bbb ccc</programlisting>
<literal>+</literal> on the same path make sure to specify <literal>-</literal> first, and <literal>+</literal>
second.</para>
<para>Note that using this setting will disconnect propagation of mounts from the service to the host
(propagation in the opposite direction continues to work). This means that this setting may not be used for
services which shall be able to install mount points in the main mount namespace. Note that the effect of these
settings may be undone by privileged processes. In order to set up an effective sandboxed environment for a
unit it is thus recommended to combine these settings with either
<para>Note that these settings will disconnect propagation of mounts from the unit's processes to the
host. This means that this setting may not be used for services which shall be able to install mount points in
the main mount namespace. For <varname>ReadWritePaths=</varname> and <varname>ReadOnlyPaths=</varname>
propagation in the other direction is not affected, i.e. mounts created on the host generally appear in the
unit processes' namespace, and mounts removed on the host also disappear there too. In particular, note that
mount propagation from host to unit will result in unmodified mounts to be created in the unit's namespace,
i.e. writable mounts appearing on the host will be writable in the unit's namespace too, even when propagated
below a path marked with <varname>ReadOnlyPaths=</varname>! Restricting access with these options hence does
not extend to submounts of a directory that are created later on. This means the lock-down offered by that
setting is not complete, and does not offer full protection. </para>
<para>Note that the effect of these settings may be undone by privileged processes. In order to set up an
effective sandboxed environment for a unit it is thus recommended to combine these settings with either
<varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or
<varname>SystemCallFilter=~@mount</varname>.</para></listitem>
</varlistentry>

12
man/systemd.socket.xml
View file

@ -94,6 +94,18 @@
socket passing (i.e. sockets passed in via standard input and
output, using <varname>StandardInput=socket</varname> in the
service file).</para>
<para>All network sockets allocated through <filename>.socket</filename> units are allocated in the host's network
namespace (see <citerefentry
project='man-pages'><refentrytitle>network_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>). This
does not mean however that the service activated by a configured socket unit has to be part of the host's network
namespace as well. It is supported and even good practice to run services in their own network namespace (for
example through <varname>PrivateNetwork=</varname>, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), receiving only
the sockets configured through socket-activation from the host's namespace. In such a set-up communication within
the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated
from the service code itself will be associated with the service's own namespace, and thus possibly subject to a a
much more restrictive configuration.</para>
</refsect1>
<refsect1>

26
man/systemd.unit.xml
View file

@ -990,12 +990,13 @@
<listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
respected. A failing condition will not result in the unit being moved into a failure state. The condition is
checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip
units that do not apply to the local running system, for example because the kernel or runtime environment
doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>,
<varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure
state and logs about the failed check (see below).</para>
respected. A failing condition will not result in the unit being moved into the <literal>failed</literal>
state. The condition is checked at the time the queued start job is to be executed. Use condition expressions
in order to silently skip units that do not apply to the local running system, for example because the kernel
or runtime environment doesn't require their functionality. Use the various
<varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … options for a similar
mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check
(instead of being silently processed). For details about assertion conditions see below.</para>
<para><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
@ -1276,9 +1277,16 @@
<listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
<varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add
assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
that is not met results in failure of the start job (which means this is logged loudly). Use assertion
expressions for units that cannot operate when specific requirements are not met, and when this is something
the administrator or user should look into.</para></listitem>
that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a
configured assertion does not cause the unit to enter the <literal>failed</literal> state (or in fact result in
any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that
cannot operate when specific requirements are not met, and when this is something the administrator or user
should look into.</para>
<para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both
are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were
queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit
dependencies.</para></listitem>
</varlistentry>
<varlistentry>

19
man/systemd.xml
View file

@ -392,6 +392,25 @@
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details about these target units.</para>
<para>systemd only keeps a minimal set of units loaded into memory. Specifically, the only units that are kept
loaded into memory are those for which at least one of the following conditions is true:</para>
<orderedlist>
<listitem><para>It is in an active, activating, deactivating or failed state (i.e. in any unit state except for <literal>dead</literal>)</para></listitem>
<listitem><para>It has a job queued for it</para></listitem>
<listitem><para>It is a dependency of some sort of at least one other unit that is loaded into memory</para></listitem>
<listitem><para>It has some form of resource still allocated (e.g. a service unit that is inactive but for which
a process is still lingering that ignored the request to be terminated)</para></listitem>
<listitem><para>It has been pinned into memory programmatically by a D-Bus call</para></listitem>
</orderedlist>
<para>systemd will automatically and implicitly load units from disk — if they are not loaded yet — as soon as
operations are requested for them. Thus, in many respects, the fact whether a unit is loaded or not is invisible to
clients. Use <command>systemctl list-units --all</command> to comprehensively list all units currently loaded. Any
unit for which none of the conditions above applies is promptly unloaded. Note that when a unit is unloaded from
memory its accounting data is flushed out too. However, this data is generally not lost, as a journal log record
is generated declaring the consumed resources whenever a unit shuts down.</para>
<para>Processes systemd spawns are placed in individual Linux
control groups named after the unit which they belong to in the
private systemd hierarchy. (see <ulink