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

Merge pull request #18137 from keszybz/deprecate-blanket-import-environment 

Deprecate blanket import-environment
This commit is contained in:
Yu Watanabe 2021-01-09 09:24:16 +09:00 committed by GitHub
parent a412ec5714 341992081b
commit 83f0ff1eda
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 397 additions and 358 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
man/systemctl.xml
View File

@ -1118,15 +1118,22 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
<varlistentry> <varlistentry>
<term> <term>
<command>import-environment</command> <command>import-environment</command>
<optional><replaceable>VARIABLE…</replaceable></optional> <replaceable>VARIABLE…</replaceable>
</term> </term>
<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>
<para>Importing of the full inherited environment block (calling this command without any
arguments) is deprecated. A shell will set dozens of variables which only make sense locally and
are only meant for processes which are descendants of the shell. Such variables in the global
environment block are confusing to other processes.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>

716
man/systemd.exec.xml
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 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,410 +2822,428 @@ 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. Importing all variables
inherited by the graphical session or by one of the user shells is strongly discouraged.</para>
<variablelist class='environment-variables'> <para>Hint: <command>systemd-run -P env</command> and <command>systemd-run --user -P env</command> print
<varlistentry> the effective system and user service environment blocks.</para>
<term><varname>$PATH</varname></term>
<listitem><para>Colon-separated list of directories to use when launching <refsect2>
executables. <command>systemd</command> uses a fixed value of <title>Environment Variables Set or Propagated by the Service Manager</title>
<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
<varname>$PATH</varname>.</para></listitem>
</varlistentry>
<varlistentry> <para>The following environment variables are propagated by the service manager or generated internally
<term><varname>$LANG</varname></term> for each invoked process:</para>
<listitem><para>Locale. Can be set in <variablelist class='environment-variables'>
<citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> <varlistentry>
or on the kernel command line (see <term><varname>$PATH</varname></term>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>Colon-separated list of directories to use when launching
<term><varname>$USER</varname></term> executables. <command>systemd</command> uses a fixed value of
<term><varname>$LOGNAME</varname></term> <literal><filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename></literal>
<term><varname>$HOME</varname></term> in the system manager. When compiled for systems with "unmerged <filename>/usr/</filename>"
<term><varname>$SHELL</varname></term> (<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>
<listitem><para>User name (twice), home directory, and the <varlistentry>
login shell. The variables are set for the units that have <term><varname>$LANG</varname></term>
<varname>User=</varname> set, which includes user
<command>systemd</command> instances. See
<citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>Locale. Can be set in <citerefentry
<term><varname>$INVOCATION_ID</varname></term> 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>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
</para></listitem>
</varlistentry>
<listitem><para>Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted <varlistentry>
as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into <term><varname>$USER</varname></term>
an activating or active state, and may be used to identify this specific runtime cycle, in particular in data <term><varname>$LOGNAME</varname></term>
stored offline, such as the journal. The same ID is passed to all processes run as part of the <term><varname>$HOME</varname></term>
unit.</para></listitem> <term><varname>$SHELL</varname></term>
</varlistentry>
<varlistentry> <listitem><para>User name (twice), home directory, and the
<term><varname>$XDG_RUNTIME_DIR</varname></term> login shell. The variables are set for the units that have
<varname>User=</varname> set, which includes user
<command>systemd</command> instances. See
<citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<listitem><para>The directory to use for runtime objects (such as IPC objects) and volatile state. Set for all <varlistentry>
services run by the user <command>systemd</command> instance, as well as any system services that use <term><varname>$INVOCATION_ID</varname></term>
<varname>PAMName=</varname> with a PAM stack that includes <command>pam_systemd</command>. See below and
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more
information.</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted
<term><varname>$RUNTIME_DIRECTORY</varname></term> as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into
<term><varname>$STATE_DIRECTORY</varname></term> an activating or active state, and may be used to identify this specific runtime cycle, in particular in data
<term><varname>$CACHE_DIRECTORY</varname></term> stored offline, such as the journal. The same ID is passed to all processes run as part of the
<term><varname>$LOGS_DIRECTORY</varname></term> unit.</para></listitem>
<term><varname>$CONFIGURATION_DIRECTORY</varname></term> </varlistentry>
<listitem><para>Absolute paths to the directories defined with <varlistentry>
<varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>, <term><varname>$XDG_RUNTIME_DIR</varname></term>
<varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and
<varname>ConfigurationDirectory=</varname> when those settings are used.</para>
</listitem>
</varlistentry>
<varlistentry> <listitem><para>The directory to use for runtime objects (such as IPC objects) and volatile state. Set for all
<term><varname>$CREDENTIALS_DIRECTORY</varname></term> services run by the user <command>systemd</command> instance, as well as any system services that use
<varname>PAMName=</varname> with a PAM stack that includes <command>pam_systemd</command>. See below and
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more
information.</para></listitem>
</varlistentry>
<listitem><para>An absolute path to the per-unit directory with credentials configured via <varlistentry>
<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>. The directory is marked <term><varname>$RUNTIME_DIRECTORY</varname></term>
read-only and is placed in unswappable memory (if supported and permitted), and is only accessible to <term><varname>$STATE_DIRECTORY</varname></term>
the UID associated with the unit via <varname>User=</varname> or <varname>DynamicUser=</varname> (and <term><varname>$CACHE_DIRECTORY</varname></term>
the superuser).</para></listitem> <term><varname>$LOGS_DIRECTORY</varname></term>
</varlistentry> <term><varname>$CONFIGURATION_DIRECTORY</varname></term>
<varlistentry> <listitem><para>Absolute paths to the directories defined with
<term><varname>$MAINPID</varname></term> <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>,
<varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and
<varname>ConfigurationDirectory=</varname> when those settings are used.</para>
</listitem>
</varlistentry>
<listitem><para>The PID of the unit's main process if it is <varlistentry>
known. This is only set for control processes as invoked by <term><varname>$CREDENTIALS_DIRECTORY</varname></term>
<varname>ExecReload=</varname> and similar. </para></listitem>
</varlistentry>
<varlistentry> <listitem><para>An absolute path to the per-unit directory with credentials configured via
<term><varname>$MANAGERPID</varname></term> <varname>LoadCredential=</varname>/<varname>SetCredential=</varname>. The directory is marked
read-only and is placed in unswappable memory (if supported and permitted), and is only accessible to
the UID associated with the unit via <varname>User=</varname> or <varname>DynamicUser=</varname> (and
the superuser).</para></listitem>
</varlistentry>
<listitem><para>The PID of the user <command>systemd</command> <varlistentry>
instance, set for processes spawned by it. </para></listitem> <term><varname>$MAINPID</varname></term>
</varlistentry>
<varlistentry> <listitem><para>The PID of the unit's main process if it is
<term><varname>$LISTEN_FDS</varname></term> known. This is only set for control processes as invoked by
<term><varname>$LISTEN_PID</varname></term> <varname>ExecReload=</varname> and similar. </para></listitem>
<term><varname>$LISTEN_FDNAMES</varname></term> </varlistentry>
<listitem><para>Information about file descriptors passed to a <varlistentry>
service for socket activation. See <term><varname>$MANAGERPID</varname></term>
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>The PID of the user <command>systemd</command>
<term><varname>$NOTIFY_SOCKET</varname></term> instance, set for processes spawned by it. </para></listitem>
</varlistentry>
<listitem><para>The socket <varlistentry>
<function>sd_notify()</function> talks to. See <term><varname>$LISTEN_FDS</varname></term>
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <term><varname>$LISTEN_PID</varname></term>
</para></listitem> <term><varname>$LISTEN_FDNAMES</varname></term>
</varlistentry>
<varlistentry> <listitem><para>Information about file descriptors passed to a
<term><varname>$WATCHDOG_PID</varname></term> service for socket activation. See
<term><varname>$WATCHDOG_USEC</varname></term> <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<listitem><para>Information about watchdog keep-alive notifications. See <varlistentry>
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <term><varname>$NOTIFY_SOCKET</varname></term>
</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>The socket
<term><varname>$TERM</varname></term> <function>sd_notify()</function> talks to. See
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<listitem><para>Terminal type, set only for units connected to <varlistentry>
a terminal (<varname>StandardInput=tty</varname>, <term><varname>$WATCHDOG_PID</varname></term>
<varname>StandardOutput=tty</varname>, or <term><varname>$WATCHDOG_USEC</varname></term>
<varname>StandardError=tty</varname>). See
<citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>Information about watchdog keep-alive notifications. See
<term><varname>$LOG_NAMESPACE</varname></term> <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<listitem><para>Contains the name of the selected logging namespace when the <varlistentry>
<varname>LogNamespace=</varname> service setting is used.</para></listitem> <term><varname>$TERM</varname></term>
</varlistentry>
<varlistentry> <listitem><para>Terminal type, set only for units connected to
<term><varname>$JOURNAL_STREAM</varname></term> a terminal (<varname>StandardInput=tty</varname>,
<varname>StandardOutput=tty</varname>, or
<varname>StandardError=tty</varname>). See
<citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<listitem><para>If the standard output or standard error output of the executed processes are connected to the <varlistentry>
journal (for example, by setting <varname>StandardError=journal</varname>) <varname>$JOURNAL_STREAM</varname> <term><varname>$LOG_NAMESPACE</varname></term>
contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a
colon (<literal>:</literal>). This permits invoked processes to safely detect whether their standard output or
standard error output are connected to the journal. The device and inode numbers of the file descriptors should
be compared with the values set in the environment variable to determine whether the process output is still
connected to the journal. Note that it is generally not sufficient to only check whether
<varname>$JOURNAL_STREAM</varname> is set at all as services might invoke external processes replacing their
standard output or standard error output, without unsetting the environment variable.</para>
<para>If both standard output and standard error of the executed processes are connected to the journal via a <listitem><para>Contains the name of the selected logging namespace when the
stream socket, this environment variable will contain information about the standard error stream, as that's <varname>LogNamespace=</varname> service setting is used.</para></listitem>
usually the preferred destination for log data. (Note that typically the same stream is used for both standard </varlistentry>
output and standard error, hence very likely the environment variable contains device and inode information
matching both stream file descriptors.)</para>
<para>This environment variable is primarily useful to allow services to optionally upgrade their used log <varlistentry>
protocol to the native journal protocol (using <term><varname>$JOURNAL_STREAM</varname></term>
<citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other
functions) if their standard output or standard error output is connected to the journal anyway, thus enabling
delivery of structured metadata along with logged messages.</para></listitem>
</varlistentry>
<varlistentry> <listitem><para>If the standard output or standard error output of the executed processes are connected to the
<term><varname>$SERVICE_RESULT</varname></term> journal (for example, by setting <varname>StandardError=journal</varname>) <varname>$JOURNAL_STREAM</varname>
contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a
colon (<literal>:</literal>). This permits invoked processes to safely detect whether their standard output or
standard error output are connected to the journal. The device and inode numbers of the file descriptors should
be compared with the values set in the environment variable to determine whether the process output is still
connected to the journal. Note that it is generally not sufficient to only check whether
<varname>$JOURNAL_STREAM</varname> is set at all as services might invoke external processes replacing their
standard output or standard error output, without unsetting the environment variable.</para>
<listitem><para>Only defined for the service unit type, this environment variable is passed to all <para>If both standard output and standard error of the executed processes are connected to the journal via a
<varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service stream socket, this environment variable will contain information about the standard error stream, as that's
"result". Currently, the following values are defined:</para> usually the preferred destination for log data. (Note that typically the same stream is used for both standard
output and standard error, hence very likely the environment variable contains device and inode information
matching both stream file descriptors.)</para>
<table> <para>This environment variable is primarily useful to allow services to optionally upgrade their used log
<title>Defined <varname>$SERVICE_RESULT</varname> values</title> protocol to the native journal protocol (using
<tgroup cols='2'> <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other
<colspec colname='result'/> functions) if their standard output or standard error output is connected to the journal anyway, thus enabling
<colspec colname='meaning'/> delivery of structured metadata along with logged messages.</para></listitem>
<thead> </varlistentry>
<row>
<entry>Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody> <varlistentry>
<row> <term><varname>$SERVICE_RESULT</varname></term>
<entry><literal>success</literal></entry>
<entry>The service ran successfully and exited cleanly.</entry>
</row>
<row>
<entry><literal>protocol</literal></entry>
<entry>A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its <varname>Type=</varname> setting).</entry>
</row>
<row>
<entry><literal>timeout</literal></entry>
<entry>One of the steps timed out.</entry>
</row>
<row>
<entry><literal>exit-code</literal></entry>
<entry>Service process exited with a non-zero exit code; see <varname>$EXIT_CODE</varname> below for the actual exit code returned.</entry>
</row>
<row>
<entry><literal>signal</literal></entry>
<entry>A service process was terminated abnormally by a signal, without dumping core. See <varname>$EXIT_CODE</varname> below for the actual signal causing the termination.</entry>
</row>
<row>
<entry><literal>core-dump</literal></entry>
<entry>A service process terminated abnormally with a signal and dumped core. See <varname>$EXIT_CODE</varname> below for the signal causing the termination.</entry>
</row>
<row>
<entry><literal>watchdog</literal></entry>
<entry>Watchdog keep-alive ping was enabled for the service, but the deadline was missed.</entry>
</row>
<row>
<entry><literal>start-limit-hit</literal></entry>
<entry>A start limit was defined for the unit and it was hit, causing the unit to fail to start. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> for details.</entry>
</row>
<row>
<entry><literal>resources</literal></entry>
<entry>A catch-all condition in case a system operation failed.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This environment variable is useful to monitor failure or successful termination of a service. Even <listitem><para>Only defined for the service unit type, this environment variable is passed to all
though this variable is available in both <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>, it <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service
is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services "result". Currently, the following values are defined:</para>
that managed to start up correctly, and the latter covers both services that failed during their start-up and
those which failed during their runtime.</para></listitem>
</varlistentry>
<varlistentry> <table>
<term><varname>$EXIT_CODE</varname></term> <title>Defined <varname>$SERVICE_RESULT</varname> values</title>
<term><varname>$EXIT_STATUS</varname></term> <tgroup cols='2'>
<colspec colname='result'/>
<colspec colname='meaning'/>
<thead>
<row>
<entry>Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<listitem><para>Only defined for the service unit type, these environment variables are passed to all <tbody>
<varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code <row>
information of the main process of the service. For the precise definition of the exit code and status, see <entry><literal>success</literal></entry>
<citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname> <entry>The service ran successfully and exited cleanly.</entry>
is one of <literal>exited</literal>, <literal>killed</literal>, </row>
<literal>dumped</literal>. <varname>$EXIT_STATUS</varname> contains the numeric exit code formatted as string <row>
if <varname>$EXIT_CODE</varname> is <literal>exited</literal>, and the signal name in all other cases. Note <entry><literal>protocol</literal></entry>
that these environment variables are only set if the service manager succeeded to start and identify the main <entry>A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its <varname>Type=</varname> setting).</entry>
process of the service.</para> </row>
<row>
<entry><literal>timeout</literal></entry>
<entry>One of the steps timed out.</entry>
</row>
<row>
<entry><literal>exit-code</literal></entry>
<entry>Service process exited with a non-zero exit code; see <varname>$EXIT_CODE</varname> below for the actual exit code returned.</entry>
</row>
<row>
<entry><literal>signal</literal></entry>
<entry>A service process was terminated abnormally by a signal, without dumping core. See <varname>$EXIT_CODE</varname> below for the actual signal causing the termination.</entry>
</row>
<row>
<entry><literal>core-dump</literal></entry>
<entry>A service process terminated abnormally with a signal and dumped core. See <varname>$EXIT_CODE</varname> below for the signal causing the termination.</entry>
</row>
<row>
<entry><literal>watchdog</literal></entry>
<entry>Watchdog keep-alive ping was enabled for the service, but the deadline was missed.</entry>
</row>
<row>
<entry><literal>start-limit-hit</literal></entry>
<entry>A start limit was defined for the unit and it was hit, causing the unit to fail to start. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> for details.</entry>
</row>
<row>
<entry><literal>resources</literal></entry>
<entry>A catch-all condition in case a system operation failed.</entry>
</row>
</tbody>
</tgroup>
</table>
<table> <para>This environment variable is useful to monitor failure or successful termination of a service. Even
<title>Summary of possible service result variable values</title> though this variable is available in both <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>, it
<tgroup cols='3'> is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services
<colspec colname='result' /> that managed to start up correctly, and the latter covers both services that failed during their start-up and
<colspec colname='code' /> those which failed during their runtime.</para></listitem>
<colspec colname='status' /> </varlistentry>
<thead>
<row>
<entry><varname>$SERVICE_RESULT</varname></entry>
<entry><varname>$EXIT_CODE</varname></entry>
<entry><varname>$EXIT_STATUS</varname></entry>
</row>
</thead>
<tbody> <varlistentry>
<row> <term><varname>$EXIT_CODE</varname></term>
<entry morerows="1" valign="top"><literal>success</literal></entry> <term><varname>$EXIT_STATUS</varname></term>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>HUP</literal>, <literal>INT</literal>, <literal>TERM</literal>, <literal>PIPE</literal></entry>
</row>
<row>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry morerows="1" valign="top"><literal>protocol</literal></entry>
<entry valign="top">not set</entry>
<entry>not set</entry>
</row>
<row>
<entry><literal>exited</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry morerows="1" valign="top"><literal>timeout</literal></entry>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>TERM</literal>, <literal>KILL</literal></entry>
</row>
<row>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
<row>
<entry valign="top"><literal>exit-code</literal></entry>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
<row>
<entry valign="top"><literal>signal</literal></entry>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry>
</row>
<row>
<entry valign="top"><literal>core-dump</literal></entry>
<entry valign="top"><literal>dumped</literal></entry>
<entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry>
</row>
<row>
<entry morerows="2" valign="top"><literal>watchdog</literal></entry>
<entry><literal>dumped</literal></entry>
<entry><literal>ABRT</literal></entry>
</row>
<row>
<entry><literal>killed</literal></entry>
<entry><literal>TERM</literal>, <literal>KILL</literal></entry>
</row>
<row>
<entry><literal>exited</literal></entry>
<entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
<row>
<entry valign="top"><literal>exec-condition</literal></entry>
<entry><literal>exited</literal></entry>
<entry><literal>1</literal>, <literal>2</literal>, <literal>3</literal>, <literal
>4</literal>, …, <literal>254</literal></entry>
</row>
<row>
<entry valign="top"><literal>oom-kill</literal></entry>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>TERM</literal>, <literal>KILL</literal></entry>
</row>
<row>
<entry><literal>start-limit-hit</literal></entry>
<entry>not set</entry>
<entry>not set</entry>
</row>
<row>
<entry><literal>resources</literal></entry>
<entry>any of the above</entry>
<entry>any of the above</entry>
</row>
<row>
<entry namest="results" nameend="status">Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included. Moreover, using <varname>SuccessExitStatus=</varname> additional exit statuses may be declared to indicate clean termination, which is not reflected by this table.</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem> <listitem><para>Only defined for the service unit type, these environment variables are passed to all
</varlistentry> <varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code
information of the main process of the service. For the precise definition of the exit code and status, see
<citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname>
is one of <literal>exited</literal>, <literal>killed</literal>,
<literal>dumped</literal>. <varname>$EXIT_STATUS</varname> contains the numeric exit code formatted as string
if <varname>$EXIT_CODE</varname> is <literal>exited</literal>, and the signal name in all other cases. Note
that these environment variables are only set if the service manager succeeded to start and identify the main
process of the service.</para>
<varlistentry> <table>
<term><varname>$PIDFILE</varname></term> <title>Summary of possible service result variable values</title>
<tgroup cols='3'>
<colspec colname='result' />
<colspec colname='code' />
<colspec colname='status' />
<thead>
<row>
<entry><varname>$SERVICE_RESULT</varname></entry>
<entry><varname>$EXIT_CODE</varname></entry>
<entry><varname>$EXIT_STATUS</varname></entry>
</row>
</thead>
<listitem><para>The path to the configured PID file, in case the process is forked off on behalf of a <tbody>
service that uses the <varname>PIDFile=</varname> setting, see <row>
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> <entry morerows="1" valign="top"><literal>success</literal></entry>
for details. Service code may use this environment variable to automatically generate a PID file at <entry valign="top"><literal>killed</literal></entry>
the location configured in the unit file. This field is set to an absolute path in the file <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>TERM</literal>, <literal>PIPE</literal></entry>
system.</para></listitem> </row>
</varlistentry> <row>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry morerows="1" valign="top"><literal>protocol</literal></entry>
<entry valign="top">not set</entry>
<entry>not set</entry>
</row>
<row>
<entry><literal>exited</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry morerows="1" valign="top"><literal>timeout</literal></entry>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>TERM</literal>, <literal>KILL</literal></entry>
</row>
<row>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
<row>
<entry valign="top"><literal>exit-code</literal></entry>
<entry valign="top"><literal>exited</literal></entry>
<entry><literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
<row>
<entry valign="top"><literal>signal</literal></entry>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry>
</row>
<row>
<entry valign="top"><literal>core-dump</literal></entry>
<entry valign="top"><literal>dumped</literal></entry>
<entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry>
</row>
<row>
<entry morerows="2" valign="top"><literal>watchdog</literal></entry>
<entry><literal>dumped</literal></entry>
<entry><literal>ABRT</literal></entry>
</row>
<row>
<entry><literal>killed</literal></entry>
<entry><literal>TERM</literal>, <literal>KILL</literal></entry>
</row>
<row>
<entry><literal>exited</literal></entry>
<entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal
>3</literal>, …, <literal>255</literal></entry>
</row>
<row>
<entry valign="top"><literal>exec-condition</literal></entry>
<entry><literal>exited</literal></entry>
<entry><literal>1</literal>, <literal>2</literal>, <literal>3</literal>, <literal
>4</literal>, …, <literal>254</literal></entry>
</row>
<row>
<entry valign="top"><literal>oom-kill</literal></entry>
<entry valign="top"><literal>killed</literal></entry>
<entry><literal>TERM</literal>, <literal>KILL</literal></entry>
</row>
<row>
<entry><literal>start-limit-hit</literal></entry>
<entry>not set</entry>
<entry>not set</entry>
</row>
<row>
<entry><literal>resources</literal></entry>
<entry>any of the above</entry>
<entry>any of the above</entry>
</row>
<row>
<entry namest="results" nameend="status">Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included. Moreover, using <varname>SuccessExitStatus=</varname> additional exit statuses may be declared to indicate clean termination, which is not reflected by this table.</entry>
</row>
</tbody>
</tgroup>
</table></listitem>
</varlistentry>
</variablelist> <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
<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
system.</para></listitem>
</varlistentry>
</variablelist>
<para>For system services, when <varname>PAMName=</varname> is enabled and <command>pam_systemd</command> is part
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>
<para>For system services, when <varname>PAMName=</varname> is enabled and <command>pam_systemd</command> is part
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>
</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

11
shell-completion/bash/systemctl.in
View File

@ -320,11 +320,20 @@ _systemctl () {
elif __contains_word "$verb" ${VERBS[JOBS]}; then elif __contains_word "$verb" ${VERBS[JOBS]}; then
comps=$( __systemctl $mode list-jobs | { while read -r a b; do echo " $a"; done; } ) comps=$( __systemctl $mode list-jobs | { while read -r a b; do echo " $a"; done; } )
elif __contains_word "$verb" ${VERBS[ENVS]}; then elif [ "$verb" = 'unset-environment' ]; then
comps=$( __systemctl $mode show-environment \
| while read -r line; do echo " ${line%%=*}"; done )
compopt -o nospace
elif [ "$verb" = 'set-environment' ]; then
comps=$( __systemctl $mode show-environment \ comps=$( __systemctl $mode show-environment \
| while read -r line; do echo " ${line%%=*}="; done ) | while read -r line; do echo " ${line%%=*}="; done )
compopt -o nospace compopt -o nospace
elif [ "$verb" = 'import-environment' ]; then
COMPREPLY=( $(compgen -A variable -- "$cur_orig") )
return 0
elif __contains_word "$verb" ${VERBS[FILE]}; then elif __contains_word "$verb" ${VERBS[FILE]}; then
comps=$( compgen -A file -- "$cur" ) comps=$( compgen -A file -- "$cur" )
compopt -o filenames compopt -o filenames

5
shell-completion/zsh/_systemctl.in
View File

@ -365,6 +365,11 @@ for fun in set-environment unset-environment ; do
} }
done done
(( $+functions[_systemctl_import-environment] )) || _systemctl_import-environment()
{
_parameters
}
(( $+functions[_systemctl_link] )) || _systemctl_link() { (( $+functions[_systemctl_link] )) || _systemctl_link() {
_sd_unit_files _sd_unit_files
} }

4
src/systemctl/systemctl-set-environment.c
View File

@ -119,9 +119,9 @@ int import_environment(int argc, char *argv[], void *userdata) {
return bus_log_create_error(r); return bus_log_create_error(r);
if (argc < 2) { if (argc < 2) {
_cleanup_strv_free_ char **copy = NULL; log_warning("Calling import-environment without a list of variable names is deprecated.");
copy = strv_copy(environ); _cleanup_strv_free_ char **copy = strv_copy(environ);
if (!copy) if (!copy)
return log_oom(); return log_oom();

2
src/systemctl/systemctl.c
View File

@ -193,7 +193,7 @@ static int systemctl_help(void) {
" show-environment Dump environment\n" " show-environment Dump environment\n"
" set-environment VARIABLE=VALUE... Set one or more environment variables\n" " set-environment VARIABLE=VALUE... Set one or more environment variables\n"
" unset-environment VARIABLE... Unset one or more environment variables\n" " unset-environment VARIABLE... Unset one or more environment variables\n"
" import-environment [VARIABLE...] Import all or some environment variables\n" " import-environment VARIABLE... Import all or some environment variables\n"
"\n%3$sManager State Commands:%4$s\n" "\n%3$sManager State Commands:%4$s\n"
" daemon-reload Reload systemd manager configuration\n" " daemon-reload Reload systemd manager configuration\n"
" daemon-reexec Reexecute systemd manager\n" " daemon-reexec Reexecute systemd manager\n"