https://github.com/bpetlert/networkd-broker

An event broker daemon for systemd-networkd
https://github.com/bpetlert/networkd-broker

arch arch-linux dbus dispatcher event-broker-daemon linux network networkd-broker networkd-dispatcher rust rust-lang systemd systemd-networkd

Last synced: about 1 month ago
JSON representation

An event broker daemon for systemd-networkd

Host: GitHub
URL: https://github.com/bpetlert/networkd-broker
Owner: bpetlert
License: gpl-3.0
Created: 2019-08-13T19:07:16.000Z (almost 7 years ago)
Default Branch: main
Last Pushed: 2025-12-15T13:43:33.000Z (6 months ago)
Last Synced: 2025-12-15T19:21:18.771Z (6 months ago)
Topics: arch, arch-linux, dbus, dispatcher, event-broker-daemon, linux, network, networkd-broker, networkd-dispatcher, rust, rust-lang, systemd, systemd-networkd
Language: Rust
Homepage:
Size: 492 KB
Stars: 29
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.adoc
- License: COPYING

Awesome Lists containing this project

README

          = 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/.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 &longrightarrow;

~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:bpetlert@gmail.com[Bhanupong Petchlert]

https://gitlab.com/craftyguy/networkd-dispatcher[networkd-dispatcher]: +

Copyright (C) 2018 mailto:clayton@craftyguy.net[Clayton Craft]

https://github.com/wavexx/networkd-notify[networkd-notify]: +

Copyright (C) 2016 mailto:wavexx@thregr.org[Yuri D'Elia]

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/bpetlert/networkd-broker

Awesome Lists containing this project

README