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:
parent
a084b38789
commit
82651d5b6b
|
@ -1123,10 +1123,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Import all, one or more environment variables set on the client into the systemd manager
|
<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.
|
environment block. If a list of environment variable names is passed, client-side values are then
|
||||||
Otherwise, a list of one or more environment variable names should be passed, whose client-side
|
imported into the manager's environment block. If any names are not valid environment variable
|
||||||
values are then imported into the manager's environment block. This command will silently ignore
|
names or have invalid values according to the rules described above, an error is raised. If no
|
||||||
any assignments which do not conform to the rules listed above.</para>
|
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>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
|
@ -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
|
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>
|
(in case <varname>PAMName=</varname> is used).</para>
|
||||||
|
|
||||||
<para>
|
<para>See "Environment Variables in Spawned Processes" below for a description of how those
|
||||||
See <citerefentry
|
settings combine to form the inherited environment. See <citerefentry
|
||||||
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details
|
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for general
|
||||||
about environment variables.</para></listitem>
|
information about environment variables.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
@ -2809,7 +2809,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<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
|
<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
|
multiple sources. Processes started by the system service manager generally do not inherit environment variables
|
||||||
|
@ -2822,30 +2822,48 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem><para>Variables globally configured for the service manager, using the
|
<listitem><para>Variables globally configured for the service manager, using the
|
||||||
<varname>DefaultEnvironment=</varname> setting in
|
<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-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) or via
|
the kernel command line option <varname>systemd.setenv=</varname> understood by
|
||||||
<command>systemctl set-environment</command> (see <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para></listitem>
|
<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,
|
<listitem><para>Variables set by any PAM modules in case <varname>PAMName=</varname> is in effect,
|
||||||
cf. <citerefentry
|
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>
|
</itemizedlist>
|
||||||
|
|
||||||
<para>If the same environment variables are set by multiple of these sources, the later source — according to the
|
<para>If the same environment variable is set by multiple of these sources, the later source — according
|
||||||
order of the list above — wins. Note that as final step all variables listed in
|
to the order of the list above — wins. Note that as the final step all variables listed in
|
||||||
<varname>UnsetEnvironment=</varname> are removed again from the compiled environment variable list, immediately
|
<varname>UnsetEnvironment=</varname> are removed from the compiled environment variable list, immediately
|
||||||
before it is passed to the executed process.</para>
|
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
|
<para>The general philosophy is to expose a small curated list of environment variables to processes.
|
||||||
process:</para>
|
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'>
|
<variablelist class='environment-variables'>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -2854,22 +2872,21 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
|
||||||
<listitem><para>Colon-separated list of directories to use when launching
|
<listitem><para>Colon-separated list of directories to use when launching
|
||||||
executables. <command>systemd</command> uses a fixed value of
|
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>
|
<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
|
in the system manager. When compiled for systems with "unmerged <filename>/usr/</filename>"
|
||||||
not a symlink to <filename>/usr/bin</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
|
<literal>:<filename>/sbin</filename>:<filename>/bin</filename></literal> is appended. In case of
|
||||||
the user manager, a different path may be configured by the distribution. It is recommended to not
|
the the user manager, a different path may be configured by the distribution. It is recommended to
|
||||||
rely on the order of entries, and have only one program with a given name in
|
not rely on the order of entries, and have only one program with a given name in
|
||||||
<varname>$PATH</varname>.</para></listitem>
|
<varname>$PATH</varname>.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><varname>$LANG</varname></term>
|
<term><varname>$LANG</varname></term>
|
||||||
|
|
||||||
<listitem><para>Locale. Can be set in
|
<listitem><para>Locale. Can be set in <citerefentry
|
||||||
<citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
or on the kernel command line (see
|
or on the kernel command line (see
|
||||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
|
||||||
and
|
|
||||||
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
|
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -3200,16 +3217,14 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
|
||||||
</row>
|
</row>
|
||||||
</tbody>
|
</tbody>
|
||||||
</tgroup>
|
</tgroup>
|
||||||
</table>
|
</table></listitem>
|
||||||
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><varname>$PIDFILE</varname></term>
|
<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
|
<listitem><para>The path to the configured PID file, in case the process is forked off on behalf of
|
||||||
service that uses the <varname>PIDFile=</varname> setting, see
|
a service that uses the <varname>PIDFile=</varname> setting, see
|
||||||
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
<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
|
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
|
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
|
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
|
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>
|
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<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
|
<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
|
with the settings above. In that case the already created service process will exit with a non-zero exit code
|
||||||
|
|
Loading…
Reference in New Issue