Merge pull request #23065 from poettering/env-var-generator

pid1: pass additional env vars about exec context to generators

TODO

@@ -441,11 +441,6 @@ Features:
   https://github.com/dvdhrm/docs/blob/master/drm-howto/modeset.c for an example
   for doing that.
 
-* pass systemd-detect-virt result to generators as env var. Modifying behaviour
-  based on whether we are virtualized or not is a pretty common thing, hence
-  maybe just pass that info along for free in an env var. We cache the result
-  anyway, so it's basically free.
-
 * introduce /dev/disk/root/* symlinks that allow referencing partitions on the
   disk the rootfs is on in a reasonably secure way. (or maybe: add
   /dev/gpt-auto-{home,srv,boot,…} similar in style to /dev/gpt-auto-root as we

man/systemd.generator.xml

@@ -51,107 +51,150 @@
     directories listed above.
     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 that is not native to the service manager into
+    loaded. Their main purpose is to convert configuration and execution context parameters that are not
-    dynamically generated unit files, symlinks or unit file drop-ins, so that they can extend the unit file
+    native to the service manager into dynamically generated unit files, symlinks or unit file drop-ins, so
-    hierarchy the service manager subsequently loads and operates on.</para>
+    that they can extend the unit file hierarchy the service manager subsequently loads and operates
+    on.</para>
 
-    <para>Each generator is called with three directory paths that are to be used for
+    <para>Each generator is called with three directory paths that are to be used for generator output. In
-    generator output. In these three directories, generators may dynamically generate
+    these three directories, generators may dynamically generate unit files (regular ones, instances, as well
-    unit files (regular ones, instances, as well as templates), unit file
+    as templates), unit file <filename>.d/</filename> drop-ins, and create symbolic links to unit files to
-    <filename>.d/</filename> drop-ins, and create symbolic links to unit files to add
+    add additional dependencies, create aliases, or instantiate existing templates. Those directories are
-    additional dependencies, create aliases, or instantiate existing templates. Those
+    included in the unit load path of
-    directories are included in the unit load path of
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, allowing
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+    generated configuration to extend or override existing definitions.</para>
-    allowing generated configuration to extend or override existing
-    definitions.</para>
 
-    <para>Directory paths for generator output differ by priority:
+    <para>Directory paths for generator output differ by priority: <filename>…/generator.early</filename> has
-    <filename>…/generator.early</filename> has priority higher than the admin
+    priority higher than the admin configuration in <filename>/etc/</filename>, while
-    configuration in <filename>/etc/</filename>, while
+    <filename>…/generator</filename> has lower priority than <filename>/etc/</filename> but higher than
-    <filename>…/generator</filename> has lower priority than
+    vendor configuration in <filename>/usr/</filename>, and <filename>…/generator.late</filename> has
-    <filename>/etc/</filename> but higher than vendor configuration in
+    priority lower than all other configuration. See the next section and the discussion of unit load paths
-    <filename>/usr/</filename>, and <filename>…/generator.late</filename> has priority
+    and unit overriding in
-    lower than all other configuration. See the next section and the discussion of
-    unit load paths and unit overriding in
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>
 
-    <para>Generators are loaded from a set of paths determined during
+    <para>Generators are loaded from a set of paths determined during compilation, as listed above. System
-    compilation, as listed above. System and user generators are loaded
+    and user generators are loaded from directories with names ending in
-    from directories with names ending in
+    <filename>system-generators/</filename> and <filename>user-generators/</filename>,
-    <filename>system-generators/</filename> and
+    respectively. Generators found in directories listed earlier override the ones with the same name in
-    <filename>user-generators/</filename>, respectively. Generators
+    directories lower in the list. A symlink to <filename>/dev/null</filename> or an empty file can be used
-    found in directories listed earlier override the ones with the
+    to mask a generator, thereby preventing it from running. Please note that the order of the two
-    same name in directories lower in the list. A symlink to
+    directories with the highest priority is reversed with respect to the unit load path, and generators in
-    <filename>/dev/null</filename> or an empty file can be used to
+    <filename>/run/</filename> overwrite those in <filename>/etc/</filename>.</para>
-    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
-    <filename>/run/</filename> overwrite those in
-    <filename>/etc/</filename>.</para>
 
-    <para>After installing new generators or updating the
+    <para>After installing new generators or updating the configuration, <command>systemctl
-    configuration, <command>systemctl daemon-reload</command> may be
+    daemon-reload</command> may be executed. This will delete the previous configuration created by
-    executed. This will delete the previous configuration created by
+    generators, re-run all generators, and cause <command>systemd</command> to reload units from disk. See
-    generators, re-run all generators, and cause
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more
-    <command>systemd</command> to reload units from disk. See
+    information.
-    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    for more information.
     </para>
   </refsect1>
 
   <refsect1>
     <title>Output directories</title>
 
-    <para>Generators are invoked with three arguments: paths to directories where
+    <para>Generators are invoked with three arguments: paths to directories where generators can place their
-    generators can place their generated unit files or symlinks. By default those
+    generated unit files or symlinks. By default those paths are runtime directories that are included in the
-    paths are runtime directories that are included in the search path of
+    search path of <command>systemd</command>, but a generator may be called with different paths for
-    <command>systemd</command>, but a generator may be called with different paths
+    debugging purposes.</para>
-    for debugging purposes.</para>
 
     <orderedlist>
       <listitem>
         <para><parameter>normal-dir</parameter></para>
-        <para>In normal use this is <filename>/run/systemd/generator</filename> in
+        <para>In normal use this is <filename>/run/systemd/generator</filename> in case of the system
-        case of the system generators and
+        generators and <filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user generators. Unit
-        <filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user
+        files placed in this directory take precedence over vendor unit configuration but not over native
-        generators. Unit files placed in this directory take precedence over vendor
+        user/administrator unit configuration.
-        unit configuration but not over native user/administrator unit configuration.
         </para>
       </listitem>
 
       <listitem>
         <para><parameter>early-dir</parameter></para>
-        <para>In normal use this is <filename>/run/systemd/generator.early</filename>
+        <para>In normal use this is <filename>/run/systemd/generator.early</filename> in case of the system
-        in case of the system generators and
+        generators and <filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
-        <filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
+        generators. Unit files placed in this directory override unit files in <filename>/usr/</filename>,
-        generators. Unit files placed in this directory override unit files in
+        <filename>/run/</filename> and <filename>/etc/</filename>. This means that unit files placed in this
-        <filename>/usr/</filename>, <filename>/run/</filename> and
+        directory take precedence over all normal configuration, both vendor and user/administrator.</para>
-        <filename>/etc/</filename>. This means that unit files placed in this
-        directory take precedence over all normal configuration, both vendor and
-        user/administrator.</para>
       </listitem>
 
       <listitem>
         <para><parameter>late-dir</parameter></para>
-        <para>In normal use this is <filename>/run/systemd/generator.late</filename>
+        <para>In normal use this is <filename>/run/systemd/generator.late</filename> in case of the system
-        in case of the system generators and
+        generators and <filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
-        <filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
+        generators. This directory may be used to extend the unit file tree without overriding any other unit
-        generators. This directory may be used to extend the unit file tree without
+        files. Any native configuration files supplied by the vendor or user/administrator take
-        overriding any other unit files. Any native configuration files supplied by
+        precedence.</para>
-        the vendor or user/administrator take precedence.</para>
       </listitem>
     </orderedlist>
   </refsect1>
 
+  <refsect1>
+    <title>Environment</title>
+
+    <para>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:</para>
+
+    <variablelist class='environment-variables'>
+      <varlistentry>
+        <term><varname>$SYSTEMD_SCOPE</varname></term>
+
+        <listitem><para>If the generator is invoked from the system service manager this variable is set to
+        <literal>system</literal>; if invoked from the per-user service manager it is set to
+        <literal>user</literal>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>$SYSTEMD_IN_INITRD</varname></term>
+
+        <listitem><para>If the generator is run as part of an initial RAM file system (initrd) this is set to
+        <literal>1</literal>. If it is run from the regular host (i.e. after the transition from initrd to
+        host) it is set to <literal>0</literal>. This environment variable is only set for system
+        generators.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>$SYSTEMD_FIRST_BOOT</varname></term>
+
+        <listitem><para>If this boot-up cycle is considered a "first boot", this is set to
+        <literal>1</literal>; if it is a subsequent, regular boot it is set to <literal>0</literal>. For
+        details see the documentation of <varname>ConditionFirstBoot=</varname> in
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
+        environment variable is only set for system generators.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>$SYSTEMD_VIRTUALIZATION</varname></term>
+
+        <listitem><para>If the service manager is run in a virtualized environment,
+        <varname>$SYSTEMD_VIRTUALIZATION</varname> is set to a pair of strings, separated by a colon. The
+        first string is either <literal>vm</literal> or <literal>container</literal>, 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
+        <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        detects and reports, and uses the same vocabulary of virtualization implementation
+        identifiers.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>$SYSTEMD_ARCHITECTURE</varname></term>
+
+        <listitem><para>This variable is set to a short identifier of the reported architecture of the
+        system. For details about defined values, see documentation of
+        <varname>ConditionArchitecture=</varname> in
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
   <refsect1>
     <title>Notes about writing generators</title>
 
     <itemizedlist>
       <listitem>
-        <para>All generators are executed in parallel. That means all executables are
+        <para>All generators are executed in parallel. That means all executables are started at the very
-        started at the very same time and need to be able to cope with this
+        same time and need to be able to cope with this parallelism.
-        parallelism.
         </para>
       </listitem>
 
@@ -169,9 +212,9 @@
       </listitem>
 
       <listitem>
-        <para>Units written by generators are removed when the configuration is
+        <para>Units written by generators are removed when the configuration is reloaded. That means the
-        reloaded. That means the lifetime of the generated units is closely bound to
+        lifetime of the generated units is closely bound to the reload cycles of <command>systemd</command>
-        the reload cycles of <command>systemd</command> itself.</para>
+        itself.</para>
       </listitem>
 
       <listitem>
@@ -193,8 +236,8 @@
         <para>Since
         <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 
-        is not available (see above), log messages have to be written to
+        is not available (see above), log messages have to be written to <filename>/dev/kmsg</filename>
-        <filename>/dev/kmsg</filename> instead.</para>
+        instead.</para>
       </listitem>
 
       <listitem>
@@ -210,48 +253,44 @@
       </listitem>
 
       <listitem>
-        <para>Generators may write out dynamic unit files or just hook unit files
+        <para>Generators may write out dynamic unit files or just hook unit files into other units with the
-        into other units with the usual <filename>.wants/</filename> or
+        usual <filename>.wants/</filename> or <filename>.requires/</filename> symlinks. Often, it is nicer to
-        <filename>.requires/</filename> symlinks. Often, it is nicer to simply
+        simply instantiate a template unit file from <filename>/usr/</filename> with a generator instead of
-        instantiate a template unit file from <filename>/usr/</filename> with a
+        writing out entirely dynamic unit files. Of course, this works only if a single parameter is to be
-        generator instead of writing out entirely dynamic unit files. Of course, this
+        used.</para>
-        works only if a single parameter is to be used.</para>
       </listitem>
 
       <listitem>
-        <para>If you are careful, you can implement generators in shell scripts. We
+        <para>If you are careful, you can implement generators in shell scripts. We do recommend C code
-        do recommend C code however, since generators are executed synchronously and
+        however, since generators are executed synchronously and hence delay the entire boot if they are
-        hence delay the entire boot if they are slow.</para>
+        slow.</para>
       </listitem>
 
       <listitem>
-        <para>Regarding overriding semantics: there are two rules we try to follow
+        <para>Regarding overriding semantics: there are two rules we try to follow when thinking about the
-        when thinking about the overriding semantics:</para>
+        overriding semantics:</para>
 
         <orderedlist numeration="lowerroman">
           <listitem>
-            <para>User configuration should override vendor configuration. This
+            <para>User configuration should override vendor configuration. This (mostly) means that stuff
-            (mostly) means that stuff from <filename>/etc/</filename> should override
+            from <filename>/etc/</filename> should override stuff from <filename>/usr/</filename>.</para>
-            stuff from <filename>/usr/</filename>.</para>
           </listitem>
 
           <listitem>
-            <para>Native configuration should override non-native configuration. This
+            <para>Native configuration should override non-native configuration. This (mostly) means that
-            (mostly) means that stuff you generate should never override native unit
+            stuff you generate should never override native unit files for the same purpose.</para>
-            files for the same purpose.</para>
           </listitem>
         </orderedlist>
 
-        <para>Of these two rules the first rule is probably the more important one
+        <para>Of these two rules the first rule is probably the more important one and breaks the second one
-        and breaks the second one sometimes. Hence, when deciding whether to use
+        sometimes. Hence, when deciding whether to use argv[1], argv[2], or argv[3], your default choice
-        argv[1], argv[2], or argv[3], your default choice should probably be
+        should probably be argv[1].</para>
-        argv[1].</para>
       </listitem>
 
       <listitem>
-        <para>Instead of heading off now and writing all kind of generators for
+        <para>Instead of heading off now and writing all kind of generators for legacy configuration file
-        legacy configuration file formats, please think twice! It is often a better
+        formats, please think twice! It is often a better idea to just deprecate old stuff instead of keeping
-        idea to just deprecate old stuff instead of keeping it artificially alive.
+        it artificially alive.
         </para>
       </listitem>
     </itemizedlist>
@@ -263,17 +302,15 @@
       <title>systemd-fstab-generator</title>
 
       <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-      converts <filename>/etc/fstab</filename> into native mount units. It uses
+      converts <filename>/etc/fstab</filename> into native mount units. It uses argv[1] as location to place
-      argv[1] as location to place the generated unit files in order to allow the
+      the generated unit files in order to allow the user to override <filename>/etc/fstab</filename> with
-      user to override <filename>/etc/fstab</filename> with their own native unit
+      their own native unit files, but also to ensure that <filename>/etc/fstab</filename> overrides any
-      files, but also to ensure that <filename>/etc/fstab</filename> overrides any
       vendor default from <filename>/usr/</filename>.</para>
 
-      <para>After editing <filename>/etc/fstab</filename>, the user should invoke
+      <para>After editing <filename>/etc/fstab</filename>, the user should invoke <command>systemctl
-      <command>systemctl daemon-reload</command>. This will re-run all generators and
+      daemon-reload</command>. This will re-run all generators and cause <command>systemd</command> to reload
-      cause <command>systemd</command> to reload units from disk. To actually mount
+      units from disk. To actually mount new directories added to <filename>fstab</filename>,
-      new directories added to <filename>fstab</filename>, <command>systemctl start
+      <command>systemctl start <replaceable>/path/to/mountpoint</replaceable></command> or <command>systemctl
-      <replaceable>/path/to/mountpoint</replaceable></command> or <command>systemctl
       start local-fs.target</command> may be used.</para>
     </example>
 
@@ -281,11 +318,9 @@
       <title>systemd-system-update-generator</title>
 
       <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-      temporarily redirects <filename>default.target</filename> to
+      temporarily redirects <filename>default.target</filename> to <filename>system-update.target</filename>,
-      <filename>system-update.target</filename>, if a system update is
+      if a system update is scheduled. Since this needs to override the default user configuration for
-      scheduled. Since this needs to override the default user configuration for
+      <filename>default.target</filename>, it uses argv[2]. For details about this logic, see
-      <filename>default.target</filename>, it uses argv[2]. For details about this
-      logic, see
       <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
       </para>
     </example>

src/core/manager.c

@@ -3665,9 +3665,67 @@ static int manager_run_environment_generators(Manager *m) {
         return r;
 }
 
+static int build_generator_environment(Manager *m, char ***ret) {
+        _cleanup_strv_free_ char **nl = NULL;
+        Virtualization v;
+        int r;
+
+        assert(m);
+        assert(ret);
+
+        /* Generators oftentimes want to know some basic facts about the environment they run in, in order to
+         * adjust generated units to that. Let's pass down some bits of information that are easy for us to
+         * determine (but a bit harder for generator scripts to determine), as environment variables. */
+
+        nl = strv_copy(m->transient_environment);
+        if (!nl)
+                return -ENOMEM;
+
+        r = strv_env_assign(&nl, "SYSTEMD_SCOPE", MANAGER_IS_SYSTEM(m) ? "system" : "user");
+        if (r < 0)
+                return r;
+
+        if (MANAGER_IS_SYSTEM(m)) {
+                /* Note that $SYSTEMD_IN_INITRD may be used to override the initrd detection in much of our
+                 * codebase. This is hence more than purely informational. It will shortcut detection of the
+                 * initrd state if generators invoke our own tools. But that's OK, as it would come to the
+                 * same results (hopefully). */
+                r = strv_env_assign(&nl, "SYSTEMD_IN_INITRD", one_zero(in_initrd()));
+                if (r < 0)
+                        return r;
+
+                if (m->first_boot >= 0) {
+                        r = strv_env_assign(&nl, "SYSTEMD_FIRST_BOOT", one_zero(m->first_boot));
+                        if (r < 0)
+                                return r;
+                }
+        }
+
+        v = detect_virtualization();
+        if (v < 0)
+                log_debug_errno(v, "Failed to detect virtualization, ignoring: %m");
+        else if (v > 0) {
+                const char *s;
+
+                s = strjoina(VIRTUALIZATION_IS_VM(v) ? "vm:" :
+                             VIRTUALIZATION_IS_CONTAINER(v) ? "container:" : ":",
+                             virtualization_to_string(v));
+
+                r = strv_env_assign(&nl, "SYSTEMD_VIRTUALIZATION", s);
+                if (r < 0)
+                        return r;
+        }
+
+        r = strv_env_assign(&nl, "SYSTEMD_ARCHITECTURE", architecture_to_string(uname_architecture()));
+        if (r < 0)
+                return r;
+
+        *ret = TAKE_PTR(nl);
+        return 0;
+}
+
 static int manager_run_generators(Manager *m) {
-        _cleanup_strv_free_ char **paths = NULL;
+        _cleanup_strv_free_ char **paths = NULL, **ge = NULL;
-        const char *argv[5];
         int r;
 
         assert(m);
@@ -3688,15 +3746,27 @@ static int manager_run_generators(Manager *m) {
                 goto finish;
         }
 
-        argv[0] = NULL; /* Leave this empty, execute_directory() will fill something in */
+        const char *argv[] = {
-        argv[1] = m->lookup_paths.generator;
+                NULL, /* Leave this empty, execute_directory() will fill something in */
-        argv[2] = m->lookup_paths.generator_early;
+                m->lookup_paths.generator,
-        argv[3] = m->lookup_paths.generator_late;
+                m->lookup_paths.generator_early,
-        argv[4] = NULL;
+                m->lookup_paths.generator_late,
+                NULL,
+        };
+
+        r = build_generator_environment(m, &ge);
+        if (r < 0) {
+                log_error_errno(r, "Failed to build generator environment: %m");
+                goto finish;
+        }
 
         RUN_WITH_UMASK(0022)
-                (void) execute_directories((const char* const*) paths, DEFAULT_TIMEOUT_USEC, NULL, NULL,
+                (void) execute_directories(
-                                           (char**) argv, m->transient_environment,
+                                (const char* const*) paths,
+                                DEFAULT_TIMEOUT_USEC,
+                                /* callbacks= */ NULL, /* callback_args= */ NULL,
+                                (char**) argv,
+                                ge,
                                 EXEC_DIR_PARALLEL | EXEC_DIR_IGNORE_ERRORS | EXEC_DIR_SET_SYSTEMD_EXEC_PID);
 
         r = 0;