man/systemd.environment-generator.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2017 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd.environment-generator" xmlns:xi="http://www.w3.org/2001/XInclude">
  28   <refentryinfo>
  29     <title>systemd.environment-generator</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Zbigniew</firstname>
  36         <surname>Jędrzejewski-Szmek</surname>
  37         <email>zbyszek@in.waw.pl</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>systemd.environment-generator</refentrytitle>
  44     <manvolnum>7</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>systemd.environment-generator</refname>
  49     <refpurpose>Systemd environment file generators</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <cmdsynopsis>
  54       <command>&systemenvgeneratordir;/some-generator</command>
  55     </cmdsynopsis>
  56     <cmdsynopsis>
  57       <command>&userenvgeneratordir;/some-generator</command>
  58     </cmdsynopsis>
  59
  60     <para>
  61       <literallayout><filename>/run/systemd/system-environment-generators/*</filename>
  62 <filename>/etc/systemd/system-environment-generators/*</filename>
  63 <filename>/usr/local/lib/systemd/system-environment-generators/*</filename>
  64 <filename>&systemenvgeneratordir;/*</filename></literallayout>
  65     </para>
  66
  67     <para>
  68       <literallayout><filename>/run/systemd/user-environment-generators/*</filename>
  69 <filename>/etc/systemd/user-environment-generators/*</filename>
  70 <filename>/usr/local/lib/systemd/user-environment-generators/*</filename>
  71 <filename>&userenvgeneratordir;/*</filename></literallayout>
  72     </para>
  73   </refsynopsisdiv>
  74
  75   <refsect1>
  76     <title>Description</title>
  77     <para>Generators are small executables that live in
  78     <filename>&systemenvgeneratordir;/</filename> and other directories listed above.
  79     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will
  80     execute those binaries very early at the startup of each manager and at configuration
  81     reload time, before running the generators described in
  82     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  83     and before starting any units. Environment generators can override the environment that the
  84     manager exports to services and other processes.</para>
  85
  86     <para>Generators are loaded from a set of paths determined during compilation, as listed
  87     above. System and user environment generators are loaded from directories with names ending in
  88     <filename>system-environment-generators/</filename> and
  89     <filename>user-environment-generators/</filename>, respectively. Generators found in directories
  90     listed earlier override the ones with the same name in directories lower in the list. A symlink
  91     to <filename>/dev/null</filename> or an empty file can be used to mask a generator, thereby
  92     preventing it from running. Please note that the order of the two directories with the highest
  93     priority is reversed with respect to the unit load path, and generators in
  94     <filename>/run</filename> overwrite those in <filename>/etc</filename>.</para>
  95
  96     <para>After installing new generators or updating the configuration, <command>systemctl
  97     daemon-reload</command> may be executed. This will re-run all generators, updating environment
  98     configuration. It will be used for any services that are started subsequently.</para>
  99
 100     <para>Environment file generators are executed similarly to unit file generators described
 101     in
 102     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 103     with the following differences:</para>
 104
 105     <itemizedlist>
 106       <listitem>
 107         <para>Generators are executed sequentially in the alphanumerical order of the final
 108         component of their name. The output of each generator output is immediately parsed and used
 109         to update the environment for generators that run after that. Thus, later generators can use
 110         and/or modify the output of earlier generators.</para>
 111       </listitem>
 112
 113       <listitem>
 114         <para>Generators are run by every manager instance, their output can be different for each
 115         user.</para>
 116       </listitem>
 117     </itemizedlist>
 118
 119     <para>It is recommended to use numerical prefixes for generator names to simplify ordering.</para>
 120   </refsect1>
 121
 122   <refsect1>
 123     <title>Examples</title>
 124
 125     <example>
 126       <title>A simple generator that extends an environment variable if a directory exists in the file system</title>
 127
 128       <programlisting># 50-xdg-data-dirs.sh
 129
 130 <xi:include href="50-xdg-data-dirs.sh" parse="text" /></programlisting>
 131     </example>
 132
 133     <example>
 134       <title>A more complicated generator which reads existing configuration and mutates one variable</title>
 135
 136       <programlisting># 90-rearrange-path.py
 137
 138 <xi:include href="90-rearrange-path.py" parse="text" /></programlisting>
 139     </example>
 140
 141     <example>
 142       <title>Debugging a generator</title>
 143
 144       <programlisting>SYSTEMD_LOG_LEVEL=debug VAR_A=something VAR_B="something else" \
 145 &systemenvgeneratordir;/path-to-generator
 146 </programlisting>
 147     </example>
 148   </refsect1>
 149
 150   <refsect1>
 151     <title>See also</title>
 152
 153     <para>
 154       <citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 155       <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 156       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 158     </para>
 159   </refsect1>
 160 </refentry>