Merge pull request #15472 from keszybz/dbus-api-docs

[thirdparty/systemd.git] / man / systemd.exec.xml

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index b7f44c9473d0cd3470ef9b89a9166503188ec0f3..3e2ae93bf0e60d857a347710b979b73710d1d97d 100644 (file)
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -70,6 +70,10 @@
       <option>syslog</option> or <option>kmsg</option> (or their combinations with console output, see below)
       automatically acquire dependencies of type <varname>After=</varname> on
       <filename>systemd-journald.socket</filename>.</para></listitem>
       <option>syslog</option> or <option>kmsg</option> (or their combinations with console output, see below)
       automatically acquire dependencies of type <varname>After=</varname> on
       <filename>systemd-journald.socket</filename>.</para></listitem>

+
+      <listitem><para>Units using <varname>LogNamespace=</varname> will automatically gain ordering and
+      requirement dependencies on the two socket units associated with
+      <filename>systemd-journald@.service</filename> instances.</para></listitem>

     </itemizedlist>
   </refsect1>
 
     </itemizedlist>
   </refsect1>
 


@@ -135,6 +139,9 @@
         <varname>PrivateDevices=</varname> below, as it may change the setting of
         <varname>DevicePolicy=</varname>.</para>
 
         <varname>PrivateDevices=</varname> below, as it may change the setting of
         <varname>DevicePolicy=</varname>.</para>
 

+        <para>Units making use of <varname>RootImage=</varname> automatically gain an
+        <varname>After=</varname> dependency on <filename>systemd-udevd.service</filename>.</para>
+

         <xi:include href="system-only.xml" xpointer="singular"/></listitem>
       </varlistentry>
 
         <xi:include href="system-only.xml" xpointer="singular"/></listitem>
       </varlistentry>
 


@@ -213,12 +220,15 @@
         is set, the default group of the user is used. This setting does not affect commands whose command line is
         prefixed with <literal>+</literal>.</para>
 
         is set, the default group of the user is used. This setting does not affect commands whose command line is
         prefixed with <literal>+</literal>.</para>
 

-        <para>Note that restrictions on the user/group name syntax are enforced: the specified name must consist only
-        of the characters a-z, A-Z, 0-9, <literal>_</literal> and <literal>-</literal>, except for the first character
-        which must be one of a-z, A-Z or <literal>_</literal> (i.e. numbers and <literal>-</literal> are not permitted
-        as first character). The user/group name must have at least one character, and at most 31. These restrictions
-        are enforced in order to avoid ambiguities and to ensure user/group names and unit files remain portable among
-        Linux systems.</para>
+        <para>Note that this enforces only weak restrictions on the user/group name syntax, but will generate
+        warnings in many cases where user/group names do not adhere to the following rules: the specified
+        name should consist only of the characters a-z, A-Z, 0-9, <literal>_</literal> and
+        <literal>-</literal>, except for the first character which must be one of a-z, A-Z and
+        <literal>_</literal> (i.e. digits and <literal>-</literal> are not permitted as first character). The
+        user/group name must have at least one character, and at most 31. These restrictions are made in
+        order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux
+        systems. For further details on the names accepted and the names warned about see <ulink
+        url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para>

 
         <para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is
         dynamically allocated at the time the service is started, and released at the time the service is
 
         <para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is
         dynamically allocated at the time the service is started, and released at the time the service is


@@ -648,8 +658,39 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         <term><varname>UMask=</varname></term>
 
         <listitem><para>Controls the file mode creation mask. Takes an access mode in octal notation. See
         <term><varname>UMask=</varname></term>
 
         <listitem><para>Controls the file mode creation mask. Takes an access mode in octal notation. See

-        <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details. Defaults
-        to 0022.</para></listitem>
+        <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+        details. Defaults to 0022 for system units. For units of the user service manager the default value
+        is inherited from the user instance (whose default is inherited from the system service manager, and
+        thus also is 0022). Hence changing the default value of a user instance, either via
+        <varname>UMask=</varname> or via a PAM module, will affect the user instance itself and all user
+        units started by the user instance unless a user unit has specified its own
+        <varname>UMask=</varname>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>CoredumpFilter=</varname></term>
+
+        <listitem><para>Controls which types of memory mappings will be saved if the process dumps core
+        (using the <filename>/proc/<replaceable>pid</replaceable>/coredump_filter</filename> file). Takes a
+        whitespace-separated combination of mapping type names or numbers (with the default base 16). Mapping
+        type names are <constant>private-anonymous</constant>, <constant>shared-anonymous</constant>,
+        <constant>private-file-backed</constant>, <constant>shared-file-backed</constant>,
+        <constant>elf-headers</constant>, <constant>private-huge</constant>,
+        <constant>shared-huge</constant>, <constant>private-dax</constant>, <constant>shared-dax</constant>,
+        and the special values <constant>all</constant> (all types) and <constant>default</constant> (the
+        kernel default of <literal><constant>private-anonymous</constant>
+        <constant>shared-anonymous</constant> <constant>elf-headers</constant>
+        <constant>private-huge</constant></literal>). See
+        <citerefentry><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the
+        meaning of the mapping types. When specified multiple times, all specified masks are ORed. When not
+        set, or if the empty value is assigned, the inherited value is not changed.</para>
+
+        <example>
+          <title>Add DAX pages to the dump filter</title>
+
+          <programlisting>CoredumpFilter=default private-dax shared-dax</programlisting>
+        </example>
+        </listitem>

       </varlistentry>
 
       <varlistentry>
       </varlistentry>
 
       <varlistentry>


@@ -770,10 +811,11 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         <term><varname>CPUAffinity=</varname></term>
 
         <listitem><para>Controls the CPU affinity of the executed processes. Takes a list of CPU indices or ranges
         <term><varname>CPUAffinity=</varname></term>
 
         <listitem><para>Controls the CPU affinity of the executed processes. Takes a list of CPU indices or ranges

-        separated by either whitespace or commas. CPU ranges are specified by the lower and upper CPU indices separated
-        by a dash. This option may be specified more than once, in which case the specified CPU affinity masks are
-        merged. If the empty string is assigned, the mask is reset, all assignments prior to this will have no
-        effect. See
+        separated by either whitespace or commas. Alternatively, takes a special "numa" value in which case systemd
+        automatically derives allowed CPU range based on the value of <varname>NUMAMask=</varname> option. CPU ranges
+        are specified by the lower and upper CPU indices separated by a dash. This option may be specified more than
+        once, in which case the specified CPU affinity masks are merged. If the empty string is assigned, the mask
+        is reset, all assignments prior to this will have no effect. See

         <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
         details.</para></listitem>
       </varlistentry>
         <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
         details.</para></listitem>
       </varlistentry>


@@ -1592,7 +1634,7 @@ RestrictNamespaces=~cgroup net</programlisting>
         points of the file system namespace created for each process of this unit. Other file system namespacing unit
         settings (see the discussion in <varname>PrivateMounts=</varname> above) will implicitly disable mount and
         unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount
         points of the file system namespace created for each process of this unit. Other file system namespacing unit
         settings (see the discussion in <varname>PrivateMounts=</varname> above) will implicitly disable mount and
         unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount

-        points in the unit's file system namepace to <option>slave</option> first. Setting this option to
+        points in the unit's file system namespace to <option>slave</option> first. Setting this option to

         <option>shared</option> does not reestablish propagation in that case.</para>
 
         <para>If not set – but file system namespaces are enabled through another file system namespace unit setting –
         <option>shared</option> does not reestablish propagation in that case.</para>
 
         <para>If not set – but file system namespaces are enabled through another file system namespace unit setting –


@@ -2254,6 +2296,36 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
         </para></listitem>
       </varlistentry>
 
         </para></listitem>
       </varlistentry>
 

+      <varlistentry>
+        <term><varname>LogNamespace=</varname></term>
+
+        <listitem><para>Run the unit's processes in the specified journal namespace. Expects a short
+        user-defined string identifying the namespace. If not used the processes of the service are run in
+        the default journal namespace, i.e. their log stream is collected and processed by
+        <filename>systemd-journald.service</filename>. If this option is used any log data generated by
+        processes of this unit (regardless if via the <function>syslog()</function>, journal native logging
+        or stdout/stderr logging) is collected and processed by an instance of the
+        <filename>systemd-journald@.service</filename> template unit, which manages the specified
+        namespace. The log data is stored in a data store independent from the default log namespace's data
+        store. See
+        <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        for details about journal namespaces.</para>
+
+        <para>Internally, journal namespaces are implemented through Linux mount namespacing and
+        over-mounting the directory that contains the relevant <constant>AF_UNIX</constant> sockets used for
+        logging in the unit's mount namespace. Since mount namespaces are used this setting disconnects
+        propagation of mounts from the unit's processes to the host, similar to how
+        <varname>ReadOnlyPaths=</varname> and similar settings (see above) work. Journal namespaces may hence
+        not be used for services that need to establish mount points on the host.</para>
+
+        <para>When this option is used the unit will automatically gain ordering and requirement dependencies
+        on the two socket units associated with the <filename>systemd-journald@.service</filename> instance
+        so that they are automatically established prior to the unit starting up. Note that when this option
+        is used log output of this service does not appear in the regular
+        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        output, unless the <option>--namespace=</option> option is used.</para></listitem>
+      </varlistentry>
+

       <varlistentry>
         <term><varname>SyslogIdentifier=</varname></term>
 
       <varlistentry>
         <term><varname>SyslogIdentifier=</varname></term>