]>
Commit | Line | Data |
---|---|---|
c3e270f4 FB |
1 | --- |
2 | title: Known Environment Variables | |
4cdca0af | 3 | category: Interfaces |
b41a3f66 | 4 | layout: default |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
c3e270f4 FB |
6 | --- |
7 | ||
4549fcdb LP |
8 | # Known Environment Variables |
9 | ||
10 | A number of systemd components take additional runtime parameters via | |
11 | environment variables. Many of these environment variables are not supported at | |
12 | the same level as command line switches and other interfaces are: we don't | |
13 | document them in the man pages and we make no stability guarantees for | |
14 | them. While they generally are unlikely to be dropped any time soon again, we | |
15 | do not want to guarantee that they stay around for good either. | |
16 | ||
17 | Below is an (incomprehensive) list of the environment variables understood by | |
18 | the various tools. Note that this list only covers environment variables not | |
19 | documented in the proper man pages. | |
20 | ||
21 | All tools: | |
22 | ||
e7b86e48 ZJS |
23 | * `$SYSTEMD_OFFLINE=[0|1]` — if set to `1`, then `systemctl` will refrain from |
24 | talking to PID 1; this has the same effect as the historical detection of | |
25 | `chroot()`. Setting this variable to `0` instead has a similar effect as | |
54dcf847 LP |
26 | `$SYSTEMD_IGNORE_CHROOT=1`; i.e. tools will try to communicate with PID 1 |
27 | even if a `chroot()` environment is detected. You almost certainly want to | |
28 | set this to `1` if you maintain a package build system or similar and are | |
29 | trying to use a modern container system and not plain `chroot()`. | |
f38951a6 | 30 | |
4549fcdb | 31 | * `$SYSTEMD_IGNORE_CHROOT=1` — if set, don't check whether being invoked in a |
f38951a6 | 32 | `chroot()` environment. This is particularly relevant for systemctl, as it |
e7b86e48 | 33 | will not alter its behaviour for `chroot()` environments if set. Normally it |
f38951a6 CW |
34 | refrains from talking to PID 1 in such a case; turning most operations such |
35 | as `start` into no-ops. If that's what's explicitly desired, you might | |
54dcf847 | 36 | consider setting `$SYSTEMD_OFFLINE=1`. |
4549fcdb | 37 | |
bd3beda2 ZJS |
38 | * `$SYSTEMD_FIRST_BOOT=0|1` — if set, assume "first boot" condition to be false |
39 | or true, instead of checking the flag file created by PID 1. | |
40 | ||
4549fcdb LP |
41 | * `$SD_EVENT_PROFILE_DELAYS=1` — if set, the sd-event event loop implementation |
42 | will print latency information at runtime. | |
43 | ||
53aa0d02 | 44 | * `$SYSTEMD_PROC_CMDLINE` — if set, the contents are used as the kernel command |
e7b86e48 | 45 | line instead of the actual one in `/proc/cmdline`. This is useful for |
53aa0d02 ZJS |
46 | debugging, in order to test generators and other code against specific kernel |
47 | command lines. | |
48 | ||
df78419d ZJS |
49 | * `$SYSTEMD_OS_RELEASE` — if set, use this path instead of `/etc/os-release` or |
50 | `/usr/lib/os-release`. When operating under some root (e.g. `systemctl | |
5cf69e70 | 51 | --root=…`), the path is prefixed with the root. Only useful for debugging. |
df78419d | 52 | |
e7b86e48 | 53 | * `$SYSTEMD_FSTAB` — if set, use this path instead of `/etc/fstab`. Only useful |
ed4ad488 ZJS |
54 | for debugging. |
55 | ||
99e3d476 ZJS |
56 | * `$SYSTEMD_SYSROOT_FSTAB` — if set, use this path instead of |
57 | `/sysroot/etc/fstab`. Only useful for debugging `systemd-fstab-generator`. | |
58 | ||
905dd992 LF |
59 | * `$SYSTEMD_SYSFS_CHECK` — takes a boolean. If set, overrides sysfs container |
60 | detection that ignores `/dev/` entries in fstab. Only useful for debugging | |
61 | `systemd-fstab-generator`. | |
62 | ||
e7b86e48 ZJS |
63 | * `$SYSTEMD_CRYPTTAB` — if set, use this path instead of `/etc/crypttab`. Only |
64 | useful for debugging. Currently only supported by | |
65 | `systemd-cryptsetup-generator`. | |
a6c57e74 | 66 | |
1f1a2243 TA |
67 | * `$SYSTEMD_INTEGRITYTAB` — if set, use this path instead of |
68 | `/etc/integritytab`. Only useful for debugging. Currently only supported by | |
69 | `systemd-integritysetup-generator`. | |
70 | ||
e7b86e48 ZJS |
71 | * `$SYSTEMD_VERITYTAB` — if set, use this path instead of |
72 | `/etc/veritytab`. Only useful for debugging. Currently only supported by | |
73 | `systemd-veritysetup-generator`. | |
08b04ec7 | 74 | |
2536752d | 75 | * `$SYSTEMD_EFI_OPTIONS` — if set, used instead of the string in the |
e7b86e48 | 76 | `SystemdOptions` EFI variable. Analogous to `$SYSTEMD_PROC_CMDLINE`. |
2467cc55 | 77 | |
05c6f341 ZJS |
78 | * `$SYSTEMD_DEFAULT_HOSTNAME` — override the compiled-in fallback hostname |
79 | (relevant in particular for the system manager and `systemd-hostnamed`). | |
80 | Must be a valid hostname (either a single label or a FQDN). | |
81 | ||
b1fd5cd4 ZJS |
82 | * `$SYSTEMD_IN_INITRD` — takes a boolean. If set, overrides initrd detection. |
83 | This is useful for debugging and testing initrd-only programs in the main | |
84 | system. | |
0307ea49 | 85 | |
385b2eb2 YW |
86 | * `$SYSTEMD_BUS_TIMEOUT=SECS` — specifies the maximum time to wait for method call |
87 | completion. If no time unit is specified, assumes seconds. The usual other units | |
88 | are understood, too (us, ms, s, min, h, d, w, month, y). If it is not set or set | |
89 | to 0, then the built-in default is used. | |
90 | ||
5f1b0cc6 | 91 | * `$SYSTEMD_MEMPOOL=0` — if set, the internal memory caching logic employed by |
e7b86e48 | 92 | hash tables is turned off, and libc `malloc()` is used for all allocations. |
b4f60743 | 93 | |
71ea8436 LP |
94 | * `$SYSTEMD_UTF8=` — takes a boolean value, and overrides whether to generate |
95 | non-ASCII special glyphs at various places (i.e. "→" instead of | |
1a127aa0 | 96 | "->"). Usually this is determined automatically, based on `$LC_CTYPE`, but in |
71ea8436 LP |
97 | scenarios where locale definitions are not installed it might make sense to |
98 | override this check explicitly. | |
99 | ||
e7b86e48 | 100 | * `$SYSTEMD_EMOJI=0` — if set, tools such as `systemd-analyze security` will |
5f1b0cc6 LP |
101 | not output graphical smiley emojis, but ASCII alternatives instead. Note that |
102 | this only controls use of Unicode emoji glyphs, and has no effect on other | |
103 | Unicode glyphs. | |
104 | ||
3f5ac303 | 105 | * `$RUNTIME_DIRECTORY` — various tools use this variable to locate the |
e7b86e48 ZJS |
106 | appropriate path under `/run/`. This variable is also set by the manager when |
107 | `RuntimeDirectory=` is used, see systemd.exec(5). | |
3f5ac303 | 108 | |
42f3b2f9 | 109 | * `$SYSTEMD_CRYPT_PREFIX` — if set configures the hash method prefix to use for |
e7b86e48 ZJS |
110 | UNIX `crypt()` when generating passwords. By default the system's "preferred |
111 | method" is used, but this can be overridden with this environment variable. | |
112 | Takes a prefix such as `$6$` or `$y$`. (Note that this is only honoured on | |
113 | systems built with libxcrypt and is ignored on systems using glibc's | |
114 | original, internal `crypt()` implementation.) | |
42f3b2f9 | 115 | |
54dcf847 | 116 | * `$SYSTEMD_SECCOMP=0` — if set, seccomp filters will not be enforced, even if |
ce8f6d47 LP |
117 | support for it is compiled in and available in the kernel. |
118 | ||
119 | * `$SYSTEMD_LOG_SECCOMP=1` — if set, system calls blocked by seccomp filtering, | |
e7b86e48 ZJS |
120 | for example in `systemd-nspawn`, will be logged to the audit log, if the |
121 | kernel supports this. | |
ce8f6d47 | 122 | |
7c7a9138 | 123 | * `$SYSTEMD_ENABLE_LOG_CONTEXT` — if set, extra fields will always be logged to |
52afaee7 YW |
124 | the journal instead of only when logging in debug mode. |
125 | ||
126 | * `$SYSTEMD_NETLINK_DEFAULT_TIMEOUT` — specifies the default timeout of waiting | |
127 | replies for netlink messages from the kernel. Defaults to 25 seconds. | |
7c7a9138 | 128 | |
343e35b3 LB |
129 | * `$SYSTEMD_VERITY_SHARING=0` — if set, sharing dm-verity devices by |
130 | using a stable `<ROOTHASH>-verity` device mapper name will be disabled. | |
131 | ||
dba0afa1 LB |
132 | * `$SYSTEMD_OPENSSL_KEY_LOADER`— when using OpenSSL to load a key via an engine |
133 | or a provider, can be used to force the usage of one or the other interface. | |
134 | Set to 'engine' to force the usage of the old engine API, and to 'provider' | |
135 | force the usage of the new provider API. If unset, the provider will be tried | |
136 | first and the engine as a fallback if that fails. Providers are the new OpenSSL | |
137 | 3 API, but there are very few if any in a production-ready state, so engines | |
138 | are still needed. | |
139 | ||
e7b86e48 | 140 | `systemctl`: |
4549fcdb | 141 | |
8f1a581e | 142 | * `$SYSTEMCTL_FORCE_BUS=1` — if set, do not connect to PID 1's private D-Bus |
4549fcdb LP |
143 | listener, and instead always connect through the dbus-daemon D-bus broker. |
144 | ||
145 | * `$SYSTEMCTL_INSTALL_CLIENT_SIDE=1` — if set, enable or disable unit files on | |
146 | the client side, instead of asking PID 1 to do this. | |
147 | ||
e7b86e48 | 148 | * `$SYSTEMCTL_SKIP_SYSV=1` — if set, do not call SysV compatibility hooks. |
4549fcdb | 149 | |
665a3d6d LB |
150 | * `$SYSTEMCTL_SKIP_AUTO_KEXEC=1` — if set, do not automatically kexec instead of |
151 | reboot when a new kernel has been loaded. | |
152 | ||
153 | * `$SYSTEMCTL_SKIP_AUTO_SOFT_REBOOT=1` — if set, do not automatically soft-reboot | |
154 | instead of reboot when a new root file system has been loaded in | |
5d4072d0 | 155 | `/run/nextroot/`. |
665a3d6d | 156 | |
e7b86e48 | 157 | `systemd-nspawn`: |
4549fcdb | 158 | |
e7b86e48 ZJS |
159 | * `$SYSTEMD_NSPAWN_UNIFIED_HIERARCHY=1` — if set, force `systemd-nspawn` into |
160 | unified cgroup hierarchy mode. | |
4549fcdb | 161 | |
e7b86e48 ZJS |
162 | * `$SYSTEMD_NSPAWN_API_VFS_WRITABLE=1` — if set, make `/sys/`, `/proc/sys/`, |
163 | and friends writable in the container. If set to "network", leave only | |
164 | `/proc/sys/net/` writable. | |
4549fcdb LP |
165 | |
166 | * `$SYSTEMD_NSPAWN_CONTAINER_SERVICE=…` — override the "service" name nspawn | |
167 | uses to register with machined. If unset defaults to "nspawn", but with this | |
168 | variable may be set to any other value. | |
169 | ||
170 | * `$SYSTEMD_NSPAWN_USE_CGNS=0` — if set, do not use cgroup namespacing, even if | |
171 | it is available. | |
172 | ||
173 | * `$SYSTEMD_NSPAWN_LOCK=0` — if set, do not lock container images when running. | |
174 | ||
e7b86e48 | 175 | * `$SYSTEMD_NSPAWN_TMPFS_TMP=0` — if set, do not overmount `/tmp/` in the |
1099ceeb LP |
176 | container with a tmpfs, but leave the directory from the image in place. |
177 | ||
d4317fe1 FS |
178 | * `$SYSTEMD_NSPAWN_CHECK_OS_RELEASE=0` — if set, do not fail when trying to |
179 | boot an OS tree without an os-release file (useful when trying to boot a | |
180 | container with empty `/etc/` and bind-mounted `/usr/`) | |
181 | ||
4a4654e0 LP |
182 | * `$SYSTEMD_SUPPRESS_SYNC=1` — if set, all disk synchronization syscalls are |
183 | blocked to the container payload (e.g. `sync()`, `fsync()`, `syncfs()`, …) | |
184 | and the `O_SYNC`/`O_DSYNC` flags are made unavailable to `open()` and | |
185 | friends. This is equivalent to passing `--suppress-sync=yes` on the | |
186 | `systemd-nspawn` command line. | |
187 | ||
813dbff4 RC |
188 | * `$SYSTEMD_NSPAWN_NETWORK_MAC=...` — if set, allows users to set a specific MAC |
189 | address for a container, ensuring that it uses the provided value instead of | |
190 | generating a random one. It is effective when used with `--network-veth`. The | |
191 | expected format is six groups of two hexadecimal digits separated by colons, | |
192 | e.g. `SYSTEMD_NSPAWN_NETWORK_MAC=12:34:56:78:90:AB` | |
193 | ||
e7b86e48 | 194 | `systemd-logind`: |
4549fcdb LP |
195 | |
196 | * `$SYSTEMD_BYPASS_HIBERNATION_MEMORY_CHECK=1` — if set, report that | |
197 | hibernation is available even if the swap devices do not provide enough room | |
198 | for it. | |
94fa1497 | 199 | |
e7b86e48 ZJS |
200 | * `$SYSTEMD_REBOOT_TO_FIRMWARE_SETUP` — if set, overrides `systemd-logind`'s |
201 | built-in EFI logic of requesting a reboot into the firmware. Takes a boolean. | |
202 | If set to false, the functionality is turned off entirely. If set to true, | |
203 | instead of requesting a reboot into the firmware setup UI through EFI a file, | |
204 | `/run/systemd/reboot-to-firmware-setup` is created whenever this is | |
e86c7a3a LP |
205 | requested. This file may be checked for by services run during system |
206 | shutdown in order to request the appropriate operation from the firmware in | |
207 | an alternative fashion. | |
208 | ||
209 | * `$SYSTEMD_REBOOT_TO_BOOT_LOADER_MENU` — similar to the above, allows | |
e7b86e48 ZJS |
210 | overriding of `systemd-logind`'s built-in EFI logic of requesting a reboot |
211 | into the boot loader menu. Takes a boolean. If set to false, the | |
212 | functionality is turned off entirely. If set to true, instead of requesting a | |
213 | reboot into the boot loader menu through EFI, the file | |
214 | `/run/systemd/reboot-to-boot-loader-menu` is created whenever this is | |
215 | requested. The file contains the requested boot loader menu timeout in µs, | |
216 | formatted in ASCII decimals, or zero in case no timeout is requested. This | |
217 | file may be checked for by services run during system shutdown in order to | |
218 | request the appropriate operation from the boot loader in an alternative | |
219 | fashion. | |
e86c7a3a LP |
220 | |
221 | * `$SYSTEMD_REBOOT_TO_BOOT_LOADER_ENTRY` — similar to the above, allows | |
e7b86e48 ZJS |
222 | overriding of `systemd-logind`'s built-in EFI logic of requesting a reboot |
223 | into a specific boot loader entry. Takes a boolean. If set to false, the | |
224 | functionality is turned off entirely. If set to true, instead of requesting a | |
225 | reboot into a specific boot loader entry through EFI, the file | |
e86c7a3a LP |
226 | `/run/systemd/reboot-to-boot-loader-entry` is created whenever this is |
227 | requested. The file contains the requested boot loader entry identifier. This | |
228 | file may be checked for by services run during system shutdown in order to | |
229 | request the appropriate operation from the boot loader in an alternative | |
5c90c67a | 230 | fashion. Note that by default only boot loader entries which follow the |
db811444 ZJS |
231 | [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) |
232 | and are placed in the ESP or the Extended Boot Loader partition may be | |
233 | selected this way. However, if a directory `/run/boot-loader-entries/` | |
234 | exists, the entries are loaded from there instead. The directory should | |
235 | contain the usual directory hierarchy mandated by the Boot Loader | |
236 | Specification, i.e. the entry drop-ins should be placed in | |
e86c7a3a LP |
237 | `/run/boot-loader-entries/loader/entries/*.conf`, and the files referenced by |
238 | the drop-ins (including the kernels and initrds) somewhere else below | |
239 | `/run/boot-loader-entries/`. Note that all these files may be (and are | |
e7b86e48 | 240 | supposed to be) symlinks. `systemd-logind` will load these files on-demand, |
e86c7a3a LP |
241 | these files can hence be updated (ideally atomically) whenever the boot |
242 | loader configuration changes. A foreign boot loader installer script should | |
243 | hence synthesize drop-in snippets and symlinks for all boot entries at boot | |
e7b86e48 ZJS |
244 | or whenever they change if it wants to integrate with `systemd-logind`'s |
245 | APIs. | |
e86c7a3a | 246 | |
a7910612 | 247 | `systemd-udevd` and sd-device library: |
679dab6a | 248 | |
54dcf847 | 249 | * `$NET_NAMING_SCHEME=` — if set, takes a network naming scheme (i.e. one of |
679dab6a | 250 | "v238", "v239", "v240"…, or the special value "latest") as parameter. If |
e7b86e48 ZJS |
251 | specified udev's `net_id` builtin will follow the specified naming scheme |
252 | when determining stable network interface names. This may be used to revert | |
253 | to naming schemes of older udev versions, in order to provide more stable | |
254 | naming across updates. This environment variable takes precedence over the | |
78266a54 | 255 | kernel command line option `net.naming_scheme=`, except if the value is |
e7b86e48 ZJS |
256 | prefixed with `:` in which case the kernel command line option takes |
257 | precedence, if it is specified as well. | |
679dab6a | 258 | |
a7910612 LP |
259 | * `$SYSTEMD_DEVICE_VERIFY_SYSFS` — if set to "0", disables verification that |
260 | devices sysfs path are actually backed by sysfs. Relaxing this verification | |
261 | is useful for testing purposes. | |
262 | ||
b16c6076 YW |
263 | * `$SYSTEMD_UDEV_EXTRA_TIMEOUT_SEC=` — Specifies an extra timespan that the |
264 | udev manager process waits for a worker process kills slow programs specified | |
265 | by IMPORT{program}=, PROGRAM=, or RUN=, and finalizes the processing event. | |
266 | If the worker process cannot finalize the event within the specified timespan, | |
5af0f171 LB |
267 | the worker process is killed by the manager process. Defaults to 10 seconds, |
268 | maximum allowed is 5 hours. | |
b16c6076 | 269 | |
3d11b46b DDM |
270 | `udevadm` and `systemd-hwdb`: |
271 | ||
272 | * `SYSTEMD_HWDB_UPDATE_BYPASS=` — If set to "1", execution of hwdb updates is skipped | |
273 | when `udevadm hwdb --update` or `systemd-hwdb update` are invoked. This can | |
274 | be useful if either of these tools are invoked unconditionally as a child | |
275 | process by another tool, such as package managers running either of these | |
276 | tools in a postinstall script. | |
277 | ||
e7b86e48 | 278 | `nss-systemd`: |
dba1bd43 LP |
279 | |
280 | * `$SYSTEMD_NSS_BYPASS_SYNTHETIC=1` — if set, `nss-systemd` won't synthesize | |
281 | user/group records for the `root` and `nobody` users if they are missing from | |
282 | `/etc/passwd`. | |
283 | ||
284 | * `$SYSTEMD_NSS_DYNAMIC_BYPASS=1` — if set, `nss-systemd` won't return | |
285 | user/group records for dynamically registered service users (i.e. users | |
286 | registered through `DynamicUser=1`). | |
287 | ||
e7b86e48 | 288 | `systemd-timedated`: |
41d0da0f YW |
289 | |
290 | * `$SYSTEMD_TIMEDATED_NTP_SERVICES=…` — colon-separated list of unit names of | |
291 | NTP client services. If set, `timedatectl set-ntp on` enables and starts the | |
292 | first existing unit listed in the environment variable, and | |
293 | `timedatectl set-ntp off` disables and stops all listed units. | |
39922217 | 294 | |
e7b86e48 | 295 | `systemd-sulogin-shell`: |
33eb44fe AH |
296 | |
297 | * `$SYSTEMD_SULOGIN_FORCE=1` — This skips asking for the root password if the | |
298 | root password is not available (such as when the root account is locked). | |
299 | See `sulogin(8)` for more details. | |
300 | ||
e7b86e48 | 301 | `bootctl` and other tools that access the EFI System Partition (ESP): |
8cbb7d87 LP |
302 | |
303 | * `$SYSTEMD_RELAX_ESP_CHECKS=1` — if set, the ESP validation checks are | |
304 | relaxed. Specifically, validation checks that ensure the specified ESP path | |
305 | is a FAT file system are turned off, as are checks that the path is located | |
306 | on a GPT partition with the correct type UUID. | |
307 | ||
cc7a0bfa LP |
308 | * `$SYSTEMD_ESP_PATH=…` — override the path to the EFI System Partition. This |
309 | may be used to override ESP path auto detection, and redirect any accesses to | |
e7b86e48 ZJS |
310 | the ESP to the specified directory. Note that unlike with `bootctl`'s |
311 | `--path=` switch only very superficial validation of the specified path is | |
312 | done when this environment variable is used. | |
cc7a0bfa | 313 | |
2e76ca79 LN |
314 | * `$KERNEL_INSTALL_CONF_ROOT=…` — override the built in default configuration |
315 | directory /etc/kernel/ to read files like entry-token and install.conf from. | |
316 | ||
e7b86e48 | 317 | `systemd` itself: |
39922217 LP |
318 | |
319 | * `$SYSTEMD_ACTIVATION_UNIT` — set for all NSS and PAM module invocations that | |
320 | are done by the service manager on behalf of a specific unit, in child | |
321 | processes that are later (after execve()) going to become unit | |
322 | processes. Contains the full unit name (e.g. "foobar.service"). NSS and PAM | |
323 | modules can use this information to determine in which context and on whose | |
324 | behalf they are being called, which may be useful to avoid deadlocks, for | |
325 | example to bypass IPC calls to the very service that is about to be | |
326 | started. Note that NSS and PAM modules should be careful to only rely on this | |
327 | data when invoked privileged, or possibly only when getppid() returns 1, as | |
328 | setting environment variables is of course possible in any even unprivileged | |
329 | contexts. | |
330 | ||
331 | * `$SYSTEMD_ACTIVATION_SCOPE` — closely related to `$SYSTEMD_ACTIVATION_UNIT`, | |
332 | it is either set to `system` or `user` depending on whether the NSS/PAM | |
333 | module is called by systemd in `--system` or `--user` mode. | |
59f13dd6 | 334 | |
88e4bfa6 MS |
335 | * `$SYSTEMD_SUPPORT_DEVICE`, `$SYSTEMD_SUPPORT_MOUNT`, `$SYSTEMD_SUPPORT_SWAP` - |
336 | can be set to `0` to mark respective unit type as unsupported. Generally, | |
337 | having less units saves system resources so these options might be useful | |
338 | for cases where we don't need to track given unit type, e.g. `--user` manager | |
339 | often doesn't need to deal with device or swap units because they are | |
340 | handled by the `--system` manager (PID 1). Note that setting certain unit | |
341 | type as unsupported may not prevent loading some units of that type if they | |
342 | are referenced by other units of another supported type. | |
343 | ||
24a4542c LB |
344 | * `$SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST` — can be set to override the mount |
345 | units burst rate limit for parsing `/proc/self/mountinfo`. On a system with | |
346 | few resources but many mounts the rate limit may be hit, which will cause the | |
347 | processing of mount units to stall. The burst limit may be adjusted when the | |
348 | default is not appropriate for a given system. Defaults to `5`, accepts | |
349 | positive integers. | |
350 | ||
e7b86e48 | 351 | `systemd-remount-fs`: |
59f13dd6 | 352 | |
d238709c | 353 | * `$SYSTEMD_REMOUNT_ROOT_RW=1` — if set and no entry for the root directory |
e7b86e48 | 354 | exists in `/etc/fstab` (this file always takes precedence), then the root |
59f13dd6 | 355 | directory is remounted writable. This is primarily used by |
e7b86e48 | 356 | `systemd-gpt-auto-generator` to ensure the root partition is mounted writable |
59f13dd6 | 357 | in accordance to the GPT partition flags. |
a7d9fccd | 358 | |
e7b86e48 | 359 | `systemd-firstboot` and `localectl`: |
a7d9fccd | 360 | |
54dcf847 | 361 | * `$SYSTEMD_LIST_NON_UTF8_LOCALES=1` — if set, non-UTF-8 locales are listed among |
a7d9fccd LP |
362 | the installed ones. By default non-UTF-8 locales are suppressed from the |
363 | selection, since we are living in the 21st century. | |
7a87fb61 | 364 | |
d8962609 JM |
365 | `systemd-resolved`: |
366 | ||
367 | * `$SYSTEMD_RESOLVED_SYNTHESIZE_HOSTNAME` — if set to "0", `systemd-resolved` | |
368 | won't synthesize system hostname on both regular and reverse lookups. | |
369 | ||
e7b86e48 | 370 | `systemd-sysext`: |
7a87fb61 | 371 | |
54dcf847 | 372 | * `$SYSTEMD_SYSEXT_HIERARCHIES` — this variable may be used to override which |
e7b86e48 ZJS |
373 | hierarchies are managed by `systemd-sysext`. By default only `/usr/` and |
374 | `/opt/` are managed, and directories may be added or removed to that list by | |
375 | setting this environment variable to a colon-separated list of absolute | |
376 | paths. Only "real" file systems and directories that only contain "real" file | |
377 | systems as submounts should be used. Do not specify API file systems such as | |
378 | `/proc/` or `/sys/` here, or hierarchies that have them as submounts. In | |
1f4f1666 | 379 | particular, do not specify the root directory `/` here. Similarly, |
380 | `$SYSTEMD_CONFEXT_HIERARCHIES` works for confext images and supports the | |
381 | systemd-confext multi-call functionality of sysext. | |
4368c60c | 382 | |
e7b86e48 | 383 | `systemd-tmpfiles`: |
4368c60c | 384 | |
54dcf847 | 385 | * `$SYSTEMD_TMPFILES_FORCE_SUBVOL` — if unset, `v`/`q`/`Q` lines will create |
e7b86e48 ZJS |
386 | subvolumes only if the OS itself is installed into a subvolume. If set to `1` |
387 | (or another value interpreted as true), these lines will always create | |
388 | subvolumes if the backing filesystem supports them. If set to `0`, these | |
389 | lines will always create directories. | |
07dc08c2 | 390 | |
3fa8a114 JSMR |
391 | `systemd-sysusers` |
392 | ||
e24c6676 | 393 | * `$SOURCE_DATE_EPOCH` — if unset, the field of the date of last password change |
3fa8a114 | 394 | in `/etc/shadow` will be the number of days from Jan 1, 1970 00:00 UTC until |
1a127aa0 | 395 | today. If `$SOURCE_DATE_EPOCH` is set to a valid UNIX epoch value in seconds, |
3fa8a114 JSMR |
396 | then the field will be the number of days until that time instead. This is to |
397 | support creating bit-by-bit reproducible system images by choosing a | |
398 | reproducible value for the field of the date of last password change in | |
399 | `/etc/shadow`. See: https://reproducible-builds.org/specs/source-date-epoch/ | |
400 | ||
07dc08c2 ZJS |
401 | `systemd-sysv-generator`: |
402 | ||
403 | * `$SYSTEMD_SYSVINIT_PATH` — Controls where `systemd-sysv-generator` looks for | |
404 | SysV init scripts. | |
405 | ||
406 | * `$SYSTEMD_SYSVRCND_PATH` — Controls where `systemd-sysv-generator` looks for | |
407 | SysV init script runlevel link farms. | |
48eb2af6 | 408 | |
f0cb09bb ZJS |
409 | systemd tests: |
410 | ||
411 | * `$SYSTEMD_TEST_DATA` — override the location of test data. This is useful if | |
412 | a test executable is moved to an arbitrary location. | |
413 | ||
414 | * `$SYSTEMD_TEST_NSS_BUFSIZE` — size of scratch buffers for "reentrant" | |
415 | functions exported by the nss modules. | |
416 | ||
7e81ce6b LP |
417 | * `$TESTFUNCS` – takes a colon separated list of test functions to invoke, |
418 | causes all non-matching test functions to be skipped. Only applies to tests | |
419 | using our regular test boilerplate. | |
420 | ||
48eb2af6 ZJS |
421 | fuzzers: |
422 | ||
423 | * `$SYSTEMD_FUZZ_OUTPUT` — A boolean that specifies whether to write output to | |
424 | stdout. Setting to true is useful in manual invocations, since all output is | |
425 | suppressed by default. | |
426 | ||
427 | * `$SYSTEMD_FUZZ_RUNS` — The number of times execution should be repeated in | |
428 | manual invocations. | |
429 | ||
f223fd6a | 430 | Note that it may be also useful to set `$SYSTEMD_LOG_LEVEL`, since all logging |
48eb2af6 | 431 | is suppressed by default. |
23851640 | 432 | |
54dcf847 | 433 | `systemd-importd`: |
23851640 | 434 | |
54dcf847 | 435 | * `$SYSTEMD_IMPORT_BTRFS_SUBVOL` — takes a boolean, which controls whether to |
23851640 LP |
436 | prefer creating btrfs subvolumes over plain directories for machine |
437 | images. Has no effect on non-btrfs file systems where subvolumes are not | |
438 | available anyway. If not set, defaults to true. | |
439 | ||
54dcf847 | 440 | * `$SYSTEMD_IMPORT_BTRFS_QUOTA` — takes a boolean, which controls whether to set |
23851640 LP |
441 | up quota automatically for created btrfs subvolumes for machine images. If |
442 | not set, defaults to true. Has no effect if machines are placed in regular | |
443 | directories, because btrfs subvolumes are not supported or disabled. If | |
444 | enabled, the quota group of the subvolume is automatically added to a | |
445 | combined quota group for all such machine subvolumes. | |
446 | ||
54dcf847 | 447 | * `$SYSTEMD_IMPORT_SYNC` — takes a boolean, which controls whether to |
23851640 LP |
448 | synchronize images to disk after installing them, before completing the |
449 | operation. If not set, defaults to true. If disabled installation of images | |
450 | will be quicker, but not as safe. | |
54dcf847 LP |
451 | |
452 | `systemd-dissect`, `systemd-nspawn` and all other tools that may operate on | |
453 | disk images with `--image=` or similar: | |
454 | ||
455 | * `$SYSTEMD_DISSECT_VERITY_SIDECAR` — takes a boolean, which controls whether to | |
456 | load "sidecar" Verity metadata files. If enabled (which is the default), | |
457 | whenever a disk image is used, a set of files with the `.roothash`, | |
458 | `.usrhash`, `.roothash.p7s`, `.usrhash.p7s`, `.verity` suffixes are searched | |
459 | adjacent to disk image file, containing the Verity root hashes, their | |
460 | signatures or the Verity data itself. If disabled this automatic discovery of | |
461 | Verity metadata files is turned off. | |
462 | ||
463 | * `$SYSTEMD_DISSECT_VERITY_EMBEDDED` — takes a boolean, which controls whether | |
464 | to load the embedded Verity signature data. If enabled (which is the | |
465 | default), Verity root hash information and a suitable signature is | |
466 | automatically acquired from a signature partition, following the | |
db811444 | 467 | [Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). |
5c90c67a BF |
468 | If disabled any such partition is ignored. Note that this only disables |
469 | discovery of the root hash and its signature, the Verity data partition | |
470 | itself is still searched in the GPT image. | |
54dcf847 LP |
471 | |
472 | * `$SYSTEMD_DISSECT_VERITY_SIGNATURE` — takes a boolean, which controls whether | |
473 | to validate the signature of the Verity root hash if available. If enabled | |
474 | (which is the default), the signature of suitable disk images is validated | |
475 | against any of the certificates in `/etc/verity.d/*.crt` (and similar | |
ba669952 | 476 | directories in `/usr/lib/`, `/run`, …) or passed to the kernel for validation |
54dcf847 | 477 | against its built-in certificates. |
ccd25f41 | 478 | |
2b660510 YW |
479 | * `$SYSTEMD_DISSECT_VERITY_TIMEOUT_SEC=sec` — takes a timespan, which controls |
480 | the timeout waiting for the image to be configured. Defaults to 100 msec. | |
481 | ||
80ce8580 LP |
482 | * `$SYSTEMD_DISSECT_FILE_SYSTEMS=` — takes a colon-separated list of file |
483 | systems that may be mounted for automatically dissected disk images. If not | |
484 | specified defaults to something like: `ext4:btrfs:xfs:vfat:erofs:squashfs` | |
485 | ||
e8c7c4d9 | 486 | * `$SYSTEMD_LOOP_DIRECT_IO` – takes a boolean, which controls whether to enable |
1a127aa0 | 487 | `LO_FLAGS_DIRECT_IO` (i.e. direct IO + asynchronous IO) on loopback block |
e8c7c4d9 LP |
488 | devices when opening them. Defaults to on, set this to "0" to disable this |
489 | feature. | |
490 | ||
f0ecff85 LP |
491 | * `$SYSTEMD_ALLOW_USERSPACE_VERITY` — takes a boolean, which controls whether |
492 | to consider the userspace Verity public key store in `/etc/verity.d/` (and | |
493 | related directories) to authenticate signatures on Verity hashes of disk | |
494 | images. Defaults to true, i.e. userspace signature validation is allowed. If | |
495 | false, authentication can be done only via the kernel's internal keyring. | |
496 | ||
ccd25f41 LP |
497 | `systemd-cryptsetup`: |
498 | ||
499 | * `$SYSTEMD_CRYPTSETUP_USE_TOKEN_MODULE` – takes a boolean, which controls | |
500 | whether to use the libcryptsetup "token" plugin module logic even when | |
501 | activating via FIDO2, PKCS#11, TPM2, i.e. mechanisms natively supported by | |
502 | `systemd-cryptsetup`. Defaults to enabled. | |
c04358ce | 503 | |
0631eac9 LP |
504 | * `$SYSTEMD_CRYPTSETUP_TOKEN_PATH` – takes a path to a directory in the file |
505 | system. If specified overrides where libcryptsetup will look for token | |
506 | modules (.so). This is useful for debugging token modules: set this | |
25757715 ZJS |
507 | environment variable to the build directory and you are set. This variable |
508 | is only supported when systemd is compiled in developer mode. | |
0631eac9 | 509 | |
c04358ce LP |
510 | Various tools that read passwords from the TTY, such as `systemd-cryptenroll` |
511 | and `homectl`: | |
512 | ||
513 | * `$PASSWORD` — takes a string: the literal password to use. If this | |
514 | environment variable is set it is used as password instead of prompting the | |
515 | user interactively. This exists primarily for debugging and testing | |
516 | purposes. Do not use this for production code paths, since environment | |
517 | variables are typically inherited down the process tree without restrictions | |
518 | and should thus not be used for secrets. | |
519 | ||
520 | * `$NEWPASSWORD` — similar to `$PASSWORD` above, but is used when both a | |
521 | current and a future password are required, for example if the password is to | |
522 | be changed. In that case `$PASSWORD` shall carry the current (i.e. old) | |
523 | password and `$NEWPASSWORD` the new. | |
67302b38 LP |
524 | |
525 | `systemd-homed`: | |
526 | ||
527 | * `$SYSTEMD_HOME_ROOT` – defines an absolute path where to look for home | |
528 | directories/images. When unspecified defaults to `/home/`. This is useful for | |
529 | debugging purposes in order to run a secondary `systemd-homed` instance that | |
530 | operates on a different directory where home directories/images are placed. | |
531 | ||
532 | * `$SYSTEMD_HOME_RECORD_DIR` – defines an absolute path where to look for | |
533 | fixated home records kept on the host. When unspecified defaults to | |
534 | `/var/lib/systemd/home/`. Similar to `$SYSTEMD_HOME_ROOT` this is useful for | |
535 | debugging purposes, in order to run a secondary `systemd-homed` instance that | |
536 | operates on a record database entirely separate from the host's. | |
537 | ||
538 | * `$SYSTEMD_HOME_DEBUG_SUFFIX` – takes a short string that is suffixed to | |
539 | `systemd-homed`'s D-Bus and Varlink service names/sockets. This is also | |
a6f44d61 | 540 | understood by `homectl`. This too is useful for running an additional copy of |
67302b38 LP |
541 | `systemd-homed` that doesn't interfere with the host's main one. |
542 | ||
543 | * `$SYSTEMD_HOMEWORK_PATH` – configures the path to the `systemd-homework` | |
544 | binary to invoke. If not specified defaults to | |
545 | `/usr/lib/systemd/systemd-homework`. | |
546 | ||
547 | Combining these four environment variables is pretty useful when | |
548 | debugging/developing `systemd-homed`: | |
549 | ```sh | |
550 | SYSTEMD_HOME_DEBUG_SUFFIX=foo \ | |
551 | SYSTEMD_HOMEWORK_PATH=/home/lennart/projects/systemd/build/systemd-homework \ | |
552 | SYSTEMD_HOME_ROOT=/home.foo/ \ | |
553 | SYSTEMD_HOME_RECORD_DIR=/var/lib/systemd/home.foo/ \ | |
554 | /home/lennart/projects/systemd/build/systemd-homed | |
555 | ``` | |
db42f011 LP |
556 | |
557 | * `$SYSTEMD_HOME_MOUNT_OPTIONS_BTRFS`, `$SYSTEMD_HOME_MOUNT_OPTIONS_EXT4`, | |
558 | `$SYSTEMD_HOME_MOUNT_OPTIONS_XFS` – configure the default mount options to | |
559 | use for LUKS home directories, overriding the built-in default mount | |
560 | options. There's one variable for each of the supported file systems for the | |
561 | LUKS home directory backend. | |
a2a9d541 | 562 | |
8f30c00c AD |
563 | * `$SYSTEMD_HOME_MKFS_OPTIONS_BTRFS`, `$SYSTEMD_HOME_MKFS_OPTIONS_EXT4`, |
564 | `$SYSTEMD_HOME_MKFS_OPTIONS_XFS` – configure additional arguments to use for | |
565 | `mkfs` when formatting LUKS home directories. There's one variable for each | |
566 | of the supported file systems for the LUKS home directory backend. | |
567 | ||
a2a9d541 DDM |
568 | `kernel-install`: |
569 | ||
570 | * `$KERNEL_INSTALL_BYPASS` – If set to "1", execution of kernel-install is skipped | |
571 | when kernel-install is invoked. This can be useful if kernel-install is invoked | |
572 | unconditionally as a child process by another tool, such as package managers | |
573 | running kernel-install in a postinstall script. | |
61297656 | 574 | |
fba84e12 | 575 | `systemd-journald`, `journalctl`: |
61297656 | 576 | |
6337be0a | 577 | * `$SYSTEMD_JOURNAL_COMPACT` – Takes a boolean. If enabled, journal files are written |
61297656 DDM |
578 | in a more compact format that reduces the amount of disk space required by the |
579 | journal. Note that journal files in compact mode are limited to 4G to allow use of | |
580 | 32-bit offsets. Enabled by default. | |
6337be0a | 581 | |
1f06ea74 YW |
582 | * `$SYSTEMD_JOURNAL_COMPRESS` – Takes a boolean, or one of the compression |
583 | algorithms "XZ", "LZ4", and "ZSTD". If enabled, the default compression | |
584 | algorithm set at compile time will be used when opening a new journal file. | |
585 | If disabled, the journal file compression will be disabled. Note that the | |
586 | compression mode of existing journal files are not changed. To make the | |
587 | specified algorithm takes an effect immediately, you need to explicitly run | |
588 | `journalctl --rotate`. | |
589 | ||
fba84e12 LP |
590 | * `$SYSTEMD_CATALOG` – path to the compiled catalog database file to use for |
591 | `journalctl -x`, `journalctl --update-catalog`, `journalctl --list-catalog` | |
592 | and related calls. | |
593 | ||
594 | * `$SYSTEMD_CATALOG_SOURCES` – path to the catalog database input source | |
595 | directory to use for `journalctl --update-catalog`. | |
596 | ||
32295fa0 | 597 | `systemd-pcrextend`, `systemd-cryptsetup`: |
6337be0a | 598 | |
6c51b49c LP |
599 | * `$SYSTEMD_FORCE_MEASURE=1` — If set, force measuring of resources (which are |
600 | marked for measurement) even if not booted on a kernel equipped with | |
601 | systemd-stub. Normally, requested measurement of resources is conditionalized | |
602 | on kernels that have booted with `systemd-stub`. With this environment | |
603 | variable the test for that my be bypassed, for testing purposes. | |
4b8ce14f DDM |
604 | |
605 | `systemd-repart`: | |
606 | ||
607 | * `$SYSTEMD_REPART_MKFS_OPTIONS_<FSTYPE>` – configure additional arguments to use for | |
608 | `mkfs` when formatting partition file systems. There's one variable for each | |
609 | of the supported file systems. | |
e59049d7 LP |
610 | |
611 | * `$SYSTEMD_REPART_OVERRIDE_FSTYPE` – if set the value will override the file | |
612 | system type specified in Format= lines in partition definition files. | |
d54c747f LP |
613 | |
614 | `systemd-nspawn`, `systemd-networkd`: | |
615 | ||
616 | * `$SYSTEMD_FIREWALL_BACKEND` – takes a string, either `iptables` or | |
617 | `nftables`. Selects the firewall backend to use. If not specified tries to | |
618 | use `nftables` and falls back to `iptables` if that's not available. | |
abc19a6f LP |
619 | |
620 | `systemd-storagetm`: | |
621 | ||
622 | * `$SYSTEMD_NVME_MODEL`, `$SYSTEMD_NVME_FIRMWARE`, `$SYSTEMD_NVME_SERIAL`, | |
623 | `$SYSTEMD_NVME_UUID` – these take a model string, firmware version string, | |
624 | serial number string, and UUID formatted as string. If specified these | |
625 | override the defaults exposed on the NVME subsystem and namespace, which are | |
626 | derived from the underlying block device and system identity. Do not set the | |
627 | latter two via the environment variable unless `systemd-storagetm` is invoked | |
628 | to expose a single device only, since those identifiers better should be kept | |
629 | unique. | |
a1bb30de | 630 | |
0691d0e5 LP |
631 | `systemd-pcrlock`, `systemd-pcrextend`: |
632 | ||
633 | * `$SYSTEMD_MEASURE_LOG_USERSPACE` – the path to the `tpm2-measure.log` file | |
634 | (containing userspace measurement data) to read. This allows overriding the | |
635 | default of `/run/log/systemd/tpm2-measure.log`. | |
636 | ||
637 | * `$SYSTEMD_MEASURE_LOG_FIRMWARE` – the path to the `binary_bios_measurements` | |
638 | file (containing firmware measurement data) to read. This allows overriding | |
639 | the default of `/sys/kernel/security/tpm0/binary_bios_measurements`. | |
640 | ||
bcb1bb37 LP |
641 | Tools using the Varlink protocol (such as `varlinkctl`) or sd-bus (such as |
642 | `busctl`): | |
a1bb30de LP |
643 | |
644 | * `$SYSTEMD_SSH` – the ssh binary to invoke when the `ssh:` transport is | |
645 | used. May be a filename (which is searched for in `$PATH`) or absolute path. | |
4a6fe5f0 LP |
646 | |
647 | * `$SYSTEMD_VARLINK_LISTEN` – interpreted by some tools that provide a Varlink | |
648 | service. Takes a file system path: if specified the tool will listen on an | |
649 | `AF_UNIX` stream socket on the specified path in addition to whatever else it | |
650 | would listen on. |