Debian Codegraph @

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

raw
1 '\" t
2 .TH "ENVIRONMENT\&.D" "5" "" "systemd 257.13" "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\&. No other elements of shell syntax are supported\&.
117 .PP
118 Each
119 \fIKEY\fR
120 must be a valid variable name\&. Empty lines and lines beginning with the comment character
121 "#"
122 are ignored\&.
123 .SS "Example"
124 .PP
125 \fBExample\ \&1.\ \&Setup environment to allow access to a program installed in /opt/foo\fR
126 .PP
127 /etc/environment\&.d/60\-foo\&.conf:
128 .sp
129 .if n \{\
130 .RS 4
131 .\}
132 .nf
133 FOO_DEBUG=force\-software\-gl,log\-verbose
134 PATH=/opt/foo/bin:$PATH
135 LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
136 XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:\-/usr/local/share/:/usr/share/}
137 .fi
138 .if n \{\
139 .RE
140 .\}
141 .SH "APPLICABILITY"
142 .PP
143 Environment variables exported by the user service manager (\fBsystemd \-\-user\fR
144 instance started in the
145 user@\fIuid\fR\&.service
146 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
147 gnome\-terminal\-server\&.service
148 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,
149 \fBsystemd.service\fR(5)
150 units contain programs launched by systemd, and
151 \fBsystemd.scope\fR(5)
152 units contain programs launched by something else\&.
153 .PP
154 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\&.
155 .PP
156 Specifically, for ssh logins, the
157 \fBsshd\fR(8)
158 service builds an environment that is a combination of variables forwarded from the remote system and defined by
159 \fBsshd\fR, see the discussion in
160 \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
161 \fBsystemctl show\-environment\fR
162 or the underlying D\-Bus call\&.
163 .SH "SEE ALSO"
164 .PP
165 \fBsystemd\fR(1), \fBsystemd-environment-d-generator\fR(8), \fBsystemd.environment-generator\fR(7)
166 .SH "NOTES"
167 .IP " 1." 4
168 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If
169 /usr/local/
170 is a separate partition, it may not be available during early boot, and must not be used for configuration.
171