core: split $MONITOR_METADATA and return it only if a single unit triggers OnFailure/OnSuccess

Remove the list logic, and simply skip passing metadata if more than one
unit triggered an OnFailure/OnSuccess handler.
Instead of a single env var to loop over, provide each separate item
as its own variable.

Fixes https://github.com/systemd/systemd/issues/22370

1 files changed, 36 insertions, 48 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 3b57f8d2f1..defca12d1b 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -3404,7 +3404,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
         <varlistentry>
           <term><varname>$SERVICE_RESULT</varname></term>
 
-          <listitem><para>Only defined for the service unit type, this environment variable is passed to all
+          <listitem><para>Only used for the service unit type. This environment variable is passed to all
           <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service
           "result". Currently, the following values are defined:</para>
 
@@ -3472,7 +3472,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
           <term><varname>$EXIT_CODE</varname></term>
           <term><varname>$EXIT_STATUS</varname></term>
 
-          <listitem><para>Only defined for the service unit type, these environment variables are passed to all
+          <listitem><para>Only defined for the service unit type. These environment variables are passed to all
           <varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code
           information of the main process of the service. For the precise definition of the exit code and status, see
           <citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname>
@@ -3585,38 +3585,28 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
         </varlistentry>
 
         <varlistentry>
-          <term><varname>$MONITOR_METADATA</varname></term>
-
-          <listitem><para>Only defined for the service unit type, this environment variable is passed to all
-          <varname>ExecStart=</varname> and <varname>ExecStartPre=</varname> processes which run in services
-          triggered by <varname>OnFailure=</varname> or <varname>OnSuccess=</varname> dependencies.</para>
-
-          <para>
-          The contents of this variable consists of a semi-colon separated list of metadata fields associated with the triggering
-          service. For each service which triggered the <varname>OnFailure=</varname> or <varname>OnSuccess=</varname>
-          dependency the following fields will be set:
+          <term><varname>$MONITOR_SERVICE_RESULT</varname></term>
+          <term><varname>$MONITOR_EXIT_CODE</varname></term>
+          <term><varname>$MONITOR_EXIT_STATUS</varname></term>
+          <term><varname>$MONITOR_INVOCATION_ID</varname></term>
+          <term><varname>$MONITOR_UNIT</varname></term>
+
+          <listitem><para>Only defined for the service unit type. Those environment variable are passed to
+          all <varname>ExecStart=</varname> and <varname>ExecStartPre=</varname> processes which run in
+          services triggered by <varname>OnFailure=</varname> or <varname>OnSuccess=</varname> dependencies.
           </para>
 
-          <itemizedlist>
-            <listitem><para><constant>SERVICE_RESULT</constant></para></listitem>
-            <listitem><para><constant>EXIT_CODE</constant></para></listitem>
-            <listitem><para><constant>EXIT_STATUS</constant></para></listitem>
-            <listitem><para><constant>INVOCATION_ID</constant></para></listitem>
-            <listitem><para><constant>UNIT</constant></para></listitem>
-          </itemizedlist>
-
-          <para>The fields <constant>SERVICE_RESULT</constant>, <constant>EXIT_CODE</constant> and
-          <constant>EXIT_STATUS</constant> may take the same values that are allowed when set for
-          <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes. The fields
-          <constant>INVOCATION_ID</constant> and <constant>UNIT</constant> are the invocaton id and unit
-          name of the service which triggered the dependency. Each field is comma separated, i.e.</para>
-
-          <programlisting>
-SERVICE_RESULT=result-string,EXIT_CODE=exit-code,EXIT_STATUS=exit-status,INVOCATION_ID=invocation-id,UNIT=triggering.service
-          </programlisting>
-
-          </listitem>
-
+          <para>Variables <varname>$MONITOR_SERVICE_RESULT</varname>, <varname>$MONITOR_EXIT_CODE</varname>
+          and <varname>$MONITOR_EXIT_STATUS</varname> take the same values as for
+          <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes. Variables
+          <varname>$MONITOR_INVOCATION_ID</varname> and <varname>$MONITOR_UNIT</varname> are set to the
+          invocaton id and unit name of the service which triggered the dependency.</para>
+
+          <para>Note that when multiple services trigger the same unit, those variables will be
+          <emphasis>not</emphasis> be passed. Consider using a template handler unit for that case instead:
+          <literal>OnFailure=<replaceable>handler</replaceable>@%n.service</literal> for non-templated units,
+          or <literal>OnFailure=<replaceable>handler</replaceable>@%p-%i.service</literal> for templated
+          units.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -4060,7 +4050,7 @@ SERVICE_RESULT=result-string,EXIT_CODE=exit-code,EXIT_STATUS=exit-status,INVOCAT
     <title>Examples</title>
 
       <example>
-        <title><varname>$MONITOR_METADATA</varname> usage</title>
+        <title><varname>$MONITOR_<replaceable>*</replaceable></varname> usage</title>
 
         <para>A service <filename index="false">myfailer.service</filename> which can trigger an
         <varname>OnFailure=</varname> dependency.</para>
@@ -4094,33 +4084,31 @@ ExecStart=/bin/mysecondprogram
 Description=Acts on service failing or succeeding
 
 [Service]
-ExecStart=/bin/bash -c "echo $MONITOR_METADATA"
+ExecStart=/bin/bash -c "echo $MONITOR_SERVICE_RESULT $MONITOR_EXIT_CODE $MONITOR_EXIT_STATUS $MONITOR_INVOCATION_ID $MONITOR_UNIT"
         </programlisting>
 
         <para>If <filename index="false">myfailer.service</filename> were to run and exit in failure,
         then <filename index="false">myhandler.service</filename> would be triggered and the
-        <varname>$MONITOR_METADATA</varname> variable would be set as follows:</para>
+        monitor variables would be set as follows:</para>
 
         <programlisting>
-MONITOR_METADATA=SERVICE_RESULT=result-string,EXIT_CODE=exit-code,EXIT_STATUS=exit-status,INVOCATION_ID=invocation-id,UNIT=myfailer.service
+MONITOR_SERVICE_RESULT=exit-code
+MONITOR_EXIT_CODE=exited
+MONITOR_EXIT_STATUS=1
+MONITOR_INVOCATION_ID=cc8fdc149b2b4ca698d4f259f4054236
+MONITOR_UNIT=myfailer.service
         </programlisting>
 
         <para>If <filename index="false">mysuccess.service</filename> were to run and exit in success,
         then <filename index="false">myhandler.service</filename> would be triggered and the
-        <varname>$MONITOR_METADATA</varname> variable would be set as follows:</para>
-
-        <programlisting>
-MONITOR_METADATA=SERVICE_RESULT=result-string,EXIT_CODE=exit-code,EXIT_STATUS=exit-status,INVOCATION_ID=invocation-id,UNIT=mysuccess.service
-        </programlisting>
-
-        <para>If <filename index="false">myfailer.service</filename> and <filename index="false">mysuccess.service</filename> were to run and exit,
-        there is a chance that the triggered dependency start job might be merged. Thus only a single invocation of
-        <filename index="false">myhandler.service</filename> would be triggered. In this case the <varname>$MONITOR_METADATA</varname> variable
-        would be a list containing exit metadata for both of <filename index="false">myfailer.service</filename>
-        and <filename index="false">mysuccess.service</filename>.</para>
+        monitor variables would be set as follows:</para>
 
         <programlisting>
-MONITOR_METADATA=SERVICE_RESULT=result-string,EXIT_CODE=exit-code,EXIT_STATUS=exit-status,INVOCATION_ID=invocation-id,UNIT=myfailer.service;SERVICE_RESULT=result-string,EXIT_CODE=exit-code,EXIT_STATUS=exit-status,INVOCATION_ID=invocation-id,UNIT=mysuccess.service
+MONITOR_SERVICE_RESULT=success
+MONITOR_EXIT_CODE=exited
+MONITOR_EXIT_STATUS=0
+MONITOR_INVOCATION_ID=6ab9af147b8c4a3ebe36e7a5f8611697
+MONITOR_UNIT=mysuccess.service
         </programlisting>
 
     </example>