<?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">
<!--
- This file is part of systemd.
+ SPDX-License-Identifier: LGPL-2.1+
- Copyright 2016 Red Hat, Inc.
- Copyright 2017 Zbigniew Jędrzejewski-Szmek
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
+ Copyright © 2016 Red Hat, Inc.
-->
<refentry id="environment.d" conditional='ENABLE_ENVIRONMENT_D'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>environment.d</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Ray</firstname>
- <surname>Strode</surname>
- <email>rstrode@redhat.com</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<refnamediv>
<refname>environment.d</refname>
- <refpurpose>Definition of user session environment</refpurpose>
+ <refpurpose>Definition of user service environment</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>The <filename>environment.d</filename> directories contain a list of "global" environment
- variable assignments for the user environment.
+ <para>The <filename>environment.d</filename> directories contain a list 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>
<literal>${<replaceable>FOO</replaceable>}</literal> would have expanded to a non-empty value.
No other elements of shell syntax are supported.</para>
- <para>Each<replaceable>KEY</replaceable> must be a valid variable name. Empty lines
+ <para>Each <replaceable>KEY</replaceable> must be a valid variable name. Empty lines
and lines beginning with the comment character <literal>#</literal> are ignored.</para>
<refsect2>
<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>
<programlisting>
FOO_DEBUG=force-software-gl,log-verbose
PATH=/opt/foo/bin:$PATH
- LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}/opt/foo/lib
+ LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/}
</programlisting>
</example>
</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>