diff --git a/Makefile-man.am b/Makefile-man.am index 6f59658445b..86ea6afbe71 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -146,6 +146,7 @@ MANPAGES += \ man/systemd.1 \ man/systemd.automount.5 \ man/systemd.device.5 \ + man/systemd.environment-generator.7 \ man/systemd.exec.5 \ man/systemd.generator.7 \ man/systemd.journal-fields.7 \ @@ -2827,6 +2828,7 @@ EXTRA_DIST += \ man/systemd-volatile-root.service.xml \ man/systemd.automount.xml \ man/systemd.device.xml \ + man/systemd.environment-generator.xml \ man/systemd.exec.xml \ man/systemd.generator.xml \ man/systemd.journal-fields.xml \ diff --git a/Makefile.am b/Makefile.am index f6699252d1e..67c433b43a6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -765,7 +765,9 @@ EXTRA_DIST += \ tools/make-man-rules.py \ tools/make-directive-index.py \ tools/xml_helper.py \ - man/glib-event-glue.c + man/glib-event-glue.c \ + man/50-xdg-data-dirs.sh \ + man/90-rearrange-path.py # ------------------------------------------------------------------------------ noinst_LTLIBRARIES += \ diff --git a/man/50-xdg-data-dirs.sh b/man/50-xdg-data-dirs.sh new file mode 100755 index 00000000000..073174cb401 --- /dev/null +++ b/man/50-xdg-data-dirs.sh @@ -0,0 +1,12 @@ +#!/bin/bash + +# 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 diff --git a/man/90-rearrange-path.py b/man/90-rearrange-path.py new file mode 100755 index 00000000000..c6ff32210f6 --- /dev/null +++ b/man/90-rearrange-path.py @@ -0,0 +1,40 @@ +#!/usr/bin/python3 + +""" + +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's not, we'll just crash, we is OK too. + new = rearrange_bin_sbin(path) + if new != path: + print('PATH={}'.format(new)) diff --git a/man/systemd.environment-generator.xml b/man/systemd.environment-generator.xml new file mode 100644 index 00000000000..e162dfcbae5 --- /dev/null +++ b/man/systemd.environment-generator.xml @@ -0,0 +1,159 @@ + + +%entities; +]> + + + + + + systemd.environment-generator + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd.environment-generator + 7 + + + + systemd.environment-generator + Systemd environment file generators + + + + + &systemenvgeneratordir;/some-generator + + + &userenvgeneratordir;/some-generator + + + + /run/systemd/system-environment-generators/* +/etc/systemd/system-environment-generators/* +/usr/local/lib/systemd/system-environment-generators/* +&systemenvgeneratordir;/* + + + + /run/systemd/user-environment-generators/* +/etc/systemd/user-environment-generators/* +/usr/local/lib/systemd/user-environment-generators/* +&userenvgeneratordir;/* + + + + + Description + Generators are small executables that live in + &systemenvgeneratordir;/ and other directories listed above. + systemd1 will + execute those binaries very early at the startup of each manager and at configuration + reload time, before running the generators described in + systemd.generator7 + 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. 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.generator7, + 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 + + + A simple generator that extends an environment variable if a directory exists in the file system + + # 50-xdg-data-dirs.sh + + + + + + A more complicated generator which reads existing configuration and mutates one variable + + # 90-rearrange-path.py + + + + + + Debugging a generator + + SYSTEMD_LOG_LEVEL=debug VAR_A=something VAR_B="something else" \ +&systemenvgeneratordir;/path-to-generator + + + + + + See also + + + systemd.generator7, + systemd1, + systemctl1 + + + diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index b268104c9de..fb0f0c4da8c 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -342,7 +342,8 @@ find $dir systemd-system-update-generator8, systemd-sysv-generator8, systemd.unit5, - systemctl1 + systemctl1, + systemd.environment-generator7