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 Jan 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 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.
.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 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 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
.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 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.
.It Pa /run/finit/cond/sys/pwr/
Power supply condition symlinks.
.El
.Sh SEE ALSO
.Xr finit 8 ,
.Xr finit.conf 5 ,
.Xr initctl 8 ,
.Xr mknod 2 ,
.Xr modprobe 8
.Sh AUTHORS
.An Joachim Wiberg Aq Mt troglobit@gmail.com