NetworkManager-dispatcher: NetworkManager Reference Manual

-

Description

-

- NetworkManager-dispatcher service is a D-Bus activated service that - runs user provided scripts upon certain changes in NetworkManager. -

-

- NetworkManager-dispatcher will execute scripts in the - /{etc,usr/lib}/NetworkManager/dispatcher.d - 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. -

-

- 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 hostname action the device name is always - "none". For connectivity-change and - dns-change it is empty. -

-

The actions are:

-

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pre-up

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 /etc/NetworkManager/dispatcher.d/pre-up.d - directory, and NetworkManager will wait for script execution to complete before - indicating to applications that the interface is fully activated. -

up

The interface has been activated.

pre-down

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 /etc/NetworkManager/dispatcher.d/pre-down.d - 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. -

down

- The interface has been deactivated. -

vpn-pre-up

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 /etc/NetworkManager/dispatcher.d/pre-up.d - directory, and NetworkManager will wait for script execution to complete before - indicating to applications that the VPN is fully activated. -

vpn-up

- A VPN connection has been activated. -

vpn-pre-down

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 /etc/NetworkManager/dispatcher.d/pre-down.d - 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. -

vpn-down

- A VPN connection has been deactivated. -

hostname

- 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. -

dhcp4-change

- The DHCPv4 lease has changed (renewed, rebound, etc). -

dhcp6-change

- The DHCPv6 lease has changed (renewed, rebound, etc). -

connectivity-change

- The network connectivity state has changed (no connectivity, went online, etc). -

reapply

- The connection was reapplied on the device. -

dns-change

- 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 /run/NetworkManager/resolv.conf -

device-add

-

- This action is called when a connection of type generic - has the generic.device-handler property set. The property - indicates the name of a dispatcher script to be executed in directory - /{etc,usr/lib}/NetworkManager/dispatcher.d/device. Note - that differently from other actions, only one script is executed. -

-

- 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: -

-

---- - - - - - - - - - - -

`IFINDEX`	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.
`ERROR`	Specifies an error message indicating the cause - of the script failure. It is ignored when the script succeeds. -

-

- 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. -

-

device-delete

- This action is the counterpart of device-add and - is called to delete the device for a generic connection. All the - aspects described for device-add also apply to - this action, with the only exception that key - IFINDEX 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. -

-

- The environment contains more information about the interface and the connection. - The following variables are available for the use in the dispatcher scripts: -

-

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

`NM_DISPATCHER_ACTION`	- The dispatcher action like "up" or "dhcp4-change", identical to the first - command line argument. Since NetworkManager 1.12.0. -
`CONNECTION_UUID`	- The UUID of the connection profile. -
`CONNECTION_ID`	- The name (ID) of the connection profile. -
`CONNECTION_DBUS_PATH`	- The NetworkManager D-Bus path of the connection. -
`CONNECTION_FILENAME`	- The backing file name of the connection profile (if any). -
`CONNECTION_EXTERNAL`	- If "1", this indicates that the connection describes a - network configuration created outside of NetworkManager. -
`DEVICE_IFACE`	- The interface name of the control interface of the device. - Depending on the device type, this differs from - `DEVICE_IP_IFACE`. For example for - ADSL devices, this could be 'atm0' or for WWAN devices - it might be 'ttyUSB0'. -
`DEVICE_IP_IFACE`	- The IP interface name of the device. This is the network - interface on which IP addresses and routes will be configured. -
`IP4_ADDRESS_N`	- 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. -
`IP4_NUM_ADDRESSES`	- The variable contains the number of IPv4 addresses the script may expect. -
`IP4_GATEWAY`	- The gateway IPv4 address in traditional numbers-and-dots notation. -
`IP4_ROUTE_N`	- The IPv4 route in the format "address/prefix next-hop metric", where N is a number - from 0 to (# IPv4 routes - 1). -
`IP4_NUM_ROUTES`	- The variable contains the number of IPv4 routes the script may expect. -
`IP4_NAMESERVERS`	- The variable contains a space-separated list of the DNS servers. -
`IP4_DOMAINS`	- The variable contains a space-separated list of the search domains. -
`DHCP4_<dhcp-option-name>`	- 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". -
`IP6_<name> and DHCP6_<name>`	- The same variables as for IPv4 are available for IPv6, but the prefixes are IP6_ - and DHCP6_ instead. -
`CONNECTIVITY_STATE`	The network connectivity state, which can - take the values defined by the NMConnectivityState type, - from the org.freedesktop.NetworkManager D-Bus API: `UNKNOWN`, - `NONE`, `PORTAL`, `LIMITED` - or `FULL`. Note: this variable will only - be set for connectivity-change actions. -

-

- 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. -

-

- The content of the user setting for the connection - being activated is also passed via environment variables. Each key is - stored in a variable with name CONNECTION_USER_ - concatenated with the encoding of the key name. The encoding works as - follows: -

-

lowercase letters become uppercase
uppercase letters are prefixed with an underscore
numbers do not change
a dot is replaced with a double underscore
any other character is encoded with an underscore followed by - its 3-digit octal representation

-

- For example, key test.foo-Bar2 is stored in a variable named - CONNECTION_USER_TEST__FOO_055_BAR2. -

-

- 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 - /etc/NetworkManager/dispatcher.d/no-wait.d/ - 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.) -

-

Bugs

-

- Please report any bugs you find in NetworkManager at the - NetworkManager issue tracker. -

-

NetworkManager-dispatcher

Synopsis

Description

Bugs

See Also