README.md 5.69 KB
Newer Older
clayton craft's avatar
clayton craft committed
1 2
# networkd-dispatcher

clayton craft's avatar
clayton craft committed
3 4 5 6
Networkd-dispatcher is a dispatcher daemon for systemd-networkd connection status changes. This daemon is similar to [NetworkManager-dispatcher](https://developer.gnome.org/NetworkManager/unstable/NetworkManager.html), but is much more limited in the types of events it supports due to the limited nature of systemd-networkd. 

Desired actions (scripts) are placed into directories that reflect [systemd-networkd operational states](https://www.freedesktop.org/software/systemd/man/networkctl.html), and are executed when the daemon receives the relevant event from systemd-networkd.

7
The daemon listens for signals from systemd-networkd over dbus, so it should be very light on resources (e.g. no polling). It is meant to be run as a system-wide daemon (as root). This allows it to be used for tasks such as starting a VPN after a connection is established.
clayton craft's avatar
clayton craft committed
8 9 10

## Usage

11
The daemon expects that scripts are 1) executable and 2) owned by root (gid = uid = 0), and will not execute scripts that are otherwise.
clayton craft's avatar
clayton craft committed
12

13
Scripts can be installed into these directories under `/usr/lib/networkd-dispatcher` for system packages, and `/etc/networkd-dispatcher` for local overrides:
clayton craft's avatar
clayton craft committed
14 15 16 17 18 19 20 21 22

```
routable.d/

dormant.d/

no-carrier.d/

off.d/
23 24 25 26

carrier.d/

degraded.d/
27 28 29 30

configuring.d/

configured.d/
clayton craft's avatar
clayton craft committed
31 32 33 34
```

networkd-dispatcher will execute any valid scripts in the directory that reflects the new state. 

35
Scripts are executed in the alpha-numeric order in which they are named, starting with 0 and ending with z. For example, a script named `50runme` would run before `99runmenext`.
clayton craft's avatar
clayton craft committed
36

37
Scripts are executed with some environment variables set. Some of these variables may not be set or may be set to an empty value, dependent upon the type of event. These can be used by scripts to conditionally take action based on a specific interface, state, etc.
clayton craft's avatar
clayton craft committed
38

39
- `IFACE` - interface that triggered the event
clayton craft's avatar
clayton craft committed
40

41
- `STATE` - The destination state change for which a script is currently being invoked. May be any of the values listed as valid for `AdministrativeState` or `OperationalState`.
clayton craft's avatar
clayton craft committed
42

43
- `ESSID` - for wlan connections, the ESSID the device is connected to
clayton craft's avatar
clayton craft committed
44

45
- `ADDR` - the ipv4 address of the device
46

47
- `IP_ADDRS` - space-delimited string of ipv4 address(es) assigned to the device (see note below)
48

49
- `IP6_ADDRS` - space-delimited string of ipv6 address(es) assigned to the device (see note below)
50

51
- `AdministrativeState` - One of `pending`, `configuring`, `configured`, `unmanaged`, `failed` or `linger`.
52

53
- `OperationalState` - One of `off`, `no-carrier`, `dormant`, `carrier`, `degraded`, `routable`, `configuring`, or `configured`. For more information about the network operational states exposed by systemd, see the `networkctl` manpage (`man networkctl`).
54

55
- `json` - A JSON encoding of this program's interpretation of `networkctl status "$IFACE"`, when the event is one for which such information is available; for debug logs or inspection with JSON-aware tools such as `jq`. Exact structure details are implementation-defined and liable to change.
56

57
*Note: For `IP_ADDRS` and `IP6_ADDRS`, the space-delimited string can be read into a BASH array like this:
clayton craft's avatar
clayton craft committed
58

59
`read -r -a ip_addrs <<<"$IP_ADDRS"`
clayton craft's avatar
clayton craft committed
60

61 62 63 64 65 66 67 68 69 70 71
### Command-Line Options

```
usage: networkd-dispatcher [-h] [-S SCRIPT_DIR] [-T] [-v] [-q]

networkd dispatcher daemon

optional arguments:
  -h, --help            show this help message and exit
  -S SCRIPT_DIR, --script-dir SCRIPT_DIR
                        Location under which to look for scripts [default:
72
                        /etc/networkd-dispatcher:/usr/lib/networkd-dispatcher]
73 74 75 76 77 78 79 80 81 82 83 84
  -T, --run-startup-triggers
                        Generate events reflecting preexisting state and
                        behavior on startup [default: False]
  -v, --verbose         Increment verbosity level once per call
  -q, --quiet           Decrement verbosity level once per call
```

Some further notes:

- The intended use case of `--run-startup-triggers` is race-condition avoidance: Ensuring that triggers are belatedly run even if networkd-dispatcher is invoked after systemd-networkd has already started an interface.
- The default log level is `WARNING`. Each use of `-v` will increment the log level (towards `INFO` or `DEBUG`), and each use of `-q` will decrement it (towards `ERROR` or `CRITICAL`).

85 86 87 88 89
### Systemd Service

There is an included systemd service file, `networkd-dispatcher.service`, which can be used to run networkd-dispatcher as a service. To specify command line options for the service, add them to a variable `networkd_dispatcher_args` in `/etc/conf.d/networkd-dispatcher.conf`. A template conf file is included.


clayton craft's avatar
clayton craft committed
90 91 92 93
## Installation

### Arch Linux

clayton craft's avatar
clayton craft committed
94
This package can be [installed from AUR](https://aur.archlinux.org/packages/networkd-dispatcher/).
clayton craft's avatar
clayton craft committed
95 96 97

### Other Linux Folks

clayton craft's avatar
clayton craft committed
98 99
Requirements:

clayton craft's avatar
clayton craft committed
100
- \>= python 3.4
clayton craft's avatar
clayton craft committed
101 102 103 104 105

- python-gobject

- python-dbus

clayton craft's avatar
clayton craft committed
106 107 108
- Handling of wireless interfaces requires one of the following tools to be installed:
  - wireless_tools (providing iwconfig)
  - iw
clayton craft's avatar
clayton craft committed
109

clayton craft's avatar
clayton craft committed
110 111 112 113
Copy networkd-dispatcher to /usr/bin.

Create the appropriate directory structure:

114
`$ sudo mkdir -p /etc/networkd-dispatcher/{routable,dormant,no-carrier,off,carrier,degraded,configuring,configured}.d`
clayton craft's avatar
clayton craft committed
115

116 117
Install networkd-dispatcher.conf to /etc/conf.d.

clayton craft's avatar
clayton craft committed
118
Install networkd-dispatcher.service and start it. If networkd-dispatcher was not copied to /usr/bin, then edit service file to reflect the appropriate path.
clayton craft's avatar
clayton craft committed
119 120


121 122
## Contributors

123
- [craftyguy](https://github.com/craftyguy) (Clayton Craft)
124

125
- [charles-dyfis-net](https://github.com/charles-dyfis-net) (Charles Duffy)
126

127
- [ryu0](https://github.com/ryu0) (James Buren)
clayton craft's avatar
clayton craft committed
128

129 130
- [raharper](https://github.com/raharper) (Ryan Harper)

clayton craft's avatar
clayton craft committed
131
A large portion of the code was leveraged from [networkd-notify](https://github.com/wavexx/networkd-notify), which was written by wavexx (Yuri D'Elia)