]>
Commit | Line | Data |
---|---|---|
c3e270f4 FB |
1 | --- |
2 | title: Known Environment Variables | |
4cdca0af | 3 | category: Interfaces |
b41a3f66 | 4 | layout: default |
c3e270f4 FB |
5 | --- |
6 | ||
4549fcdb LP |
7 | # Known Environment Variables |
8 | ||
9 | A number of systemd components take additional runtime parameters via | |
10 | environment variables. Many of these environment variables are not supported at | |
11 | the same level as command line switches and other interfaces are: we don't | |
12 | document them in the man pages and we make no stability guarantees for | |
13 | them. While they generally are unlikely to be dropped any time soon again, we | |
14 | do not want to guarantee that they stay around for good either. | |
15 | ||
16 | Below is an (incomprehensive) list of the environment variables understood by | |
17 | the various tools. Note that this list only covers environment variables not | |
18 | documented in the proper man pages. | |
19 | ||
20 | All tools: | |
21 | ||
e7b86e48 ZJS |
22 | * `$SYSTEMD_OFFLINE=[0|1]` — if set to `1`, then `systemctl` will refrain from |
23 | talking to PID 1; this has the same effect as the historical detection of | |
24 | `chroot()`. Setting this variable to `0` instead has a similar effect as | |
25 | `SYSTEMD_IGNORE_CHROOT=1`; i.e. tools will try to communicate with PID 1 even | |
26 | if a `chroot()` environment is detected. You almost certainly want to set | |
27 | this to `1` if you maintain a package build system or similar and are trying | |
28 | to use a modern container system and not plain `chroot()`. | |
f38951a6 | 29 | |
4549fcdb | 30 | * `$SYSTEMD_IGNORE_CHROOT=1` — if set, don't check whether being invoked in a |
f38951a6 | 31 | `chroot()` environment. This is particularly relevant for systemctl, as it |
e7b86e48 | 32 | will not alter its behaviour for `chroot()` environments if set. Normally it |
f38951a6 CW |
33 | refrains from talking to PID 1 in such a case; turning most operations such |
34 | as `start` into no-ops. If that's what's explicitly desired, you might | |
35 | consider setting `SYSTEMD_OFFLINE=1`. | |
4549fcdb LP |
36 | |
37 | * `$SD_EVENT_PROFILE_DELAYS=1` — if set, the sd-event event loop implementation | |
38 | will print latency information at runtime. | |
39 | ||
53aa0d02 | 40 | * `$SYSTEMD_PROC_CMDLINE` — if set, the contents are used as the kernel command |
e7b86e48 | 41 | line instead of the actual one in `/proc/cmdline`. This is useful for |
53aa0d02 ZJS |
42 | debugging, in order to test generators and other code against specific kernel |
43 | command lines. | |
44 | ||
e7b86e48 | 45 | * `$SYSTEMD_FSTAB` — if set, use this path instead of `/etc/fstab`. Only useful |
ed4ad488 ZJS |
46 | for debugging. |
47 | ||
e7b86e48 ZJS |
48 | * `$SYSTEMD_CRYPTTAB` — if set, use this path instead of `/etc/crypttab`. Only |
49 | useful for debugging. Currently only supported by | |
50 | `systemd-cryptsetup-generator`. | |
a6c57e74 | 51 | |
e7b86e48 ZJS |
52 | * `$SYSTEMD_VERITYTAB` — if set, use this path instead of |
53 | `/etc/veritytab`. Only useful for debugging. Currently only supported by | |
54 | `systemd-veritysetup-generator`. | |
08b04ec7 | 55 | |
2536752d | 56 | * `$SYSTEMD_EFI_OPTIONS` — if set, used instead of the string in the |
e7b86e48 | 57 | `SystemdOptions` EFI variable. Analogous to `$SYSTEMD_PROC_CMDLINE`. |
2467cc55 | 58 | |
05c6f341 ZJS |
59 | * `$SYSTEMD_DEFAULT_HOSTNAME` — override the compiled-in fallback hostname |
60 | (relevant in particular for the system manager and `systemd-hostnamed`). | |
61 | Must be a valid hostname (either a single label or a FQDN). | |
62 | ||
1f22621b KS |
63 | * `$SYSTEMD_IN_INITRD=[auto|lenient|0|1]` — if set, specifies initrd detection |
64 | method. Defaults to `auto`. Behavior is defined as follows: | |
65 | `auto`: Checks if `/etc/initrd-release` exists, and a temporary fs is mounted | |
66 | on `/`. If both conditions meet, then it's in initrd. | |
38f3e0a5 | 67 | `lenient`: Similar to `auto`, but the rootfs check is skipped. |
1f22621b KS |
68 | `0|1`: Simply overrides initrd detection. This is useful for debugging and |
69 | testing initrd-only programs in the main system. | |
0307ea49 | 70 | |
385b2eb2 YW |
71 | * `$SYSTEMD_BUS_TIMEOUT=SECS` — specifies the maximum time to wait for method call |
72 | completion. If no time unit is specified, assumes seconds. The usual other units | |
73 | are understood, too (us, ms, s, min, h, d, w, month, y). If it is not set or set | |
74 | to 0, then the built-in default is used. | |
75 | ||
5f1b0cc6 | 76 | * `$SYSTEMD_MEMPOOL=0` — if set, the internal memory caching logic employed by |
e7b86e48 | 77 | hash tables is turned off, and libc `malloc()` is used for all allocations. |
b4f60743 | 78 | |
e7b86e48 | 79 | * `$SYSTEMD_EMOJI=0` — if set, tools such as `systemd-analyze security` will |
5f1b0cc6 LP |
80 | not output graphical smiley emojis, but ASCII alternatives instead. Note that |
81 | this only controls use of Unicode emoji glyphs, and has no effect on other | |
82 | Unicode glyphs. | |
83 | ||
3f5ac303 | 84 | * `$RUNTIME_DIRECTORY` — various tools use this variable to locate the |
e7b86e48 ZJS |
85 | appropriate path under `/run/`. This variable is also set by the manager when |
86 | `RuntimeDirectory=` is used, see systemd.exec(5). | |
3f5ac303 | 87 | |
42f3b2f9 | 88 | * `$SYSTEMD_CRYPT_PREFIX` — if set configures the hash method prefix to use for |
e7b86e48 ZJS |
89 | UNIX `crypt()` when generating passwords. By default the system's "preferred |
90 | method" is used, but this can be overridden with this environment variable. | |
91 | Takes a prefix such as `$6$` or `$y$`. (Note that this is only honoured on | |
92 | systems built with libxcrypt and is ignored on systems using glibc's | |
93 | original, internal `crypt()` implementation.) | |
42f3b2f9 | 94 | |
fbccb980 KH |
95 | * `$SYSTEMD_RDRAND=0` — if set, the RDRAND instruction will never be used, |
96 | even if the CPU supports it. | |
97 | ||
ce8f6d47 LP |
98 | * `$SYSTEMD_SECCOMP=0` – if set, seccomp filters will not be enforced, even if |
99 | support for it is compiled in and available in the kernel. | |
100 | ||
101 | * `$SYSTEMD_LOG_SECCOMP=1` — if set, system calls blocked by seccomp filtering, | |
e7b86e48 ZJS |
102 | for example in `systemd-nspawn`, will be logged to the audit log, if the |
103 | kernel supports this. | |
ce8f6d47 | 104 | |
e7b86e48 | 105 | `systemctl`: |
4549fcdb LP |
106 | |
107 | * `$SYSTEMCTL_FORCE_BUS=1` — if set, do not connect to PID1's private D-Bus | |
108 | listener, and instead always connect through the dbus-daemon D-bus broker. | |
109 | ||
110 | * `$SYSTEMCTL_INSTALL_CLIENT_SIDE=1` — if set, enable or disable unit files on | |
111 | the client side, instead of asking PID 1 to do this. | |
112 | ||
e7b86e48 | 113 | * `$SYSTEMCTL_SKIP_SYSV=1` — if set, do not call SysV compatibility hooks. |
4549fcdb | 114 | |
e7b86e48 | 115 | `systemd-nspawn`: |
4549fcdb | 116 | |
e7b86e48 ZJS |
117 | * `$SYSTEMD_NSPAWN_UNIFIED_HIERARCHY=1` — if set, force `systemd-nspawn` into |
118 | unified cgroup hierarchy mode. | |
4549fcdb | 119 | |
e7b86e48 ZJS |
120 | * `$SYSTEMD_NSPAWN_API_VFS_WRITABLE=1` — if set, make `/sys/`, `/proc/sys/`, |
121 | and friends writable in the container. If set to "network", leave only | |
122 | `/proc/sys/net/` writable. | |
4549fcdb LP |
123 | |
124 | * `$SYSTEMD_NSPAWN_CONTAINER_SERVICE=…` — override the "service" name nspawn | |
125 | uses to register with machined. If unset defaults to "nspawn", but with this | |
126 | variable may be set to any other value. | |
127 | ||
128 | * `$SYSTEMD_NSPAWN_USE_CGNS=0` — if set, do not use cgroup namespacing, even if | |
129 | it is available. | |
130 | ||
131 | * `$SYSTEMD_NSPAWN_LOCK=0` — if set, do not lock container images when running. | |
132 | ||
e7b86e48 | 133 | * `$SYSTEMD_NSPAWN_TMPFS_TMP=0` — if set, do not overmount `/tmp/` in the |
1099ceeb LP |
134 | container with a tmpfs, but leave the directory from the image in place. |
135 | ||
e7b86e48 | 136 | `systemd-logind`: |
4549fcdb LP |
137 | |
138 | * `$SYSTEMD_BYPASS_HIBERNATION_MEMORY_CHECK=1` — if set, report that | |
139 | hibernation is available even if the swap devices do not provide enough room | |
140 | for it. | |
94fa1497 | 141 | |
e7b86e48 ZJS |
142 | * `$SYSTEMD_REBOOT_TO_FIRMWARE_SETUP` — if set, overrides `systemd-logind`'s |
143 | built-in EFI logic of requesting a reboot into the firmware. Takes a boolean. | |
144 | If set to false, the functionality is turned off entirely. If set to true, | |
145 | instead of requesting a reboot into the firmware setup UI through EFI a file, | |
146 | `/run/systemd/reboot-to-firmware-setup` is created whenever this is | |
e86c7a3a LP |
147 | requested. This file may be checked for by services run during system |
148 | shutdown in order to request the appropriate operation from the firmware in | |
149 | an alternative fashion. | |
150 | ||
151 | * `$SYSTEMD_REBOOT_TO_BOOT_LOADER_MENU` — similar to the above, allows | |
e7b86e48 ZJS |
152 | overriding of `systemd-logind`'s built-in EFI logic of requesting a reboot |
153 | into the boot loader menu. Takes a boolean. If set to false, the | |
154 | functionality is turned off entirely. If set to true, instead of requesting a | |
155 | reboot into the boot loader menu through EFI, the file | |
156 | `/run/systemd/reboot-to-boot-loader-menu` is created whenever this is | |
157 | requested. The file contains the requested boot loader menu timeout in µs, | |
158 | formatted in ASCII decimals, or zero in case no timeout is requested. This | |
159 | file may be checked for by services run during system shutdown in order to | |
160 | request the appropriate operation from the boot loader in an alternative | |
161 | fashion. | |
e86c7a3a LP |
162 | |
163 | * `$SYSTEMD_REBOOT_TO_BOOT_LOADER_ENTRY` — similar to the above, allows | |
e7b86e48 ZJS |
164 | overriding of `systemd-logind`'s built-in EFI logic of requesting a reboot |
165 | into a specific boot loader entry. Takes a boolean. If set to false, the | |
166 | functionality is turned off entirely. If set to true, instead of requesting a | |
167 | reboot into a specific boot loader entry through EFI, the file | |
e86c7a3a LP |
168 | `/run/systemd/reboot-to-boot-loader-entry` is created whenever this is |
169 | requested. The file contains the requested boot loader entry identifier. This | |
170 | file may be checked for by services run during system shutdown in order to | |
171 | request the appropriate operation from the boot loader in an alternative | |
172 | fashion. Note that by default only boot loader entries which follow the [Boot | |
173 | Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) and are | |
174 | placed in the ESP or the Extended Boot Loader partition may be selected this | |
175 | way. However, if a directory `/run/boot-loader-entries/` exists, the entries | |
176 | are loaded from there instead. The directory should contain the usual | |
177 | directory hierarchy mandated by the Boot Loader Specification, i.e. the entry | |
178 | drop-ins should be placed in | |
179 | `/run/boot-loader-entries/loader/entries/*.conf`, and the files referenced by | |
180 | the drop-ins (including the kernels and initrds) somewhere else below | |
181 | `/run/boot-loader-entries/`. Note that all these files may be (and are | |
e7b86e48 | 182 | supposed to be) symlinks. `systemd-logind` will load these files on-demand, |
e86c7a3a LP |
183 | these files can hence be updated (ideally atomically) whenever the boot |
184 | loader configuration changes. A foreign boot loader installer script should | |
185 | hence synthesize drop-in snippets and symlinks for all boot entries at boot | |
e7b86e48 ZJS |
186 | or whenever they change if it wants to integrate with `systemd-logind`'s |
187 | APIs. | |
e86c7a3a | 188 | |
e7b86e48 | 189 | `systemd-udevd`: |
679dab6a YW |
190 | |
191 | * `$NET_NAMING_SCHEME=` – if set, takes a network naming scheme (i.e. one of | |
192 | "v238", "v239", "v240"…, or the special value "latest") as parameter. If | |
e7b86e48 ZJS |
193 | specified udev's `net_id` builtin will follow the specified naming scheme |
194 | when determining stable network interface names. This may be used to revert | |
195 | to naming schemes of older udev versions, in order to provide more stable | |
196 | naming across updates. This environment variable takes precedence over the | |
197 | kernel command line option `net.naming-scheme=`, except if the value is | |
198 | prefixed with `:` in which case the kernel command line option takes | |
199 | precedence, if it is specified as well. | |
679dab6a | 200 | |
e7b86e48 | 201 | `nss-systemd`: |
dba1bd43 LP |
202 | |
203 | * `$SYSTEMD_NSS_BYPASS_SYNTHETIC=1` — if set, `nss-systemd` won't synthesize | |
204 | user/group records for the `root` and `nobody` users if they are missing from | |
205 | `/etc/passwd`. | |
206 | ||
207 | * `$SYSTEMD_NSS_DYNAMIC_BYPASS=1` — if set, `nss-systemd` won't return | |
208 | user/group records for dynamically registered service users (i.e. users | |
209 | registered through `DynamicUser=1`). | |
210 | ||
211 | * `$SYSTEMD_NSS_BYPASS_BUS=1` — if set, `nss-systemd` won't use D-Bus to do | |
212 | dynamic user lookups. This is primarily useful to make `nss-systemd` work | |
213 | safely from within `dbus-daemon`. | |
41d0da0f | 214 | |
e7b86e48 | 215 | `systemd-timedated`: |
41d0da0f YW |
216 | |
217 | * `$SYSTEMD_TIMEDATED_NTP_SERVICES=…` — colon-separated list of unit names of | |
218 | NTP client services. If set, `timedatectl set-ntp on` enables and starts the | |
219 | first existing unit listed in the environment variable, and | |
220 | `timedatectl set-ntp off` disables and stops all listed units. | |
39922217 | 221 | |
e7b86e48 | 222 | `systemd-sulogin-shell`: |
33eb44fe AH |
223 | |
224 | * `$SYSTEMD_SULOGIN_FORCE=1` — This skips asking for the root password if the | |
225 | root password is not available (such as when the root account is locked). | |
226 | See `sulogin(8)` for more details. | |
227 | ||
e7b86e48 | 228 | `bootctl` and other tools that access the EFI System Partition (ESP): |
8cbb7d87 LP |
229 | |
230 | * `$SYSTEMD_RELAX_ESP_CHECKS=1` — if set, the ESP validation checks are | |
231 | relaxed. Specifically, validation checks that ensure the specified ESP path | |
232 | is a FAT file system are turned off, as are checks that the path is located | |
233 | on a GPT partition with the correct type UUID. | |
234 | ||
cc7a0bfa LP |
235 | * `$SYSTEMD_ESP_PATH=…` — override the path to the EFI System Partition. This |
236 | may be used to override ESP path auto detection, and redirect any accesses to | |
e7b86e48 ZJS |
237 | the ESP to the specified directory. Note that unlike with `bootctl`'s |
238 | `--path=` switch only very superficial validation of the specified path is | |
239 | done when this environment variable is used. | |
cc7a0bfa | 240 | |
e7b86e48 | 241 | `systemd` itself: |
39922217 LP |
242 | |
243 | * `$SYSTEMD_ACTIVATION_UNIT` — set for all NSS and PAM module invocations that | |
244 | are done by the service manager on behalf of a specific unit, in child | |
245 | processes that are later (after execve()) going to become unit | |
246 | processes. Contains the full unit name (e.g. "foobar.service"). NSS and PAM | |
247 | modules can use this information to determine in which context and on whose | |
248 | behalf they are being called, which may be useful to avoid deadlocks, for | |
249 | example to bypass IPC calls to the very service that is about to be | |
250 | started. Note that NSS and PAM modules should be careful to only rely on this | |
251 | data when invoked privileged, or possibly only when getppid() returns 1, as | |
252 | setting environment variables is of course possible in any even unprivileged | |
253 | contexts. | |
254 | ||
255 | * `$SYSTEMD_ACTIVATION_SCOPE` — closely related to `$SYSTEMD_ACTIVATION_UNIT`, | |
256 | it is either set to `system` or `user` depending on whether the NSS/PAM | |
257 | module is called by systemd in `--system` or `--user` mode. | |
59f13dd6 | 258 | |
e7b86e48 | 259 | `systemd-remount-fs`: |
59f13dd6 | 260 | |
d238709c | 261 | * `$SYSTEMD_REMOUNT_ROOT_RW=1` — if set and no entry for the root directory |
e7b86e48 | 262 | exists in `/etc/fstab` (this file always takes precedence), then the root |
59f13dd6 | 263 | directory is remounted writable. This is primarily used by |
e7b86e48 | 264 | `systemd-gpt-auto-generator` to ensure the root partition is mounted writable |
59f13dd6 | 265 | in accordance to the GPT partition flags. |
a7d9fccd | 266 | |
e7b86e48 | 267 | `systemd-firstboot` and `localectl`: |
a7d9fccd | 268 | |
e7b86e48 | 269 | * `SYSTEMD_LIST_NON_UTF8_LOCALES=1` – if set, non-UTF-8 locales are listed among |
a7d9fccd LP |
270 | the installed ones. By default non-UTF-8 locales are suppressed from the |
271 | selection, since we are living in the 21st century. | |
7a87fb61 | 272 | |
e7b86e48 | 273 | `systemd-sysext`: |
7a87fb61 | 274 | |
e7b86e48 ZJS |
275 | * `SYSTEMD_SYSEXT_HIERARCHIES` – this variable may be used to override which |
276 | hierarchies are managed by `systemd-sysext`. By default only `/usr/` and | |
277 | `/opt/` are managed, and directories may be added or removed to that list by | |
278 | setting this environment variable to a colon-separated list of absolute | |
279 | paths. Only "real" file systems and directories that only contain "real" file | |
280 | systems as submounts should be used. Do not specify API file systems such as | |
281 | `/proc/` or `/sys/` here, or hierarchies that have them as submounts. In | |
282 | particular, do not specify the root directory `/` here. | |
4368c60c | 283 | |
e7b86e48 | 284 | `systemd-tmpfiles`: |
4368c60c | 285 | |
07dc08c2 | 286 | * `SYSTEMD_TMPFILES_FORCE_SUBVOL` — if unset, `v`/`q`/`Q` lines will create |
e7b86e48 ZJS |
287 | subvolumes only if the OS itself is installed into a subvolume. If set to `1` |
288 | (or another value interpreted as true), these lines will always create | |
289 | subvolumes if the backing filesystem supports them. If set to `0`, these | |
290 | lines will always create directories. | |
07dc08c2 ZJS |
291 | |
292 | `systemd-sysv-generator`: | |
293 | ||
294 | * `$SYSTEMD_SYSVINIT_PATH` — Controls where `systemd-sysv-generator` looks for | |
295 | SysV init scripts. | |
296 | ||
297 | * `$SYSTEMD_SYSVRCND_PATH` — Controls where `systemd-sysv-generator` looks for | |
298 | SysV init script runlevel link farms. | |
48eb2af6 | 299 | |
f0cb09bb ZJS |
300 | systemd tests: |
301 | ||
302 | * `$SYSTEMD_TEST_DATA` — override the location of test data. This is useful if | |
303 | a test executable is moved to an arbitrary location. | |
304 | ||
305 | * `$SYSTEMD_TEST_NSS_BUFSIZE` — size of scratch buffers for "reentrant" | |
306 | functions exported by the nss modules. | |
307 | ||
48eb2af6 ZJS |
308 | fuzzers: |
309 | ||
310 | * `$SYSTEMD_FUZZ_OUTPUT` — A boolean that specifies whether to write output to | |
311 | stdout. Setting to true is useful in manual invocations, since all output is | |
312 | suppressed by default. | |
313 | ||
314 | * `$SYSTEMD_FUZZ_RUNS` — The number of times execution should be repeated in | |
315 | manual invocations. | |
316 | ||
317 | Note that is may be also useful to set `$SYSTEMD_LOG_LEVEL`, since all logging | |
318 | is suppressed by default. | |
23851640 LP |
319 | |
320 | systemd-importd: | |
321 | ||
322 | * `SYSTEMD_IMPORT_BTRFS_SUBVOL` – takes a boolean, which controls whether to | |
323 | prefer creating btrfs subvolumes over plain directories for machine | |
324 | images. Has no effect on non-btrfs file systems where subvolumes are not | |
325 | available anyway. If not set, defaults to true. | |
326 | ||
327 | * `SYSTEMD_IMPORT_BTRFS_QUOTA` – takes a boolean, which controls whether to set | |
328 | up quota automatically for created btrfs subvolumes for machine images. If | |
329 | not set, defaults to true. Has no effect if machines are placed in regular | |
330 | directories, because btrfs subvolumes are not supported or disabled. If | |
331 | enabled, the quota group of the subvolume is automatically added to a | |
332 | combined quota group for all such machine subvolumes. | |
333 | ||
334 | * `SYSTEMD_IMPORT_SYNC` – takes a boolean, which controls whether to | |
335 | synchronize images to disk after installing them, before completing the | |
336 | operation. If not set, defaults to true. If disabled installation of images | |
337 | will be quicker, but not as safe. |