mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-07-05 17:19:00 +00:00
425 lines
19 KiB
XML
425 lines
19 KiB
XML
<?xml version='1.0'?>
|
|
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
<!ENTITY % entities SYSTEM "common.ent" >
|
|
%entities;
|
|
]>
|
|
|
|
<!--
|
|
SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
|
|
|
|
NetworkManager-dispatcher(8) manual page
|
|
|
|
Copyright 2005 - 2016 Red Hat, Inc.
|
|
Copyright 2005 - 2009 Novell, Inc.
|
|
Copyright 2005 Robert Love
|
|
-->
|
|
|
|
<refentry id="NetworkManager-dispatcher">
|
|
<refentryinfo>
|
|
<title>NetworkManager-dispatcher</title>
|
|
<author>NetworkManager developers</author>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>NetworkManager-dispatcher</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
<refmiscinfo class="source">NetworkManager-dispatcher</refmiscinfo>
|
|
<refmiscinfo class="manual">Network management daemons</refmiscinfo>
|
|
<refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>NetworkManager-dispatcher</refname>
|
|
<refpurpose>Dispatch user scripts for NetworkManager</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>NetworkManager <arg choice="opt" rep="repeat">OPTIONS</arg></command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
NetworkManager-dispatcher service is a D-Bus activated service that
|
|
runs user provided scripts upon certain changes in NetworkManager.
|
|
</para>
|
|
<para>
|
|
NetworkManager-dispatcher will execute scripts in the
|
|
<filename>/{etc,usr/lib}/NetworkManager/dispatcher.d</filename>
|
|
directory or subdirectories in
|
|
alphabetical order in response to network events. Each script should
|
|
be a regular executable file owned by root. Furthermore, it must not be
|
|
writable by group or other, and not setuid.
|
|
</para>
|
|
<para>
|
|
Each script receives two arguments, the first being the interface name of the
|
|
device an operation just happened on, and second the action. For device actions,
|
|
the interface is the name of the kernel interface suitable for IP configuration.
|
|
Thus it is either VPN_IP_IFACE, DEVICE_IP_IFACE, or DEVICE_IFACE, as applicable.
|
|
For the <varname>hostname</varname> action the device name is always
|
|
<literal>"none"</literal>. For <varname>connectivity-change</varname> and
|
|
<varname>dns-change</varname> it is empty.
|
|
</para>
|
|
<para>The actions are:</para>
|
|
<variablelist class="dispatcher-options">
|
|
<varlistentry>
|
|
<term><varname>pre-up</varname></term>
|
|
<listitem><para>The interface is connected to the network but is not
|
|
yet fully activated. Scripts acting on this event must be placed or
|
|
symlinked into the <filename>/etc/NetworkManager/dispatcher.d/pre-up.d</filename>
|
|
directory, and NetworkManager will wait for script execution to complete before
|
|
indicating to applications that the interface is fully activated.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>up</varname></term>
|
|
<listitem><para>The interface has been activated.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>pre-down</varname></term>
|
|
<listitem><para>The interface will be deactivated but has not yet been
|
|
disconnected from the network. Scripts acting on this event must be
|
|
placed or symlinked into the <filename>/etc/NetworkManager/dispatcher.d/pre-down.d</filename>
|
|
directory, and NetworkManager will wait for script execution to complete
|
|
before disconnecting the interface from its network. Note that this
|
|
event is not emitted for forced disconnections, like when carrier is
|
|
lost or a wireless signal fades. It is only emitted when there is
|
|
an opportunity to cleanly handle a network disconnection event.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>down</varname></term>
|
|
<listitem><para>
|
|
The interface has been deactivated.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>vpn-pre-up</varname></term>
|
|
<listitem><para>The VPN is connected to the network but is not yet
|
|
fully activated. Scripts acting on this event must be placed or
|
|
symlinked into the <filename>/etc/NetworkManager/dispatcher.d/pre-up.d</filename>
|
|
directory, and NetworkManager will wait for script execution to complete before
|
|
indicating to applications that the VPN is fully activated.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>vpn-up</varname></term>
|
|
<listitem><para>
|
|
A VPN connection has been activated.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>vpn-pre-down</varname></term>
|
|
<listitem><para>The VPN will be deactivated but has not yet been
|
|
disconnected from the network. Scripts acting on this event must be
|
|
placed or symlinked into the <filename>/etc/NetworkManager/dispatcher.d/pre-down.d</filename>
|
|
directory, and NetworkManager will wait for script execution to complete
|
|
before disconnecting the VPN from its network. Note that this
|
|
event is not emitted for forced disconnections, like when the VPN
|
|
terminates unexpectedly or general connectivity is lost. It is only
|
|
emitted when there is an opportunity to cleanly handle a VPN
|
|
disconnection event.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>vpn-down</varname></term>
|
|
<listitem><para>
|
|
A VPN connection has been deactivated.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>hostname</varname></term>
|
|
<listitem><para>
|
|
The system hostname has been updated. Use gethostname(2) to retrieve it.
|
|
The interface name (first argument) is empty and no environment variable is
|
|
set for this action.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>dhcp4-change</varname></term>
|
|
<listitem><para>
|
|
The DHCPv4 lease has changed (renewed, rebound, etc).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>dhcp6-change</varname></term>
|
|
<listitem><para>
|
|
The DHCPv6 lease has changed (renewed, rebound, etc).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>connectivity-change</varname></term>
|
|
<listitem><para>
|
|
The network connectivity state has changed (no connectivity, went online, etc).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>reapply</varname></term>
|
|
<listitem><para>
|
|
The connection was reapplied on the device.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>dns-change</varname></term>
|
|
<listitem><para>
|
|
The DNS configuration has changed. This action is raised even if
|
|
NetworkManager is configured to not manage resolv.conf (for example,
|
|
via dns=none). In such case, the dispatch script can discover the
|
|
DNS configuration provided by currently active connections by
|
|
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.
|
|
The following variables are available for the use in the dispatcher scripts:
|
|
<variablelist class="dispatcher-environment">
|
|
<varlistentry>
|
|
<term><varname>NM_DISPATCHER_ACTION</varname></term>
|
|
<listitem><para>
|
|
The dispatcher action like "up" or "dhcp4-change", identical to the first
|
|
command line argument. Since NetworkManager 1.12.0.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>CONNECTION_UUID</varname></term>
|
|
<listitem><para>
|
|
The UUID of the connection profile.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>CONNECTION_ID</varname></term>
|
|
<listitem><para>
|
|
The name (ID) of the connection profile.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>CONNECTION_DBUS_PATH</varname></term>
|
|
<listitem><para>
|
|
The NetworkManager D-Bus path of the connection.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>CONNECTION_FILENAME</varname></term>
|
|
<listitem><para>
|
|
The backing file name of the connection profile (if any).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>CONNECTION_EXTERNAL</varname></term>
|
|
<listitem><para>
|
|
If "1", this indicates that the connection describes a
|
|
network configuration created outside of NetworkManager.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>DEVICE_IFACE</varname></term>
|
|
<listitem><para>
|
|
The interface name of the control interface of the device.
|
|
Depending on the device type, this differs from
|
|
<varname>DEVICE_IP_IFACE</varname>. For example for
|
|
ADSL devices, this could be 'atm0' or for WWAN devices
|
|
it might be 'ttyUSB0'.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>DEVICE_IP_IFACE</varname></term>
|
|
<listitem><para>
|
|
The IP interface name of the device. This is the network
|
|
interface on which IP addresses and routes will be configured.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_ADDRESS_N</varname></term>
|
|
<listitem><para>
|
|
The IPv4 address in the format "address/prefix gateway", where N is a number
|
|
from 0 to (# IPv4 addresses - 1). gateway item in this variable is deprecated,
|
|
use IP4_GATEWAY instead.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_NUM_ADDRESSES</varname></term>
|
|
<listitem><para>
|
|
The variable contains the number of IPv4 addresses the script may expect.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_GATEWAY</varname></term>
|
|
<listitem><para>
|
|
The gateway IPv4 address in traditional numbers-and-dots notation.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_ROUTE_N</varname></term>
|
|
<listitem><para>
|
|
The IPv4 route in the format "address/prefix next-hop metric", where N is a number
|
|
from 0 to (# IPv4 routes - 1).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_NUM_ROUTES</varname></term>
|
|
<listitem><para>
|
|
The variable contains the number of IPv4 routes the script may expect.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_NAMESERVERS</varname></term>
|
|
<listitem><para>
|
|
The variable contains a space-separated list of the DNS servers.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP4_DOMAINS</varname></term>
|
|
<listitem><para>
|
|
The variable contains a space-separated list of the search domains.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>DHCP4_<dhcp-option-name></varname></term>
|
|
<listitem><para>
|
|
If the connection used DHCP for address configuration, the received DHCP
|
|
configuration is passed in the environment using standard DHCP
|
|
option names, prefixed with "DHCP4_", like "DHCP4_HOST_NAME=foobar".
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>IP6_<name> and DHCP6_<name></varname></term>
|
|
<listitem><para>
|
|
The same variables as for IPv4 are available for IPv6, but the prefixes are IP6_
|
|
and DHCP6_ instead.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>CONNECTIVITY_STATE</varname></term>
|
|
<listitem><para> The network connectivity state, which can
|
|
take the values defined by the NMConnectivityState type,
|
|
from the org.freedesktop.NetworkManager D-Bus API: <literal>UNKNOWN</literal>,
|
|
<literal>NONE</literal>, <literal>PORTAL</literal>, <literal>LIMITED</literal>
|
|
or <literal>FULL</literal>. Note: this variable will only
|
|
be set for connectivity-change actions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
In case of VPN, VPN_IP_IFACE is set, and IP4_*, IP6_* variables with VPN prefix are
|
|
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
|
|
parent return immediately. Scripts that are symbolic links pointing inside the
|
|
<filename>/etc/NetworkManager/dispatcher.d/no-wait.d/</filename>
|
|
directory are run immediately, without
|
|
waiting for the termination of previous scripts, and in parallel. Also beware that
|
|
once a script is queued, it will always be run, even if a later event renders it
|
|
obsolete. (Eg, if an interface goes up, and then back down again quickly, it is
|
|
possible that one or more "up" scripts will be run after the interface has gone down.)
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Bugs</title>
|
|
<para>
|
|
Please report any bugs you find in NetworkManager at the
|
|
<ulink url="https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues">NetworkManager issue tracker</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<ulink url="https://networkmanager.dev">NetworkManager home page</ulink>,
|
|
<link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|