docs/ENVIRONMENT.md

   1 ---
   2 title: Known Environment Variables
   3 category: Interfaces
   4 layout: default
   5 ---
   6
   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
  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()`.
  29
  30 * `$SYSTEMD_IGNORE_CHROOT=1` — if set, don't check whether being invoked in a
  31   `chroot()` environment. This is particularly relevant for systemctl, as it
  32   will not alter its behaviour for `chroot()` environments if set. Normally it
  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`.
  36
  37 * `$SD_EVENT_PROFILE_DELAYS=1` — if set, the sd-event event loop implementation
  38   will print latency information at runtime.
  39
  40 * `$SYSTEMD_PROC_CMDLINE` — if set, the contents are used as the kernel command
  41   line instead of the actual one in `/proc/cmdline`. This is useful for
  42   debugging, in order to test generators and other code against specific kernel
  43   command lines.
  44
  45 * `$SYSTEMD_FSTAB` — if set, use this path instead of `/etc/fstab`. Only useful
  46   for debugging.
  47
  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`.
  51
  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`.
  55
  56 * `$SYSTEMD_EFI_OPTIONS` — if set, used instead of the string in the
  57   `SystemdOptions` EFI variable. Analogous to `$SYSTEMD_PROC_CMDLINE`.
  58
  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
  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.
  67   `lenient`: Similar to `auto`, but the rootfs check is skipped.
  68   `0|1`: Simply overrides initrd detection. This is useful for debugging and
  69          testing initrd-only programs in the main system.
  70
  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
  76 * `$SYSTEMD_MEMPOOL=0` — if set, the internal memory caching logic employed by
  77   hash tables is turned off, and libc `malloc()` is used for all allocations.
  78
  79 * `$SYSTEMD_EMOJI=0` — if set, tools such as `systemd-analyze security` will
  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
  84 * `$RUNTIME_DIRECTORY` — various tools use this variable to locate the
  85   appropriate path under `/run/`. This variable is also set by the manager when
  86   `RuntimeDirectory=` is used, see systemd.exec(5).
  87
  88 * `$SYSTEMD_CRYPT_PREFIX` — if set configures the hash method prefix to use for
  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.)
  94
  95 * `$SYSTEMD_RDRAND=0` — if set, the RDRAND instruction will never be used,
  96   even if the CPU supports it.
  97
  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,
 102   for example in `systemd-nspawn`, will be logged to the audit log, if the
 103   kernel supports this.
 104
 105 `systemctl`:
 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
 113 * `$SYSTEMCTL_SKIP_SYSV=1` — if set, do not call SysV compatibility hooks.
 114
 115 `systemd-nspawn`:
 116
 117 * `$SYSTEMD_NSPAWN_UNIFIED_HIERARCHY=1` — if set, force `systemd-nspawn` into
 118   unified cgroup hierarchy mode.
 119
 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.
 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
 133 * `$SYSTEMD_NSPAWN_TMPFS_TMP=0` — if set, do not overmount `/tmp/` in the
 134   container with a tmpfs, but leave the directory from the image in place.
 135
 136 `systemd-logind`:
 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.
 141
 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
 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
 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.
 162
 163 * `$SYSTEMD_REBOOT_TO_BOOT_LOADER_ENTRY` — similar to the above, allows
 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
 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
 182   supposed to be) symlinks. `systemd-logind` will load these files on-demand,
 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
 186   or whenever they change if it wants to integrate with `systemd-logind`'s
 187   APIs.
 188
 189 `systemd-udevd`:
 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
 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.
 200
 201 installed systemd tests:
 202
 203 * `$SYSTEMD_TEST_DATA` — override the location of test data. This is useful if
 204   a test executable is moved to an arbitrary location.
 205
 206 `nss-systemd`:
 207
 208 * `$SYSTEMD_NSS_BYPASS_SYNTHETIC=1` — if set, `nss-systemd` won't synthesize
 209   user/group records for the `root` and `nobody` users if they are missing from
 210   `/etc/passwd`.
 211
 212 * `$SYSTEMD_NSS_DYNAMIC_BYPASS=1` — if set, `nss-systemd` won't return
 213   user/group records for dynamically registered service users (i.e. users
 214   registered through `DynamicUser=1`).
 215
 216 * `$SYSTEMD_NSS_BYPASS_BUS=1` — if set, `nss-systemd` won't use D-Bus to do
 217   dynamic user lookups. This is primarily useful to make `nss-systemd` work
 218   safely from within `dbus-daemon`.
 219
 220 `systemd-timedated`:
 221
 222 * `$SYSTEMD_TIMEDATED_NTP_SERVICES=…` — colon-separated list of unit names of
 223   NTP client services. If set, `timedatectl set-ntp on` enables and starts the
 224   first existing unit listed in the environment variable, and
 225   `timedatectl set-ntp off` disables and stops all listed units.
 226
 227 `systemd-sulogin-shell`:
 228
 229 * `$SYSTEMD_SULOGIN_FORCE=1` — This skips asking for the root password if the
 230   root password is not available (such as when the root account is locked).
 231   See `sulogin(8)` for more details.
 232
 233 `bootctl` and other tools that access the EFI System Partition (ESP):
 234
 235 * `$SYSTEMD_RELAX_ESP_CHECKS=1` — if set, the ESP validation checks are
 236   relaxed. Specifically, validation checks that ensure the specified ESP path
 237   is a FAT file system are turned off, as are checks that the path is located
 238   on a GPT partition with the correct type UUID.
 239
 240 * `$SYSTEMD_ESP_PATH=…` — override the path to the EFI System Partition. This
 241   may be used to override ESP path auto detection, and redirect any accesses to
 242   the ESP to the specified directory. Note that unlike with `bootctl`'s
 243   `--path=` switch only very superficial validation of the specified path is
 244   done when this environment variable is used.
 245
 246 `systemd` itself:
 247
 248 * `$SYSTEMD_ACTIVATION_UNIT` — set for all NSS and PAM module invocations that
 249   are done by the service manager on behalf of a specific unit, in child
 250   processes that are later (after execve()) going to become unit
 251   processes. Contains the full unit name (e.g. "foobar.service"). NSS and PAM
 252   modules can use this information to determine in which context and on whose
 253   behalf they are being called, which may be useful to avoid deadlocks, for
 254   example to bypass IPC calls to the very service that is about to be
 255   started. Note that NSS and PAM modules should be careful to only rely on this
 256   data when invoked privileged, or possibly only when getppid() returns 1, as
 257   setting environment variables is of course possible in any even unprivileged
 258   contexts.
 259
 260 * `$SYSTEMD_ACTIVATION_SCOPE` — closely related to `$SYSTEMD_ACTIVATION_UNIT`,
 261   it is either set to `system` or `user` depending on whether the NSS/PAM
 262   module is called by systemd in `--system` or `--user` mode.
 263
 264 `systemd-remount-fs`:
 265
 266 * `$SYSTEMD_REMOUNT_ROOT_RW=1` — if set and no entry for the root directory
 267   exists in `/etc/fstab` (this file always takes precedence), then the root
 268   directory is remounted writable. This is primarily used by
 269   `systemd-gpt-auto-generator` to ensure the root partition is mounted writable
 270   in accordance to the GPT partition flags.
 271
 272 `systemd-firstboot` and `localectl`:
 273
 274 * `SYSTEMD_LIST_NON_UTF8_LOCALES=1` – if set, non-UTF-8 locales are listed among
 275   the installed ones. By default non-UTF-8 locales are suppressed from the
 276   selection, since we are living in the 21st century.
 277
 278 `systemd-sysext`:
 279
 280 * `SYSTEMD_SYSEXT_HIERARCHIES` – this variable may be used to override which
 281   hierarchies are managed by `systemd-sysext`. By default only `/usr/` and
 282   `/opt/` are managed, and directories may be added or removed to that list by
 283   setting this environment variable to a colon-separated list of absolute
 284   paths. Only "real" file systems and directories that only contain "real" file
 285   systems as submounts should be used. Do not specify API file systems such as
 286   `/proc/` or `/sys/` here, or hierarchies that have them as submounts. In
 287   particular, do not specify the root directory `/` here.
 288
 289 `systemd-tmpfiles`:
 290
 291 * `SYSTEMD_TMPFILES_FORCE_SUBVOL` - if unset, `v`/`q`/`Q` lines will create
 292   subvolumes only if the OS itself is installed into a subvolume. If set to `1`
 293   (or another value interpreted as true), these lines will always create
 294   subvolumes if the backing filesystem supports them. If set to `0`, these
 295   lines will always create directories.