= Networkd-broker :toc: :toc-placement!: :xrefstyle: full ifndef::env-github[:icons: font] ifdef::env-github[] :status: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[]

image:https://img.shields.io/github/v/tag/bpetlert/networkd-broker?include_prereleases&label=release&style=flat-square[Release,link=https://github.com/bpetlert/networkd-broker/releases/latest] image:https://img.shields.io/aur/version/networkd-broker?style=flat-square["AUR: networkd-broker",link=https://aur.archlinux.org/packages/networkd-broker/] image:https://img.shields.io/github/license/bpetlert/networkd-broker?style=flat-square["License: GPL-3.0-or-later",link=./COPYING]

The networkd-broker is an event broker daemon for systemd-networkd. It will execute scripts in the /etc/networkd/broker.d/<STATE>.d directory in alphabetical order in response to network events.

toc::[]

This work is based on https://gitlab.com/craftyguy/networkd-dispatcher[networkd-dispatcher], written in Rust, for the purpose of reducing runtime dependencies. This also helps reduce memory footprint (~30MB ⟶ ~8MB) and improve startup time (~30secs ⟶ ~1sec for spinning hard disk drive).

== Installation

=== Arch Linux

It is available on AUR as https://aur.archlinux.org/packages/networkd-broker/[networkd-broker]. To build and install arch package from GIT source:

[source,console] $ git clone https://github.com/bpetlert/networkd-broker.git $ cd networkd-broker $ makepkg -p PKGBUILD.local $ pacman -U networkd-broker-xxxx-1-x86_64.pkg.tar

Then enable/start networkd-broker.service

[source,console] $ systemctl enable --now networkd-broker.service

== Configuration

To change the options of networkd-broker service e.g. enable debug, run systemctl edit networkd-broker.service

./etc/systemd/system/networkd-broker.service.d/override.conf [source,ini]

[Service] Environment='RUST_LOG=networkd_broker=debug'

Or enable --startup-triggers. Start this service after systemd-networkd.service to ensure network devices are already configured or renamed.

./etc/systemd/system/networkd-broker.service.d/override.conf [source,ini]

[Unit] Wants=systemd-networkd.service After=systemd-networkd.service

[Service] ExecStart= ExecStart=/usr/bin/networkd-broker --startup-triggers

== Usage

The scripts for any network event need to be putted (or symlink) in its corresponding directory as shown below. Each script must be a regular executable file owned by root. The default execution timeout of each script is 20 seconds. It can be overridden by --timeout option in service configuration. Any of the scripts which has filename (exclude extension) end with '-nowait' is run immediately, without waitting for the termination of previous scripts. e.g. script-nowait, script-nowait.sh

.Directories of Commonly Used Network Events [source,console]

/etc/networkd └── broker.d ├── carrier.d ├── degraded.d ├── dormant.d ├── no-carrier.d ├── off.d └── routable.d

The scripts are run in alphabetical order, one at a time with two arguments and a set of environment variables being passed. Each script run asynchronously from networkd-broker process.

[[table-script-arguments]] .Script's Arguments |=== | Argument | Description

| STATE | Current link status is one of the following: carrier, degraded, dormant, no-carrier, off, routable; see man networkctl for more details.

| IFACE | Link name that operation just happened on |===

The following environment variables are being passed to each script:

.Script's Environment Variables |=== | Environment Variable | Description

| NWD_DEVICE_IFACE | Link name that operation just happened on, same value as IFACE

| NWD_BROKER_ACTION | Current link status, same value as STATE

| NWD_JSON | All the link details are encoded in JSON format. |===

[TIP] .Add Uncommonly Used Network Events

There are link's STATE which are not list in <>. To find out which link state that can be added, using the following command: [source,console]

$ journalctl -u networkd-broker.service | grep "Respond to" | grep -v -E "(carrier)|(degraded)|(dormant)|(no-carrier)|(off)|(routable)"

... INFO networkd_broker::broker: Respond to 'enslaved' event of 'vethbece646'

The result shows that event enslaved can be used for device vethbece646. To use this event, crate directory /etc/networkd/broker.d/enslaved.d and put scripts in it.

=== Example Usage

The script below activate/deactivate https://wiki.archlinux.org/index.php/Chrony[Chrony] correspond to link state of wlp3s0 link. This is useful if your computer is not connected to the internet on startup and use offline option for NTP sources. The script must be put (or symlink) in /etc/networkd/broker.d/routable.d, and /etc/networkd/broker.d/no-carrier.d.

.chrony-switch [source,bash]

#!/usr/bin/env bash

STATE=$1 IFACE=$2 DEV=wlp3s0

if [[ "$IFACE" != "$DEV" ]]; then exit 2 fi

if [[ "$STATE" = "routable" ]]; then chronyc online > /dev/null chronyc burst 4/4 > /dev/null sleep 10 chronyc makestep > /dev/null echo "Activate chrony" exit 0 elif [[ "$STATE" = "no-carrier" ]]; then chronyc offline > /dev/null echo "Deactivate chrony" exit 0 fi

exit 0

./etc/networkd [source,console]

/etc/networkd └── broker.d ├── carrier.d ├── degraded.d ├── dormant.d ├── no-carrier.d │  └── 10-chrony-switch -> /usr/local/bin/chrony-switch ├── off.d └── routable.d └── 10-chrony-switch-nowait -> /usr/local/bin/chrony-switch

./etc/systemd/system/networkd-broker.service.d/override.conf [source,ini]

[Unit] Wants=systemd-networkd.service chronyd.service After=systemd-networkd.service chronyd.service

[Service] ExecStart= ExecStart=/usr/bin/networkd-broker --startup-triggers

== Design

[link=https://raw.githubusercontent.com/bpetlert/networkd-broker/main/docs/assets/networkd-broker.svg?sanitize=true&raw=true] image::https://raw.githubusercontent.com/bpetlert/networkd-broker/main/docs/assets/networkd-broker.svg?sanitize=true&raw=true[Sequence Diagram]

== License

link:./COPYING[GNU General Public License v3.0 or later]

https://github.com/bpetlert/networkd-broker[networkd-broker]: + Copyright (C) 2019 mailto:[email protected][Bhanupong Petchlert]

https://gitlab.com/craftyguy/networkd-dispatcher[networkd-dispatcher]: + Copyright (C) 2018 mailto:[email protected][Clayton Craft]

https://github.com/wavexx/networkd-notify[networkd-notify]: + Copyright (C) 2016 mailto:[email protected][Yuri D'Elia]