finit/man/keventd.8

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.Dd Aug 29, 2026
.\" Please adjust this date whenever revising the manpage.
.Dt KEVENTD 8 SMM
.Os Linux
.Sh NAME
.Nm keventd
.Nd Finit device manager daemon
.Sh SYNOPSIS
.Nm
.Op Fl c
.Op Fl d
.Op Fl g Ar group
.Op Fl G
.Op Fl h
.Op Fl n
.Op Fl p
.Op Fl r Ar dir
.Op Fl S
.Op Fl t Ar sec
.Op Fl v
.Sh DESCRIPTION
.Nm
is a built-in device manager bundled with
.Xr finit 8 .
It listens for kernel uevents on a
.Dv NETLINK_KOBJECT_UEVENT
socket and handles device node creation, persistent symlinks, firmware
loading, kernel module loading, and condition management.  Events are
matched against udev rules read from
.Pa /lib/udev/rules.d ,
.Pa /run/udev/rules.d ,
and
.Pa /etc/udev/rules.d ,
and device properties are persisted to
.Pa /run/udev/data
in the format libudev consumers expect.
.Pp
It replaces the need for external device managers like
.Nm mdev ,
.Nm mdevd ,
or
.Nm udevd
on systems where a lighter-weight solution is preferred, particularly
on embedded systems.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl c
Run coldplug at startup.  Walks the
.Pa /sys/devices
tree and writes
.Cm add
to each
.Pa uevent
file, causing the kernel to re-emit add events for all devices already
present.  This populates
.Pa /dev
with nodes for hardware that existed before
.Nm
started.
.It Fl d
Enable debug mode.  Implies
.Fl n .
All received uevents are logged to stderr.
.It Fl h
Show help text and exit.
.It Fl g Ar group
Override the netlink multicast group mask used for uevent rebroadcast.
The default is 4 (group 0x4), which is the
.Sy libudev-zero
convention.
Bit 0 is always masked out to prevent a feedback loop with the kernel
group.
See
.Sx NETLINK REBROADCAST
below.
.It Fl G
Disable netlink uevent rebroadcast entirely.
See
.Sx NETLINK REBROADCAST
below.
.It Fl n
Run in foreground, do not daemonize.  Log messages are written to
stderr instead of syslog.
.It Fl p
Passive mode: monitor power supply events only, leaving device
management to an external device manager.
.It Fl r Ar dir
Extra udev rules directory.  Takes precedence over the standard paths, a
file here masks one of the same name in any of them.  See
.Sx UDEV RULES
below.
.It Fl S
Settle: wait until the device event queue is quiet, then exit 0, or
non-zero on timeout.  Asks the running
.Nm
over D-Bus when available, else polls the kernel's uevent sequence
counter.
.It Fl t Ar sec
Settle timeout in seconds, default 30.  Only with
.Fl S .
.It Fl v
Show version and exit.
.El
.Sh DEVICE NODES
On receiving an
.Cm add
event with
.Cm MAJOR ,
.Cm MINOR ,
and
.Cm DEVNAME
fields,
.Nm
creates the device node in
.Pa /dev
using
.Xr mknod 2 .
Parent directories are created as needed, e.g.\&
.Pa /dev/input/
for
.Pa /dev/input/event0 .
.Pp
On
.Cm remove
events the device node and its associated symlinks are cleaned up.
.Pp
Permissions are assigned based on built-in rules matching on device
subsystem and name.  For example, block devices default to mode 0660
owned by root:disk, TTY devices to root:tty, and common devices like
.Pa /dev/null
and
.Pa /dev/zero
are world-readable (0666).
.Sh UDEV RULES
Rules files need a
.Pa .rules
suffix.  Like
.Xr udev 7 ,
all files sort together by filename, whichever directory they live in,
and a file masks one of the same name in an earlier directory:
.Pa /etc/udev/rules.d
overrides
.Pa /run/udev/rules.d ,
which overrides
.Pa /lib/udev/rules.d ,
and the
.Fl r
directory overrides them all.  A symlink to
.Pa /dev/null
disables the file it shadows.
.Pp
The rules syntax is described in
.Xr udev 7 .
.Nm
implements a subset; the Finit User's Guide details what is supported
and where it differs.
.Sh PERSISTENT SYMLINKS
For block devices,
.Nm
creates symlinks in
.Pa /dev/disk/ :
.Bl -tag -width by-path -offset indent -compact
.It Pa by-id
Based on device serial number and model, read from sysfs.
.It Pa by-path
Based on the device topology path.
.El
.Pp
For input devices, symlinks are created in
.Pa /dev/input/ :
.Bl -tag -width by-path -offset indent -compact
.It Pa by-id
Based on the device name from sysfs.
.It Pa by-path
Based on the physical device path.
.El
.Pp
Symlinks are tracked internally and automatically removed when the
device is unplugged.
.Sh FIRMWARE LOADING
When a kernel driver requests firmware via
.Fn request_firmware ,
the kernel emits a uevent with a
.Cm FIRMWARE
field.
.Nm
handles this by searching for the firmware file in the following order:
.Pp
.Bl -enum -compact -offset indent
.It
.Pa /lib/firmware/updates/<kernel-version>/<name>
.It
.Pa /lib/firmware/updates/<name>
.It
.Pa /lib/firmware/<kernel-version>/<name>
.It
.Pa /lib/firmware/<name>
.El
.Pp
The firmware is loaded by writing to the device's sysfs
.Pa loading
and
.Pa data
attributes.
.Sh MODULE LOADING
When a device add event includes a
.Cm MODALIAS
field,
.Nm
spawns
.Cm modprobe -bq
to load the matching kernel module.  Module loading is asynchronous
to avoid blocking event processing.
.Sh CONDITIONS
.Nm
provides conditions for Finit's dependency system by creating and
removing symlinks in
.Pa /run/finit/cond/ .
.Ss Device Conditions
When a device node is created,
.Nm
asserts a corresponding
.Cm dev/
condition.  For example, creating
.Pa /dev/sda
asserts
.Cm dev/sda .
This allows services to depend on specific devices:
.Bd -literal -offset indent
service mdadm {
    description = "RAID monitor"
    runlevel    = "2345"
    conditions  = { "dev/sda" }
    command     = "/usr/sbin/mdadm"
}

service gpsd {
    description = "GPS daemon"
    runlevel    = "2345"
    conditions  = { "dev/ttyUSB0" }
    command     = "/usr/sbin/gpsd"
}
.Ed
.Pp
When the device is removed, the condition is cleared and Finit stops
the dependent services.
.Ss Power Supply Conditions
.Nm
monitors the
.Cm power_supply
subsystem and provides:
.Bl -tag -width sys/pwr/ac -offset indent -compact
.It Cm sys/pwr/ac
Asserted when AC power is connected.
.El
.Pp
Useful for preventing power-hungry services from running on battery:
.Bd -literal -offset indent
service cron {
    description = "Cron daemon"
    runlevel    = "2345"
    conditions  = { "sys/pwr/ac" }
    command     = "cron -f"
}
.Ed
.Ss Class and Driver Conditions
Devices without a
.Pa /dev
node are covered by
.Cm class/<subsystem>/<name> ,
asserted on every sysfs class device add, e.g.\&
.Cm class/leds/blue
or
.Cm class/net/eth0 .
.Cm driver/<name>
is asserted while the driver
.Ar name
is bound to at least one device, from the kernel's bind/unbind
uevents, e.g.\&
.Cm driver/mt7530 .
.Sh D-BUS INTERFACE
With D-Bus support,
.Nm
serves
.Cm org.finit.Device1
at
.Pa /org/finit/device
on its own brokerless bus,
.Pa unix:path=/run/keventd/bus ,
the same way
.Xr finit 8
serves
.Cm org.finit .
Methods:
.Bl -tag -width RulesReload -offset indent -compact
.It Cm Settle (u) -> b
Wait until the device event queue drains, timeout in seconds
.It Cm Trigger (ss)
Replay events: action and subsystem glob, empty glob matches all
.It Cm Info (s) -> a{ss}
Device properties for a devpath, from /run/udev/data
.It Cm RulesReload () -> u
Re-read the udev rules directories, returns the rule count
.El
.Pp
Properties
.Cm QueueEmpty (b)
and
.Cm SeqnumProcessed (t)
expose the queue state; the
.Cm DeviceProcessed (ss)
signal fires after each fully handled event.
.Sh NETLINK REBROADCAST
The Linux kernel sends uevents to netlink multicast group 1 (bit 0) of
.Dv NETLINK_KOBJECT_UEVENT .
Only the device manager listens on this raw kernel group.  Userspace
consumers such as applications using
.Sy libudev
expect to receive processed events on a separate netlink group.
.Pp
.Sy systemd/udevd
established the convention of rebroadcasting to a separate group, and
.Sy libudev-zero ,
a daemonless replacement for libudev, listens on group 0x4 for these
events.  Without rebroadcast, graphical applications, Wayland and X11
compositors, libinput, and other libudev consumers will not receive
device hotplug events.
.Pp
.Nm
rebroadcasts by default to netlink group 4 (bit 2, i.e.\&
.Li 0x4 ) .
A second netlink socket is created at startup, and after each uevent
has been fully processed (device nodes created, modules loaded,
etc.\&), the original event is sent to the configured group.  This
ensures that device nodes and symlinks already exist by the time
consumers receive the event.
.Pp
Use
.Fl g
to override the default group mask, or
.Fl G
to disable rebroadcast entirely.
.Pp
See also:
.Lk https://github.com/illiliti/libudev-zero "libudev-zero" ,
.Lk https://skarnet.org/software/mdevd/ "mdevd" .
.Sh SIGNALS
.Bl -tag -width SIGUSR1
.It Dv SIGHUP
Re-read the udev rules directories.
.It Dv SIGUSR1
Toggle debug logging at runtime.
.It Dv SIGTERM
Graceful shutdown.
.El
.Sh FILES
.Bl -tag -width /run/finit/cond/dev/ -compact
.It Pa /dev/
Device nodes managed by
.Nm .
.It Pa /dev/disk/by-id/ , Pa /dev/disk/by-path/
Persistent block device symlinks.
.It Pa /dev/input/by-id/ , Pa /dev/input/by-path/
Persistent input device symlinks.
.It Pa /lib/firmware/
Firmware search path.
.It Pa /run/finit/cond/dev/
Device condition symlinks, also
.Pa class/
and
.Pa driver/ .
.It Pa /run/finit/cond/sys/pwr/
Power supply condition symlinks.
.It Pa /lib/udev/rules.d/ , Pa /run/udev/rules.d/ , Pa /etc/udev/rules.d/
udev rules, a later directory overrides an earlier one.
.It Pa /run/udev/data/
Per-device property database, libudev compatible.
.It Pa /run/keventd/bus
The
.Cm org.finit.Device1
D-Bus socket.
.El
.Sh SEE ALSO
.Xr finit 8 ,
.Xr finit.conf 5 ,
.Xr initctl 8 ,
.Xr mknod 2 ,
.Xr modprobe 8 ,
.Xr udev 7
.Sh AUTHORS
.An Joachim Wiberg Aq Mt troglobit@gmail.com