'\" t
.\"     Title: networkd-dispatcher
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/24/2023
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NETWORKD\-DISPATCHER" "8" "04/24/2023" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
networkd-dispatcher \- Dispatcher service for systemd\-networkd connection status changes
.SH "SYNOPSIS"
.sp
\fBnetworkd\-dispatcher\fR [\-h] [\-S \fISCRIPT_DIR\fR] [\-T] [\-v] [\-q]
.SH "DESCRIPTION"
.sp
Dispatcher daemon for systemd\-networkd connection status changes\&. This daemon is similar to NetworkManager\-dispatcher, but is much more limited in the types of events it supports due to the limited nature of \fIsystemd\-networkd(8)\fR\&.
.sp
Desired actions (scripts) are placed into directories that reflect systemd\-networkd operational states under \fISCRIPT_DIR\fR and are executed when the daemon receives the relevant event from systemd\-networkd\&.
.sp
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\&.
.SH "OPTIONS"
.PP
\fB\-h, \-\-help\fR
.RS 4
Print command\-line syntax and program options to stdout\&.
.RE
.PP
\fB\-S, \-\-script\-dir=\fR\fB\fISCRIPT_DIR\fR\fR
.RS 4
Location under which to look for scripts\&. Like the
\fIPATH\fR
environment variable, this may contain multiple directories separated by : and in case multiple directories have scripts with the same name, the earliest directory wins\&. Defaults to /etc/networkd\-dispatcher:/usr/lib/networkd\-dispatcher\&.
.RE
.PP
\fB\-T, \-\-run\-startup\-triggers\fR
.RS 4
Generate events reflecting preexisting state and behavior on startup\&. This can be used to ensure that triggers are belatedly run even if networkd\-dispatcher is invoked after systemd\-networkd has already started an interface\&.
.RE
.PP
\fB\-v, \-\-verbose\fR
.RS 4
Increase verbosity by one level\&. The default level is
\fIWARNING\fR\&. Each use of
\fI\-v\fR
will increment the log level (towards
\fIINFO\fR
or
\fIDEBUG\fR), and each use of
\fI\-q\fR
will decrement it (towards
\fIERROR\fR
or
\fICRITICAL\fR)\&.
.RE
.PP
\fB\-q, \-\-quiet\fR
.RS 4
Decrease verbosity by one level\&.
.RE
.SH "CONFIGURATION FILES"
.sp
The systemd service reads \fI/etc/default/networkd\-dispatcher\fR as an environment file for additional daemon arguments\&.
.sp
The scripts to be run on network changes are in subdirectories \fIroutable\&.d/\fR, \fIdormant\&.d/\fR, \fIno\-carrier\&.d/\fR, \fIoff\&.d/\fR, \fIcarrier\&.d/\fR, \fIdegraded\&.d/\fR, \fIconfigured\&.d/\fR, \fIconfiguring\&.d/\fR inside \fISCRIPT_DIR\fR\&. The default value for \fISCRIPT_DIR\fR is \fI/etc/networkd\-dispatcher:/usr/lib/networkd\-dispatcher\fR\&.
.sp
For information about the network operational states exposed by systemd, see networkctl(1)\&.
.SH "ENVIRONMENT"
.sp
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\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBIFACE\fR
\- interface that triggered the event
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBSTATE\fR
\- 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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBESSID\fR
\- for wlan connections, the ESSID the device is connected to
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBADDR\fR
\- the ipv4 address of the device
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBIP_ADDRS\fR
\- space\-delimited string of ipv4 address(es) assigned to the device (see note below)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBIP6_ADDRS\fR
\- space\-delimited string of ipv6 address(es) assigned to the device (see note below)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBAdministrativeState\fR
\- One of
pending,
configuring,
configured,
unmanaged,
failed
or
linger\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBOperationalState\fR
\- 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)\&.
.RE
.SH "RESOURCES"
.sp
GitLab: https://gitlab\&.com/craftyguy/networkd\-dispatcher
.SH "SEE ALSO"
.sp
systemd\-networkd(8), networkctl(1)