man: improve description of environment block creation

This adds a general description of "philosphy" of keeping the environemnt
block small and hints about systemd-run -P env.

The list of generated variables is split out to a subsection. Viewing
the patch with ignoring whitespace changes is recommended.

We don't ignore invalid assignments (except in import-environment to some
extent), previous description was wrong.

For https://bugzilla.redhat.com/show_bug.cgi?id=1912046#c17.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2021-01-05 11:17:14 +01:00
parent a084b38789
commit 82651d5b6b
2 changed files with 372 additions and 353 deletions

View File

@ -1123,10 +1123,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
<listitem>
<para>Import all, one or more environment variables set on the client into the systemd manager
environment block. If no arguments are passed, the entire environment block is imported.
Otherwise, a list of one or more environment variable names should be passed, whose client-side
values are then imported into the manager's environment block. This command will silently ignore
any assignments which do not conform to the rules listed above.</para>
environment block. If a list of environment variable names is passed, client-side values are then
imported into the manager's environment block. If any names are not valid environment variable
names or have invalid values according to the rules described above, an error is raised. If no
arguments are passed, the entire environment block inherited by the <command>systemctl</command>
process is imported. In this mode, any inherited invalid environment variables are quietly
ignored.</para>
</listitem>
</varlistentry>
</variablelist>

View File

@ -2304,10 +2304,10 @@ SystemCallErrorNumber=EPERM</programlisting>
set by the service manager itself (such as <varname>$NOTIFY_SOCKET</varname> and such), or set by a PAM module
(in case <varname>PAMName=</varname> is used).</para>
<para>
See <citerefentry
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details
about environment variables.</para></listitem>
<para>See "Environment Variables in Spawned Processes" below for a description of how those
settings combine to form the inherited environment. See <citerefentry
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for general
information about environment variables.</para></listitem>
</varlistentry>
</variablelist>
@ -2809,7 +2809,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
</refsect1>
<refsect1>
<title>Environment variables in spawned processes</title>
<title>Environment Variables in Spawned Processes</title>
<para>Processes started by the service manager are executed with an environment variable block assembled from
multiple sources. Processes started by the system service manager generally do not inherit environment variables
@ -2822,30 +2822,48 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
<itemizedlist>
<listitem><para>Variables globally configured for the service manager, using the
<varname>DefaultEnvironment=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the kernel command line option <varname>systemd.setenv=</varname> (see
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) or via
<command>systemctl set-environment</command> (see <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para></listitem>
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
the kernel command line option <varname>systemd.setenv=</varname> understood by
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or via
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<command>set-environment</command> verb.</para></listitem>
<listitem><para>Variables defined by the service manager itself (see the list below)</para></listitem>
<listitem><para>Variables defined by the service manager itself (see the list below).</para></listitem>
<listitem><para>Variables set in the service manager's own environment variable block (subject to <varname>PassEnvironment=</varname> for the system service manager)</para></listitem>
<listitem><para>Variables set in the service manager's own environment variable block (subject to
<varname>PassEnvironment=</varname> for the system service manager).</para></listitem>
<listitem><para>Variables set via <varname>Environment=</varname> in the unit file</para></listitem>
<listitem><para>Variables set via <varname>Environment=</varname> in the unit file.</para></listitem>
<listitem><para>Variables read from files specified via <varname>EnvironmentFile=</varname> in the unit file</para></listitem>
<listitem><para>Variables read from files specified via <varname>EnvironmentFile=</varname> in the unit
file.</para></listitem>
<listitem><para>Variables set by any PAM modules in case <varname>PAMName=</varname> is in effect,
cf. <citerefentry
project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry></para></listitem>
project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para></listitem>
</itemizedlist>
<para>If the same environment variables are set by multiple of these sources, the later source — according to the
order of the list above — wins. Note that as final step all variables listed in
<varname>UnsetEnvironment=</varname> are removed again from the compiled environment variable list, immediately
<para>If the same environment variable is set by multiple of these sources, the later source — according
to the order of the list above — wins. Note that as the final step all variables listed in
<varname>UnsetEnvironment=</varname> are removed from the compiled environment variable list, immediately
before it is passed to the executed process.</para>
<para>The following environment variables are set or propagated by the service manager for each invoked
process:</para>
<para>The general philosophy is to expose a small curated list of environment variables to processes.
Services started by the system manager (PID 1) will be started, without additional service-specific
configuration, with just a few environment variables. The user manager inherits environment variables as
any other system service, but in addition may receive additional environment variables from PAM, and,
typically, additional imported variables when the user starts a graphical session. It is recommended to
keep the environment blocks in both the system and user managers managers lean.</para>
<para>Hint: <command>systemd-run -P env</command> and <command>systemd-run --user -P env</command> print
the effective system and user service environment blocks.</para>
<refsect2>
<title>Environment Variables Set or Propagated by the Service Manager</title>
<para>The following environment variables are propagated by the service manager or generated internally
for each invoked process:</para>
<variablelist class='environment-variables'>
<varlistentry>
@ -2854,22 +2872,21 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
<listitem><para>Colon-separated list of directories to use when launching
executables. <command>systemd</command> uses a fixed value of
<literal><filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename></literal>
in the system manager. When compiled for systems with "unmerged /usr" (<filename>/bin</filename> is
not a symlink to <filename>/usr/bin</filename>),
<literal>:<filename>/sbin</filename>:<filename>/bin</filename></literal> is appended. In case of the
the user manager, a different path may be configured by the distribution. It is recommended to not
rely on the order of entries, and have only one program with a given name in
in the system manager. When compiled for systems with "unmerged <filename>/usr/</filename>"
(<filename>/bin</filename> is not a symlink to <filename>/usr/bin</filename>),
<literal>:<filename>/sbin</filename>:<filename>/bin</filename></literal> is appended. In case of
the the user manager, a different path may be configured by the distribution. It is recommended to
not rely on the order of entries, and have only one program with a given name in
<varname>$PATH</varname>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$LANG</varname></term>
<listitem><para>Locale. Can be set in
<citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<listitem><para>Locale. Can be set in <citerefentry
project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
or on the kernel command line (see
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
</para></listitem>
</varlistentry>
@ -3200,16 +3217,14 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
</row>
</tbody>
</tgroup>
</table>
</listitem>
</table></listitem>
</varlistentry>
<varlistentry>
<term><varname>$PIDFILE</varname></term>
<listitem><para>The path to the configured PID file, in case the process is forked off on behalf of a
service that uses the <varname>PIDFile=</varname> setting, see
<listitem><para>The path to the configured PID file, in case the process is forked off on behalf of
a service that uses the <varname>PIDFile=</varname> setting, see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. Service code may use this environment variable to automatically generate a PID file at
the location configured in the unit file. This field is set to an absolute path in the file
@ -3222,10 +3237,12 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
of the selected PAM stack, additional environment variables defined by systemd may be set for
services. Specifically, these are <varname>$XDG_SEAT</varname>, <varname>$XDG_VTNR</varname>, see
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Process exit codes</title>
<title>Process Exit Codes</title>
<para>When invoking a unit process the service manager possibly fails to apply the execution parameters configured
with the settings above. In that case the already created service process will exit with a non-zero exit code