diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/sd_notify.xml | 9 | ||||
| -rw-r--r-- | man/systemd-notify.xml | 22 | ||||
| -rw-r--r-- | man/systemd-run.xml | 4 | ||||
| -rw-r--r-- | man/systemd-socket-proxyd.xml | 6 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 55 | ||||
| -rw-r--r-- | man/systemd.service.xml | 45 |
6 files changed, 76 insertions, 65 deletions
diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 6e98041912..4dcefc4baf 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -268,6 +268,15 @@ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para> + <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either + the sending process is still around at the time PID 1 processes the message, or if the sending process is + explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked + off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or + <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an + <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly + attribute the message to the unit, and thus will ignore it, even if + <varname>NotifyAccess=</varname><option>all</option> is set for it.</para> + <para><function>sd_notifyf()</function> is similar to <function>sd_notify()</function> but takes a <function>printf()</function>-like format string plus diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 4a8e119eb6..8c56a6b8ed 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -72,10 +72,24 @@ <para>The command line may carry a list of environment variables to send as part of the status update.</para> - <para>Note that systemd will refuse reception of status updates - from this command unless <varname>NotifyAccess=all</varname> is - set for the service unit this command is called from.</para> - + <para>Note that systemd will refuse reception of status updates from this command unless + <varname>NotifyAccess=</varname> is set for the service unit this command is called from.</para> + + <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either + the sending process is still around at the time PID 1 processes the message, or if the sending process is + explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked + off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or + <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an + <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly + attribute the message to the unit, and thus will ignore it, even if + <varname>NotifyAccess=</varname><option>all</option> is set for it.</para> + + <para><command>systemd-notify</command> will first attempt to invoke <function>sd_notify()</function> pretending to + have the PID of the invoking process. This will only succeed when invoked with sufficient privileges. On failure, + it will then fall back to invoking it under its own PID. This behaviour is useful in order that when the tool is + invoked from a shell script the shell process — and not the <command>systemd-notify</command> process — appears as + sender of the message, which in turn is helpful if the shell process is the main process of a service, due to the + limitations of <varname>NotifyAccess=</varname><option>all</option> described above.</para> </refsect1> <refsect1> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 1ac5124aa3..5e44b1523d 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -250,7 +250,7 @@ command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>, <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - details. These options may not be combined with <option>--scope</option>.</para> + details. These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para> </listitem> </varlistentry> @@ -259,7 +259,7 @@ <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname> in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option may not be combined with <option>--scope</option>.</para> + option may not be combined with <option>--scope</option> or <option>--pty</option>.</para> </listitem> </varlistentry> diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml index a86b13daa8..b8a7800b82 100644 --- a/man/systemd-socket-proxyd.xml +++ b/man/systemd-socket-proxyd.xml @@ -135,8 +135,7 @@ server { </example> <example> <title>Enabling the proxy</title> - <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket -# systemctl start proxy-to-nginx.socket + <programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket $ curl http://localhost:80/]]></programlisting> </example> </refsect2> @@ -176,8 +175,7 @@ server { </example> <example> <title>Enabling the proxy</title> - <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket -# systemctl start proxy-to-nginx.socket + <programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket $ curl http://localhost:80/]]></programlisting> </example> </refsect2> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 8079b4b210..bb38ea2467 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1508,40 +1508,29 @@ <varlistentry> <term><varname>RestrictAddressFamilies=</varname></term> - <listitem><para>Restricts the set of socket address families - accessible to the processes of this unit. Takes a - space-separated list of address family names to whitelist, - such as - <constant>AF_UNIX</constant>, - <constant>AF_INET</constant> or - <constant>AF_INET6</constant>. When - prefixed with <constant>~</constant> the listed address - families will be applied as blacklist, otherwise as whitelist. - Note that this restricts access to the - <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call only. Sockets passed into the process by other - means (for example, by using socket activation with socket - units, see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - are unaffected. Also, sockets created with - <function>socketpair()</function> (which creates connected - AF_UNIX sockets only) are unaffected. Note that this option - has no effect on 32-bit x86 and is ignored (but works - correctly on x86-64). If running in user mode, or in system - mode, but without the <constant>CAP_SYS_ADMIN</constant> - capability (e.g. setting <varname>User=nobody</varname>), - <varname>NoNewPrivileges=yes</varname> is implied. By - default, no restriction applies, all address families are - accessible to processes. If assigned the empty string, any - previous list changes are undone.</para> - - <para>Use this option to limit exposure of processes to remote - systems, in particular via exotic network protocols. Note that - in most cases, the local <constant>AF_UNIX</constant> address - family should be included in the configured whitelist as it is - frequently used for local communication, including for + <listitem><para>Restricts the set of socket address families accessible to the processes of this unit. Takes a + space-separated list of address family names to whitelist, such as <constant>AF_UNIX</constant>, + <constant>AF_INET</constant> or <constant>AF_INET6</constant>. When prefixed with <constant>~</constant> the + listed address families will be applied as blacklist, otherwise as whitelist. Note that this restricts access + to the <citerefentry + project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call + only. Sockets passed into the process by other means (for example, by using socket activation with socket + units, see <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + are unaffected. Also, sockets created with <function>socketpair()</function> (which creates connected AF_UNIX + sockets only) are unaffected. Note that this option has no effect on 32-bit x86, s390, s390x, mips, mips-le, + ppc, ppc-le, pcc64, ppc64-le and is ignored (but works correctly on other architectures, including x86-64). If + running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> capability + (e.g. setting <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. By default, + no restrictions apply, all address families are accessible to processes. If assigned the empty string, any + previous address familiy restriction changes are undone. This setting does not affect commands prefixed with + <literal>+</literal>.</para> + + <para>Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive + network protocols, such as <constant>AF_PACKET</constant>. Note that in most cases, the local + <constant>AF_UNIX</constant> address family should be included in the configured whitelist as it is frequently + used for local communication, including for <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> - logging. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> + logging.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 522ed5e61e..627176750f 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -136,9 +136,10 @@ process it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The options specific to the <literal>[Service]</literal> section of service units are the following:</para> @@ -792,26 +793,26 @@ <varlistentry> <term><varname>NotifyAccess=</varname></term> - <listitem><para>Controls access to the service status - notification socket, as accessible via the - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call. Takes one of <option>none</option> (the default), - <option>main</option>, <option>exec</option> or - <option>all</option>. If <option>none</option>, no daemon status - updates are accepted from the service processes, all status - update messages are ignored. If <option>main</option>, only - service updates sent from the main process of the service are - accepted. If <option>exec</option>, only service updates sent - from any of the control processes originating from one of the - <varname>Exec*=</varname> commands are accepted. If - <option>all</option>, all services updates from all members of - the service's control group are accepted. This option should - be set to open access to the notification socket when using - <varname>Type=notify</varname> or - <varname>WatchdogSec=</varname> (see above). If those options - are used but <varname>NotifyAccess=</varname> is not - configured, it will be implicitly set to - <option>main</option>.</para></listitem> + <listitem><para>Controls access to the service status notification socket, as accessible via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> call. Takes one + of <option>none</option> (the default), <option>main</option>, <option>exec</option> or + <option>all</option>. If <option>none</option>, no daemon status updates are accepted from the service + processes, all status update messages are ignored. If <option>main</option>, only service updates sent from the + main process of the service are accepted. If <option>exec</option>, only service updates sent from any of the + main or control processes originating from one of the <varname>Exec*=</varname> commands are accepted. If + <option>all</option>, all services updates from all members of the service's control group are accepted. This + option should be set to open access to the notification socket when using <varname>Type=notify</varname> or + <varname>WatchdogSec=</varname> (see above). If those options are used but <varname>NotifyAccess=</varname> is + not configured, it will be implicitly set to <option>main</option>.</para> + + <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if + either the sending process is still around at the time PID 1 processes the message, or if the sending process + is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally + forked off the process, i.e. on all processes that match <option>main</option> or + <option>exec</option>. Conversely, if an auxiliary process of the unit sends an + <function>sd_notify()</function> message and immediately exits, the service manager might not be able to + properly attribute the message to the unit, and thus will ignore it, even if + <varname>NotifyAccess=</varname><option>all</option> is set for it.</para></listitem> </varlistentry> <varlistentry> |