Debian Codegraph @

upstream/debian-unstable/man5/environment.d.5

raw
1 '\" t
2 .TH "ENVIRONMENT\&.D" "5" "" "systemd 261~rc3" "environment.d"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 environment.d \- Definition of user service environment
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 ~/\&.config/environment\&.d/*\&.conf
28 .RE
29 .RS 4
30 /etc/environment\&.d/*\&.conf
31 .RE
32 .RS 4
33 /run/environment\&.d/*\&.conf
34 .RE
35 .RS 4
36 /usr/local/lib/environment\&.d/*\&.conf
37 .RE
38 .RS 4
39 /usr/lib/environment\&.d/*\&.conf
40 .RE
41 .RS 4
42 /etc/environment
43 .RE
44 .SH "DESCRIPTION"
45 .PP
46 Configuration files in the
47 environment\&.d/
48 directories contain lists of environment variable assignments passed to services started by the systemd user instance\&.
49 \fBsystemd-environment-d-generator\fR(8)
50 parses them and updates the environment exported by the systemd user instance\&. See below for an discussion of which processes inherit those variables\&.
51 .PP
52 It is recommended to use numerical prefixes for file names to simplify ordering\&.
53 .PP
54 For backwards compatibility, a symlink to
55 /etc/environment
56 is installed, so this file is also parsed\&.
57 .SH "CONFIGURATION DIRECTORIES AND PRECEDENCE"
58 .PP
59 Configuration files are read from directories in
60 /etc/,
61 /run/,
62 /usr/local/lib/, and
63 /usr/lib/, in order of precedence, as listed in the SYNOPSIS section above\&. Files must have the
64 "\&.conf"
65 extension\&. Files in
66 /etc/
67 override files with the same name in
68 /run/,
69 /usr/local/lib/, and
70 /usr/lib/\&. Files in
71 /run/
72 override files with the same name under
73 /usr/\&.
74 .PP
75 All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence\&. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later)\&.
76 .PP
77 Packages should install their configuration files in
78 /usr/lib/
79 (distribution packages) or
80 /usr/local/lib/
81 (local installs)
82 \&\s-2\u[1]\d\s+2\&. Files in
83 /etc/
84 are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&.
85 .PP
86 It is recommended to prefix all filenames with a two\-digit number and a dash to simplify the ordering\&. It is recommended to use the range 10\-40 for configuration files in
87 /usr/
88 and the range 60\-90 for configuration files in
89 /etc/
90 and
91 /run/, to make sure that local and transient configuration files will always take priority over configuration files shipped by the OS vendor\&.
92 .PP
93 If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to
94 /dev/null
95 in the configuration directory in
96 /etc/, with the same filename as the vendor configuration file\&. If the vendor configuration file is included in the initrd image, the image has to be regenerated\&.
97 .SH "CONFIGURATION FORMAT"
98 .PP
99 The configuration files contain a list of
100 "\fIKEY\fR=\fIVALUE\fR"
101 environment variable assignments, separated by newlines\&. The right hand side of these assignments may reference previously defined environment variables, using the
102 "${OTHER_KEY}"
103 and
104 "$OTHER_KEY"
105 format\&. It is also possible to use
106 "${\fIFOO\fR:\-\fIDEFAULT_VALUE\fR}"
107 to expand in the same way as
108 "${\fIFOO\fR}"
109 unless the expansion would be empty, in which case it expands to
110 \fIDEFAULT_VALUE\fR, and use
111 "${\fIFOO\fR:+\fIALTERNATE_VALUE\fR}"
112 to expand to
113 \fIALTERNATE_VALUE\fR
114 as long as
115 "${\fIFOO\fR}"
116 would have expanded to a non\-empty value\&. You can escape a literal dollar sign
117 "$"
118 by doubling it, as in
119 "$$"\&.
120 .PP
121 A backslash character
122 "\e"
123 followed by a newline acts as a line continuation (both characters are discarded); in all other cases, the backslash is consumed and the following character is included literally in the value\&. This can be used to preserve leading/trailing whitespace or include literal backslashes\&.
124 .PP
125 You may optionally enclose the right hand side of assignments in pairs of either
126 \fB\*(Aq\fRsingle quotes\fB\*(Aq\fR
127 or
128 \fB"\fRdouble quotes\fB"\fR; these will be stripped from the value before saving it\&. Using either quoting style does not affect variable expansion; however, single quotes disable backslash escaping entirely, while double quoting removes backslashes that precede double quotes
129 """, dollar signs
130 "$", backslashes
131 "\e", backticks
132 "`", and newlines, and leaves all other backslashes in place\&.
133 .PP
134 Leading and trailing whitespace characters are stripped from both the left and right hand sides of the assignment\&. To preserve such spaces in the value, you can either enclose the entire value in quotes, or escape the space characters with backslashes\&. You can also include literal newlines in the value by enclosing it in quotes\&.
135 .PP
136 Each
137 \fIKEY\fR
138 must be a valid variable name\&. Empty lines and lines beginning with the comment characters
139 "#"
140 or
141 ";"
142 are ignored\&. No other elements of shell syntax are supported\&.
143 .SS "Examples"
144 .PP
145 \fBExample\ \&1.\ \&Setup environment to allow access to a program installed in /opt/foo\fR
146 .PP
147 /etc/environment\&.d/60\-foo\&.conf:
148 .sp
149 .if n \{\
150 .RS 4
151 .\}
152 .nf
153 FOO_DEBUG=force\-software\-gl,log\-verbose
154 PATH=/opt/foo/bin:$PATH
155 LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
156 XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:\-/usr/local/share/:/usr/share/}
157 .fi
158 .if n \{\
159 .RE
160 .\}
161 .PP
162 \fBExample\ \&2.\ \&Escaping and variable expansion\fR
163 .PP
164 /etc/environment\&.d/70\-bar\&.conf:
165 .sp
166 .if n \{\
167 .RS 4
168 .\}
169 .nf
170 # A comment
171 test_var=(variable)
172 ; Another comment
173 test_comment=value # This is a part of the variable, and not a comment!
174
175 test_none= \e before\e
176 after "" \*(Aq\*(Aq \e${test_var}
177 test_double=" \e before\e
178 after "" \*(Aq\*(Aq \e${test_var}"
179 test_single=\*(Aq \e before\e
180 after "" \*(Aq\*(Aq \e${test_var}\*(Aq
181
182 # The above example produces the following environment variables, written using
183 # C\-style string escapes:
184 #
185 # test_var="(variable)"
186 # test_comment="value # This is a part of the variable, and not a comment!"
187 # test_none=" beforeafter \e"\e" \*(Aq\*(Aq (variable)"
188 # test_double=" \e\e beforeafter \*(Aq\*(Aq (variable)"
189 # test_single=" \e\e before\e\e\enafter \e"\e" \e\e(variable)"
190 .fi
191 .if n \{\
192 .RE
193 .\}
194 .SH "APPLICABILITY"
195 .PP
196 Environment variables exported by the user service manager (\fBsystemd \-\-user\fR
197 instance started in the
198 user@\fIuid\fR\&.service
199 system service) are passed to any services started by that service manager\&. In particular, this may include services which run user shells\&. For example in the GNOME environment, the graphical terminal emulator runs as the
200 gnome\-terminal\-server\&.service
201 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 service manager, the environment they inherit is defined by the program that starts them\&. Hint: in general,
202 \fBsystemd.service\fR(5)
203 units contain programs launched by systemd, and
204 \fBsystemd.scope\fR(5)
205 units contain programs launched by something else\&.
206 .PP
207 Note that these files do not affect the environment block of the service manager itself, but exclusively the environment blocks passed to the services it manages\&. Environment variables set that way thus cannot be used to influence behaviour of the service manager\&. In order to make changes to the service manager\*(Aqs environment block the environment must be modified before the user\*(Aqs service manager is invoked, for example from the system service manager or via a PAM module\&.
208 .PP
209 Specifically, for ssh logins, the
210 \fBsshd\fR(8)
211 service builds an environment that is a combination of variables forwarded from the remote system and defined by
212 \fBsshd\fR, see the discussion in
213 \fBssh\fR(1)\&. 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
214 \fBsystemctl show\-environment\fR
215 or the underlying D\-Bus call\&.
216 .SH "SEE ALSO"
217 .PP
218 \fBsystemd\fR(1), \fBsystemd-environment-d-generator\fR(8), \fBsystemd.environment-generator\fR(7)
219 .SH "NOTES"
220 .IP " 1." 4
221 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If
222 /usr/local/
223 is a separate partition, it may not be available during early boot, and must not be used for configuration.
224