systemd.environment-generator

package: systemd

title: systemd.environment-generator(7)

summary: systemd environment file generators

text:
# systemd.environment-generator(7)

## NAME
systemd.environment-generator - systemd environment file generators

## SYNOPSIS
/usr/lib/systemd/system-environment-generators/some-generator

/usr/lib/systemd/user-environment-generators/some-generator

/run/systemd/system-environment-generators/*

/etc/systemd/system-environment-generators/*

/usr/local/lib/systemd/system-environment-generators/*

/usr/lib/systemd/system-environment-generators/*

/run/systemd/user-environment-generators/*

/etc/systemd/user-environment-generators/*

/usr/local/lib/systemd/user-environment-generators/*

/usr/lib/systemd/user-environment-generators/*

## DESCRIPTION
Generators are small executables that live in /usr/lib/systemd/system-environment-generators/ and other directories listed above. systemd(1) will execute those binaries very early at the startup of each manager and at configuration reload time, before running the generators described in systemd.generator(7) and before starting any units. Environment generators can override the environment that the manager exports to services and other processes.

Generators are loaded from a set of paths determined during compilation, as listed above. System and user environment generators are loaded from directories with names ending in system-environment-generators/ and user-environment-generators/, respectively. Generators found in directories listed earlier override the ones with the same name in directories lower in the list [1]. A symlink to /dev/null or an empty file can be used to mask a generator, thereby preventing it from running. Please note that the order of the two directories with the highest priority is reversed with respect to the unit load path, and generators in /run/ overwrite those in /etc/.

After installing new generators or updating the configuration, systemctl daemon-reload may be executed. This will re-run all generators, updating environment configuration. It will be used for any services that are started subsequently.

Environment file generators are executed similarly to unit file generators described in systemd.generator(7), with the following differences:

•Generators are executed sequentially in the alphanumerical order of the final component of their name. The output of each generator output is immediately parsed and used to update the environment for generators that run after that. Thus, later generators can use and/or modify the output of earlier generators.

•Generators are run by every manager instance, their output can be different for each user.

It is recommended to use numerical prefixes for generator names to simplify ordering.

## EXAMPLES
Example 1. A simple generator that extends an environment variable if a directory exists in the file system

```
# 50-xdg-data-dirs.sh
#!/bin/sh
# SPDX-License-Identifier: MIT-0
# set the default value
XDG_DATA_DIRS="${XDG_DATA_DIRS:-/usr/local/share/:/usr/share}"
# add a directory if it exists
if [ -d /opt/foo/share ]; then

    XDG_DATA_DIRS="/opt/foo/share:${XDG_DATA_DIRS}"
fi
# write our output
echo "XDG_DATA_DIRS=${XDG_DATA_DIRS}"
```

Example 2. A more complicated generator which reads existing configuration and mutates one variable

```
# 90-rearrange-path.py
#!/usr/bin/python
# SPDX-License-Identifier: MIT-0
"""
Proof-of-concept systemd environment generator that makes sure that bin dirs
are always after matching sbin dirs in the path.
(Changes /sbin:/bin:/foo/bar to /bin:/sbin:/foo/bar.)
This generator shows how to override the configuration possibly created by
earlier generators. It would be easier to write in bash, but let's have it
in Python just to prove that we can, and to serve as a template for more
interesting generators.
"""
import os
import pathlib
def rearrange_bin_sbin(path):

    """Make sure any pair of .../bin, .../sbin directories is in this order

    >>> rearrange_bin_sbin('/bin:/sbin:/usr/sbin:/usr/bin')

    '/bin:/sbin:/usr/bin:/usr/sbin'

    """

    items = [pathlib.Path(p) for p in path.split(':')]

    for i in range(len(items)):

        if 'sbin' in items[i].parts:

            ind = items[i].parts.index('sbin')

            bin = pathlib.Path(*items[i].parts[:ind], 'bin', *items[i].parts[ind+1:])

            if bin in items[i+1:]:

                j = i + 1 + items[i+1:].index(bin)

                items[i], items[j] = items[j], items[i]

    return ':'.join(p.as_posix() for p in items)
if __name__ == '__main__':

    path = os.environ['PATH'] # This should be always set.

                              # If it is not, we will just crash, which is OK too.

    new = rearrange_bin_sbin(path)

    if new != path:

        print('PATH={}'.format(new))
```

Example 3. Debugging a generator

```
SYSTEMD_LOG_LEVEL=debug VAR_A=something VAR_B="something else" \
/usr/lib/systemd/system-environment-generators/path-to-generator
```

## SEE ALSO
systemd-environment-d-generator(8), systemd.generator(7), systemd(1), systemctl(1)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.

branch: sisyphus


systemd.generator

title: systemd.generator(7)

summary: systemd unit generators

text:
# systemd.generator(7)

## NAME
systemd.generator - systemd unit generators

## SYNOPSIS
/path/to/generator normal-dir [early-dir] [late-dir]

/run/systemd/system-generators/*

/etc/systemd/system-generators/*

/usr/local/lib/systemd/system-generators/*

/usr/lib/systemd/system-generators/*

/run/systemd/user-generators/*

/etc/systemd/user-generators/*

/usr/local/lib/systemd/user-generators/*

/usr/lib/systemd/user-generators/*

## DESCRIPTION
Generators are small executables placed in /usr/lib/systemd/system-generators/ and other directories listed above. systemd(1) will execute these binaries very early at bootup and at configuration reload time — before unit files are loaded. Their main purpose is to convert configuration and execution context parameters that are not native to the service manager into dynamically generated unit files, symlinks or unit file drop-ins, so that they can extend the unit file hierarchy the service manager subsequently loads and operates on.

systemd will call each generator with three directory paths that are to be used for generator output. In these three directories, generators may dynamically generate unit files (regular ones, instances, as well as templates), unit file .d/ drop-ins, and create symbolic links to unit files to add additional dependencies, create aliases, or instantiate existing templates. Those directories are included in the unit load path, allowing generated configuration to extend or override existing definitions. For tests, generators may be called with just one argument; the generator should assume that all three paths are the same in that case.

Generators executed by the system manager are invoked in a sandbox with a private writable /tmp/ directory and where most of the file system is read-only except for the generator output directories.

Directory paths for generator output differ by priority: .../generator.early has priority higher than the admin configuration in /etc/, while .../generator has lower priority than /etc/ but higher than vendor configuration in /usr/, and .../generator.late has priority lower than all other configuration. See the next section and the discussion of unit load paths and unit overriding in systemd.unit(5).

Generators are loaded from a set of paths determined during compilation, as listed above. System and user generators are loaded from directories with names ending in system-generators/ and user-generators/, respectively. Generators found in directories listed earlier override the ones with the same name in directories lower in the list [1]. A symlink to /dev/null or an empty file can be used to mask a generator, thereby preventing it from running. Please note that the order of the two directories with the highest priority is reversed with respect to the unit load path, and generators in /run/ overwrite those in /etc/.

After installing new generators or updating the configuration, systemctl daemon-reload may be executed. This will delete the previous configuration created by generators, re-run all generators, and cause systemd to reload units from disk. See systemctl(1) for more information.

## OUTPUT DIRECTORIES
Generators are invoked with three arguments: paths to directories where generators can place their generated unit files or symlinks. By default, those paths are runtime directories that are included in the search path of systemd, but a generator may be called with different paths for debugging purposes. If only one argument is provided, the generator should use the same directory as the three output paths.

1.normal-dir In normal use this is /run/systemd/generator in case of the system generators and $XDG_RUNTIME_DIR/systemd/generator in case of the user generators. Unit files placed in this directory take precedence over vendor unit configuration but not over native user/administrator unit configuration.

2.early-dir In normal use this is /run/systemd/generator.early in case of the system generators and $XDG_RUNTIME_DIR/systemd/generator.early in case of the user generators. Unit files placed in this directory override unit files in /usr/, /run/ and /etc/. This means that unit files placed in this directory take precedence over all normal configuration, both vendor and user/administrator.

3.late-dir In normal use this is /run/systemd/generator.late in case of the system generators and $XDG_RUNTIME_DIR/systemd/generator.late in case of the user generators. This directory may be used to extend the unit file tree without overriding any other unit files. Any native configuration files supplied by the vendor or user/administrator take precedence.

Note: generators must not write to other locations or otherwise make changes to system state. Generator output is supposed to last only until the next daemon-reload or daemon-reexec; if the generator is replaced or masked, its effects should vanish.

## ENVIRONMENT
The service manager sets a number of environment variables when invoking generator executables. They carry information about the execution context of the generator, in order to simplify conditionalizing generators to specific environments. The following environment variables are set:

$SYSTEMD_SCOPE

If the generator is invoked from the system service manager this variable is set to "system"; if invoked from the per-user service manager it is set to "user". Added in version 251.

$SYSTEMD_IN_INITRD

If the generator is run as part of an initrd this is set to "1". If it is run from the regular host (i.e. after the transition from initrd to host) it is set to "0". This environment variable is only set for system generators. Added in version 251.

$SYSTEMD_SOFT_REBOOTS_COUNT

If the system has soft-rebooted, this variable is set to the count of soft-reboots. This environment variable is only set for system generators. Added in version 257.

$SYSTEMD_FIRST_BOOT

If this boot-up cycle is considered a "first boot", this is set to "1"; if it is a subsequent, regular boot it is set to "0". For details see the documentation of ConditionFirstBoot= in systemd.unit(5). This environment variable is only set for system generators. Added in version 251.

$SYSTEMD_VIRTUALIZATION

If the service manager is run in a virtualized environment, $SYSTEMD_VIRTUALIZATION is set to a pair of strings, separated by a colon. The first string is either "vm" or "container", categorizing the type of virtualization. The second string identifies the implementation of the virtualization technology. If no virtualization is detected this variable will not be set. This data is identical to what systemd-detect-virt(1) detects and reports, and uses the same vocabulary of virtualization implementation identifiers. Added in version 251.

$SYSTEMD_ARCHITECTURE

This variable is set to a short identifier of the reported architecture of the system. For details about defined values, see documentation of ConditionArchitecture= in systemd.unit(5). Added in version 251.

$CREDENTIALS_DIRECTORY, $ENCRYPTED_CREDENTIALS_DIRECTORY

If set, refers to the directory system credentials have been placed in. Credentials passed into the system in plaintext form will be placed in $CREDENTIALS_DIRECTORY, and those passed in in encrypted form will be placed in $ENCRYPTED_CREDENTIALS_DIRECTORY. Use the systemd-creds(1) command to automatically decrypt/authenticate credentials passed in, if needed. Specifically, use the systemd-creds --system cat command. Added in version 254.

$SYSTEMD_CONFIDENTIAL_VIRTUALIZATION

If the service manager is run in a confidential virtualized environment, $SYSTEMD_CONFIDENTIAL_VIRTUALIZATION is set to a string that identifies the confidential virtualization hardware technology. If no confidential virtualization is detected this variable will not be set. This data is identical to what systemd-detect-virt(1) detects and reports, and uses the same vocabulary of confidential virtualization technology identifiers. Added in version 254.

## NOTES ABOUT WRITING GENERATORS
•All generators are executed in parallel. That means all executables are started at the very same time and need to be able to cope with this parallelism.

•Generators are run very early at boot and cannot rely on any external services. They may not talk to any other process. That includes simple things such as logging to syslog(3), or systemd itself (this means: no systemctl(1))! Non-essential file systems like /var/ and /home/ are mounted after generators have run. Generators can however rely on the most basic kernel functionality to be available, as well as mounted /sys/, /proc/, /dev/, /usr/ and /run/ file systems.

•Units written by generators are removed when the configuration is reloaded. That means the lifetime of the generated units is closely bound to the reload cycles of systemd itself.

•Generators should only be used to generate unit files, .d/*.conf drop-ins for them and symlinks to them, not any other kind of non-unit related configuration. Due to the lifecycle logic mentioned above, generators are not a good fit to generate dynamic configuration for other services. If you need to generate dynamic configuration for other services, do so in normal services you order before the service in question. Note that using the StandardInputData=/StandardInputText= settings of service unit files (see systemd.exec(5)), it is possible to make arbitrary input data (including daemon-specific configuration) part of the unit definitions, which often might be sufficient to embed data or configuration for other programs into unit files in a native fashion.

•Since syslog(3) is not available (see above), log messages have to be written to /dev/kmsg instead.

•The generator should always include its own name in a comment at the top of the generated file, so that the user can easily figure out which component created or amended a particular unit. The SourcePath= directive should be used in generated files to specify the source configuration file they are generated from. This makes things more easily understood by the user and also has the benefit that systemd can warn the user about configuration files that changed on disk but have not been read yet by systemd. The SourcePath= value does not have to be a file in a physical filesystem. For example, in the common case of the generator looking at the kernel command line, SourcePath=/proc/cmdline should be used.

•Generators may write out dynamic unit files or just hook unit files into other units with the usual .wants/ or .requires/ symlinks. Often, it is nicer to simply instantiate a template unit file from /usr/ with a generator instead of writing out entirely dynamic unit files. Of course, this works only if a single parameter is to be used.

•If you are careful, you can implement generators in shell scripts. We do recommend C code however, since generators are executed synchronously and hence delay the entire boot if they are slow.

•Regarding overriding semantics: there are two rules we try to follow when thinking about the overriding semantics:

1.User configuration should override vendor configuration. This (mostly) means that stuff from /etc/ should override stuff from /usr/.

2.Native configuration should override non-native configuration. This (mostly) means that stuff you generate should never override native unit files for the same purpose.

Of these two rules the first rule is probably the more important one and breaks the second one sometimes. Hence, when deciding whether to use argv[1], argv[2], or argv[3], your default choice should probably be argv[1].

•Instead of heading off now and writing all kind of generators for legacy configuration file formats, please think twice! It is often a better idea to just deprecate old stuff instead of keeping it artificially alive.

## EXAMPLES
Example 1. systemd-fstab-generator

systemd-fstab-generator(8) converts /etc/fstab into native mount units. It uses argv[1] as location to place the generated unit files in order to allow the user to override /etc/fstab with their own native unit files, but also to ensure that /etc/fstab overrides any vendor default from /usr/.

After editing /etc/fstab, the user should invoke systemctl daemon-reload. This will re-run all generators and cause systemd to reload units from disk. To actually mount new directories added to fstab, systemctl start /path/to/mountpoint or systemctl start local-fs.target may be used.

Example 2. systemd-system-update-generator

systemd-system-update-generator(8) temporarily redirects default.target to system-update.target, if a system update is scheduled. Since this needs to override the default user configuration for default.target, it uses argv[2]. For details about this logic, see systemd.offline-updates(7).

Example 3. Debugging a generator

```
dir=$(mktemp -d)
SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \

        "$dir" "$dir" "$dir"
find $dir
```

## SEE ALSO
systemd(1), systemd-cryptsetup-generator(8), systemd-debug-generator(8), systemd-fstab-generator(8), fstab(5), systemd-getty-generator(8), systemd-gpt-auto-generator(8), systemd-hibernate-resume-generator(8), systemd-rc-local-generator(8), systemd-system-update-generator(8), systemd-sysv-generator(8), systemd-xdg-autostart-generator(8), systemd.unit(5), systemctl(1), systemd.environment-generator(7)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.


systemd.image-filter

title: systemd.image-filter(7)

summary: Disk Image Dissection Filter

text:
# systemd.image-filter(7)

## NAME
systemd.image-filter - Disk Image Dissection Filter

## DESCRIPTION
In systemd, whenever a disk image (DDI) implementing the Discoverable Partitions Specification[1] is activated, a filter may be specified controlling which partitions to consider for mounting. Such a disk image dissection filter is a string that contains per-partition-type patterns, separated by colons (":"). The individual rules consist of a partition identifier, an equal sign ("="), and a shell globbing pattern applied to the GPT label string of the partition. See glob(7) for details on shell globbing.

The partition identifiers currently defined are: root, usr, home, srv, esp, xbootldr, swap, root-verity, root-verity-sig, usr-verity, usr-verity-sig, tmp, var. These identifiers match the relevant partition types in the Discoverable Partitions Specification, but are agnostic to CPU architectures.

## USE
Various systemd components that support operating with disk images support a --image-filter= command line option to specify the image filter to use. If no filter is specified all partitions in partition table are considered and no per-label filtering is applied (except that partitions with the "_empty" label are always ignored).

For the host root file system image itself systemd-gpt-auto-generator(8) is responsible for processing the GPT partition table and making use of the included discoverable partitions. It accepts an image filter via the kernel command line option systemd.image_filter=.

## EXAMPLES
The following image filter string dictates that for the root file system partition only partitions shall be considered whose label begins with "ParticleOS-". For the /usr/ partition the precise label "ParticleOS_47110815" is required.

```
root=ParticleOS-*:usr=ParticleOS_47110815
```

## SEE ALSO
systemd(1), systemd-dissect(1), systemd-gpt-auto-generator(8), systemd.image-policy(7)

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification


systemd.image-policy

title: systemd.image-policy(7)

summary: Disk Image Dissection Policy

text:
# systemd.image-policy(7)

## NAME
systemd.image-policy - Disk Image Dissection Policy

## DESCRIPTION
In systemd, whenever a disk image (DDI) implementing the Discoverable Partitions Specification[1] is activated, a policy may be specified controlling which partitions to mount and what kind of cryptographic protection to require. Such a disk image dissection policy is a string that contains per-partition-type rules, separated by colons (":"). The individual rules consist of a partition identifier, an equal sign ("="), and one or more flags which may be set per partition. If multiple flags are specified per partition they are separated by a plus sign ("+").

The partition identifiers currently defined are: root, usr, home, srv, esp, xbootldr, swap, root-verity, root-verity-sig, usr-verity, usr-verity-sig, tmp, var. These identifiers match the relevant partition types in the Discoverable Partitions Specification, but are agnostic to CPU architectures. If the partition identifier is left empty it defines the default policy for partitions defined in the Discoverable Partitions Specification for which no policy flags are explicitly listed in the policy string.

The following partition policy flags are defined that dictate the existence/absence, the use, and the protection level of partitions:

•unprotected for partitions that shall exist and be used, but shall come without cryptographic protection, lacking both Verity authentication and LUKS encryption.

•verity for partitions that shall exist and be used, with Verity authentication. (Note: if a DDI image carries a data partition, along with a Verity partition and a signature partition for it, and only the verity flag is set (signed is not), then the image will be set up with Verity, but the signature data will not be used. Or in other words: any DDI with a set of partitions that qualify for signature also implicitly qualifies for verity, and in fact also unprotected).

•signed for partitions that shall exist and be used, with Verity authentication, which are also accompanied by a PKCS#7 signature of the Verity root hash.

•encrypted for partitions which shall exist and be used and are encrypted with LUKS.

•unused for partitions that shall exist but shall not be used.

•absent for partitions that shall not exist on the image.

By setting a combination of the flags above, alternatives can be declared. For example the combination "unused+absent" means: the partition may exist (in which case it shall not be used) or may be absent. The combination of "unprotected+verity+signed+encrypted+unused+absent" may be specified via the special shortcut "open", and indicates that the partition may exist or may be absent, but if it exists is used, regardless of the protection level.

As special rule: if none of the flags above are set for a listed partition identifier, the default policy of open is implied, i.e. setting none of these flags listed above means effectively all flags listed above will be set.

The following partition policy flags are defined that dictate the state of specific GPT partition flags:

•read-only-off, read-only-on to require that the partitions have the read-only partition flag off or on.

•growfs-off, growfs-on to require that the partitions have the growfs partition flag off or on.

If both read-only-off and read-only-on are set for a partition, then the state of the read-only flag on the partition is not dictated by the policy. Setting neither flag is equivalent to setting both, i.e. setting neither of these two flags means effectively both will be set. A similar logic applies to growfs-off/growfs-on.

If partitions are not listed within an image policy string, the default policy flags are applied (configurable via an empty partition identifier, see above). If no default policy flags are configured in the policy string, it is implied to be "absent+unused", except for the Verity partition and their signature partitions where the policy is automatically derived from minimal protection level of the data partition they protect, as encoded in the policy.

## SPECIAL POLICIES
The special image policy string "*" is short for "use everything", i.e. is equivalent to:

```
=verity+signed+encrypted+unprotected+unused+absent
```

The special image policy string "-" is short for "use nothing", i.e. is equivalent to:

```
=unused+absent
```

The special image policy string "~" is short for "everything must be absent", i.e. is equivalent to:

```
=absent
```

## USE
Most systemd components that support operating with disk images support a --image-policy= command line option to specify the image policy to use, and default to relatively open policies (typically the "*" policy, as described above), under the assumption that trust in disk images is established before the images are passed to the program in question.

For the host image itself systemd-gpt-auto-generator(8) is responsible for processing the GPT partition table and making use of the included discoverable partitions. It accepts an image policy via the kernel command line option systemd.image_policy=.

Note that image policies do not dictate how the components will mount and use disk images — they only dictate which parts to avoid and which protection level and arrangement to require while mounting/using them. For example, systemd-sysext(8) only cares for the /usr/ and /opt/ trees inside a disk image, and thus ignores any /home/ partitions (and similar) in all cases, which might be included in the image, regardless whether the configured image policy would allow access to it or not. Similar, systemd-nspawn(1) is not going to make use of any discovered swap device, regardless of whether the policy would allow that or not.

Use the image-policy command of the systemd-analyze(1) tool to analyze image policy strings, and determine what a specific policy string means for a specific partition.

## EXAMPLES
The following image policy string dictates one read-only Verity-enabled /usr/ partition must exist, plus encrypted root and swap partitions. All other partitions are ignored:

```
usr=verity+read-only-on:root=encrypted:swap=encrypted
```

The following image policy string dictates an encrypted, writable root file system, and optional /srv/ file system that must be encrypted if it exists and no swap partition may exist:

```
root=encrypted+read-only-off:srv=encrypted+absent:swap=absent
```

The following image policy string dictates a single root partition that may be encrypted, but does not have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption.

```
root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent
```

## SEE ALSO
systemd(1), systemd-dissect(1), systemd-gpt-auto-generator(8), systemd-sysext(8), systemd-analyze(1)

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification