New upstream version 1.46.0 upstream/1.46.0

1 files changed, 84 insertions, 0 deletions

diff --git a/man/NetworkManager-dispatcher.xml b/man/NetworkManager-dispatcher.xml
index f6e1d22d..f85a495a 100644
--- a/man/NetworkManager-dispatcher.xml
+++ b/man/NetworkManager-dispatcher.xml
@@ -172,6 +172,63 @@
             looking at file <filename>/run/NetworkManager/resolv.conf</filename>
         </para></listitem>
       </varlistentry>
+      <varlistentry>
+        <term><varname>device-add</varname></term>
+        <listitem>
+          <para>
+            This action is called when a connection of type <literal>generic</literal>
+            has the <literal>generic.device-handler</literal> property set. The property
+            indicates the name of a dispatcher script to be executed in directory
+            <filename>/{etc,usr/lib}/NetworkManager/dispatcher.d/device</filename>. Note
+            that differently from other actions, only one script is executed.
+          </para>
+          <para>
+            The script needs to perform any action needed to create the device
+            for the generic connection. On successful termination, the script
+            returns zero. Otherwise, it returns a non-zero value to indicate an
+            error. The script can return values to NetworkManager by writing to
+            standard output; each line should contain a key name followed by the
+            equal sign '=' and a key value. The keys understood at the moment
+            are:
+            <variablelist>
+              <varlistentry>
+                <term><varname>IFINDEX</varname></term>
+                <listitem><para> Indicates the interface index of the interface
+                created by the script. This key is required when the script
+                succeeds; if it is not set, the activation will fail. The key is
+                ignored in case of script failure. </para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><varname>ERROR</varname></term>
+                <listitem><para> Specifies an error message indicating the cause
+                of the script failure. It is ignored when the script succeeds.
+                </para></listitem>
+              </varlistentry>
+            </variablelist>
+            Since the dispatcher service captures stdout for parsing those keys,
+            anything written to stdout will not appear in the dispatcher service
+            journal log. Use stderr if you want to print messages to the journal
+            (for example, for debugging). Only the first 8KiB of stdout are
+            considered and among those, only the first 64 lines; the rest is
+            ignored.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><varname>device-delete</varname></term>
+        <listitem>
+          <para>
+            This action is the counterpart of <literal>device-add</literal> and
+            is called to delete the device for a generic connection. All the
+            aspects described for <literal>device-add</literal> also apply to
+            this action, with the only exception that key
+            <varname>IFINDEX</varname> is ignored. It is not necessary to delete
+            the kernel link in the handler because NetworkManager already does
+            that; therefore the action is useful for any additional cleanup
+            needed.
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
     <para>
       The environment contains more information about the interface and the connection.
@@ -309,6 +366,33 @@
       exported too, like VPN_IP4_ADDRESS_0, VPN_IP4_NUM_ADDRESSES.
     </para>
     <para>
+      The content of the <literal>user</literal> setting for the connection
+      being activated is also passed via environment variables. Each key is
+      stored in a variable with name <literal>CONNECTION_USER_</literal>
+      concatenated with the encoding of the key name. The encoding works as
+      follows:
+      <itemizedlist>
+        <listitem>
+          <para>lowercase letters become uppercase</para>
+        </listitem>
+        <listitem>
+          <para>uppercase letters are prefixed with an underscore</para>
+        </listitem>
+        <listitem>
+          <para>numbers do not change</para>
+        </listitem>
+        <listitem>
+          <para>a dot is replaced with a double underscore</para>
+        </listitem>
+        <listitem>
+          <para>any other character is encoded with an underscore followed by
+          its 3-digit octal representation</para>
+        </listitem>
+      </itemizedlist>
+      For example, key <literal>test.foo-Bar2</literal> is stored in a variable named
+      <literal>CONNECTION_USER_TEST__FOO_055_BAR2</literal>.
+    </para>
+    <para>
       Dispatcher scripts are run one at a time, but asynchronously from the main
       NetworkManager process, and will be killed if they run for too long. If your script
       might take arbitrarily long to complete, you should spawn a child process and have the