udev: fix codesonar warnings

[thirdparty/systemd.git] / man / environment.d.xml

diff --git a/man/environment.d.xml b/man/environment.d.xml
index 2257dcb04c9856384972254fc9bd7fa2a445023b..0f53b0fef106780c6b58de53089c3cd155f5af69 100644 (file)
--- a/man/environment.d.xml
+++ b/man/environment.d.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0"?>
 <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!--
   SPDX-License-Identifier: LGPL-2.1+
 
@@ -21,7 +22,7 @@
 
   <refnamediv>
     <refname>environment.d</refname>
-    <refpurpose>Definition of user session environment</refpurpose>
+    <refpurpose>Definition of user service environment</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -35,11 +36,11 @@
   <refsect1>
     <title>Description</title>
 
-    <para>The <filename>environment.d</filename> directories contain a list of "global" environment
-    variable assignments for the user environment.
+    <para>Configuration files in the <filename>environment.d/</filename> directories contain lists of
+    environment variable assignments for services started by the systemd user instance.
     <citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    parses them and updates the environment exported by the systemd user instance to the services it
-    starts.</para>
+    parses them and updates the environment exported by the systemd user instance. See below for an
+    discussion of which processes inherit those variables.</para>
 
     <para>It is recommended to use numerical prefixes for file names to simplify ordering.</para>
 
@@ -57,7 +58,6 @@
     variable assignments, separated by newlines. The right hand side of these assignments may
     reference previously defined environment variables, using the <literal>${OTHER_KEY}</literal>
     and <literal>$OTHER_KEY</literal> format. It is also possible to use
-
     <literal>${<replaceable>FOO</replaceable>:-<replaceable>DEFAULT_VALUE</replaceable>}</literal>
     to expand in the same way as <literal>${<replaceable>FOO</replaceable>}</literal> unless the
     expansion would be empty, in which case it expands to <replaceable>DEFAULT_VALUE</replaceable>,
@@ -74,7 +74,7 @@
       <title>Example</title>
       <example>
         <title>Setup environment to allow access to a program installed in
-        <filename noindex='true'>/opt/foo</filename></title>
+        <filename index="false">/opt/foo</filename></title>
 
         <para><filename>/etc/environment.d/60-foo.conf</filename>:
         </para>
@@ -88,6 +88,33 @@
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Applicability</title>
+
+    <para>Environment variables exported by the user manager (<command>systemd --user</command> instance
+    started in the <filename>user@<replaceable>uid</replaceable>.service</filename> system service) apply to
+    any services started by that manager. In particular, this may include services which run user shells. For
+    example in the GNOME environment, the graphical terminal emulator runs as the
+    <filename>gnome-terminal-server.service</filename> user unit, which in turn runs the user shell, so that
+    shell will inherit environment variables exported by the user manager. For other instances of the shell,
+    not launched by the user manager, the environment they inherit is defined by the program that starts
+    them. Hint: in general,
+    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    units contain programs launched by systemd, and
+    <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    units contain programs launched by something else.</para>
+
+    <para>Specifically, for ssh logins, the
+    <citerefentry project='die-net'><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    service builds an environment that is a combination of variables forwarded from the remote system and
+    defined by <command>sshd</command>, see the discussion in
+    <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+    A graphical display session will have an analogous mechanism to define the environment. Note that some
+    managers query the systemd user instance for the exported environment and inject this configuration into
+    programs they start, using <command>systemctl show-environment</command> or the underlying D-Bus call.
+    </para>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>