From 9c0c0ac966cb4dddaeba72580edc20c777280858 Mon Sep 17 00:00:00 2001 From: Thomas Haller Date: Tue, 16 Mar 2021 14:30:58 +0100 Subject: [PATCH] man: split NetworkManager-dispatcher(8) manual page out of NetworkManager(8) https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/784 --- Makefile.am | 4 +- configure.ac | 1 + contrib/fedora/rpm/NetworkManager.spec | 1 + docs/api/Makefile.am | 1 + docs/api/network-manager-docs.xml | 1 + man/NetworkManager-dispatcher.xml | 331 +++++++++++++++++++++++++ man/NetworkManager.xml | 258 +------------------ man/meson.build | 1 + 8 files changed, 343 insertions(+), 255 deletions(-) create mode 100644 man/NetworkManager-dispatcher.xml diff --git a/Makefile.am b/Makefile.am index c38f215ac2..50cdc3c8d7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -5327,12 +5327,14 @@ endif man_pages += \ man/NetworkManager.8 \ + man/NetworkManager-dispatcher.8 \ man/NetworkManager.conf.5 \ man/nm-online.1 \ man/nm-initrd-generator.8 \ man/nmcli-examples.7 \ man/nmcli.1 \ - man/nmtui.1 + man/nmtui.1 \ + $(NULL) man_pages_autogen += \ man/nm-settings-dbus.5 \ diff --git a/configure.ac b/configure.ac index 0489ff8072..9f74007796 100644 --- a/configure.ac +++ b/configure.ac @@ -1276,6 +1276,7 @@ AM_CONDITIONAL(WITH_PYTHON_BLACK, test "${BLACK}" != "") use_pregen_docs=no if test "$build_docs" != "yes" -a \ -f "$srcdir"/man/NetworkManager.8 -a \ + -f "$srcdir"/man/NetworkManager-dispatcher.8 -a \ -f "$srcdir"/man/NetworkManager.conf.5 -a \ -f "$srcdir"/man/nm-online.1 -a \ -f "$srcdir"/man/nmcli-examples.7 -a \ diff --git a/contrib/fedora/rpm/NetworkManager.spec b/contrib/fedora/rpm/NetworkManager.spec index 0ba5fe37a0..174535cc4d 100644 --- a/contrib/fedora/rpm/NetworkManager.spec +++ b/contrib/fedora/rpm/NetworkManager.spec @@ -1005,6 +1005,7 @@ fi %{_mandir}/man7/nmcli-examples.7* %{_mandir}/man8/nm-initrd-generator.8.gz %{_mandir}/man8/NetworkManager.8.gz +%{_mandir}/man8/NetworkManager-dispatcher.8.gz %dir %{_localstatedir}/lib/NetworkManager %dir %{_sysconfdir}/sysconfig/network-scripts %{_datadir}/dbus-1/system-services/org.freedesktop.nm_dispatcher.service diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index a5b71ad3fe..fd98aa2415 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -86,6 +86,7 @@ content_files = \ $(top_builddir)/man/nm-online.xml \ $(top_builddir)/man/nm-initrd-generator.xml \ $(top_builddir)/man/NetworkManager.xml \ + $(top_builddir)/man/NetworkManager-dispatcher.xml \ $(top_builddir)/man/NetworkManager.conf.xml \ $(top_builddir)/man/nmcli-examples.xml \ $(top_builddir)/man/nm-settings-dbus.xml \ diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index f921b08604..a2fc76d7ff 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -70,6 +70,7 @@ Manual Pages + diff --git a/man/NetworkManager-dispatcher.xml b/man/NetworkManager-dispatcher.xml new file mode 100644 index 0000000000..2d9a270569 --- /dev/null +++ b/man/NetworkManager-dispatcher.xml @@ -0,0 +1,331 @@ + + + +%entities; +]> + + + + + + NetworkManager-dispatcher + NetworkManager developers + + + NetworkManager-dispatcher + 8 + NetworkManager-dispatcher + Network management daemons + &NM_VERSION; + + + + NetworkManager-dispatcher + Dispatch user scripts for NetworkManager + + + + + NetworkManager OPTIONS + + + + + 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" + and for connectivity-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). + + + + + 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. + + + 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. + + + + + See Also + + NetworkManager home page, + NetworkManager8, + + + diff --git a/man/NetworkManager.xml b/man/NetworkManager.xml index e2ac82547c..8977ae4eed 100644 --- a/man/NetworkManager.xml +++ b/man/NetworkManager.xml @@ -68,260 +68,9 @@ Dispatcher scripts - NetworkManager will execute scripts in the - /etc/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" - and for connectivity-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). - - - - - 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. - - - 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.) + NetworkManager-dispatcher service can execute scripts for the user + in response to network events. See + NetworkManager-dispatcher8 manual. @@ -582,6 +331,7 @@ NetworkManager home page, NetworkManager.conf5, + NetworkManager-dispatcher8, nmcli1, nmcli-examples7, nm-online1, diff --git a/man/meson.build b/man/meson.build index a2e3bcdbe7..fea0b9dbdc 100644 --- a/man/meson.build +++ b/man/meson.build @@ -26,6 +26,7 @@ mans_xmls = [] mans = [ ['NetworkManager', '8'], + ['NetworkManager-dispatcher', '8'], ['NetworkManager.conf', '5'], ['nm-online', '1'], ['nmcli-examples', '7'],