1.\" 2.\" Copyright (c) 2026 Baptiste Daroussin <bapt@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd April 9, 2026 7.Dt NLSYSEVENT 4 8.Os 9.Sh NAME 10.Nm nlsysevent 11.Nd Netlink-based kernel event notification module 12.Sh SYNOPSIS 13To load the driver as a module at boot time, place the following line in 14.Xr loader.conf 5 : 15.Bd -literal -offset indent 16nlsysevent_load="YES" 17.Ed 18.Pp 19Alternatively, to load the module at runtime: 20.Bd -literal -offset indent 21kldload nlsysevent 22.Ed 23.Sh DESCRIPTION 24The 25.Nm 26kernel module provides a 27.Xr netlink 4 28Generic Netlink interface for receiving kernel device events. 29It hooks into the 30.Xr devctl 4 31notification system and re-publishes all kernel events as Generic Netlink 32multicast messages under the 33.Dv NETLINK_GENERIC 34protocol family. 35.Pp 36This provides an alternative to reading events from 37.Pa /dev/devctl 38.Pq used by Xr devd 8 , 39with the advantage that multiple consumers can subscribe to events 40simultaneously, and consumers can selectively subscribe to specific 41event groups. 42.Ss Generic Netlink Family 43The module registers a Generic Netlink family named 44.Dq Li nlsysevent . 45The dynamically-assigned family identifier can be resolved using the 46standard 47.Dv CTRL_CMD_GETFAMILY 48request as described in 49.Xr genetlink 4 . 50.Ss Commands 51The following command is defined: 52.Bl -tag -width indent 53.It Dv NLSE_CMD_NEWEVENT 54Sent when a kernel event occurs. 55This message is never solicited by userland; it is only delivered to 56sockets that have subscribed to one or more multicast groups. 57.El 58.Ss Attributes 59Each 60.Dv NLSE_CMD_NEWEVENT 61message contains the following TLV attributes: 62.Bl -tag -width indent 63.It Dv NLSE_ATTR_SYSTEM 64(string) The system name that generated the event 65.Pq e.g., Dq Li ACPI , Dq Li IFNET , Dq Li USB . 66.It Dv NLSE_ATTR_SUBSYSTEM 67(string) The subsystem name within the system. 68.It Dv NLSE_ATTR_TYPE 69(string) The type of the event. 70.It Dv NLSE_ATTR_DATA 71(string) Optional extra data associated with the event. 72This attribute may be absent if no extra data was provided. 73.El 74.Ss Multicast Groups 75The module creates one multicast group per system name. 76The following groups are pre-registered when the module is loaded: 77.Pp 78.Bl -column "HYPERV_NIC_VF" -offset indent -compact 79.It Li ACPI 80.It Li AEON 81.It Li CAM 82.It Li CARP 83.It Li coretemp 84.It Li DEVFS 85.It Li device 86.It Li ETHERNET 87.It Li GEOM 88.It Li HYPERV_NIC_VF 89.It Li IFNET 90.It Li INFINIBAND 91.It Li KERNEL 92.It Li nvme 93.It Li PMU 94.It Li RCTL 95.It Li USB 96.It Li VFS 97.It Li VT 98.It Li ZFS 99.El 100.Pp 101Additional groups are created dynamically as new system names appear in 102kernel events, up to a maximum of 64 groups. 103.Pp 104The group identifier for a given system name can be resolved via 105.Dv CTRL_CMD_GETFAMILY 106and then subscribed to using the 107.Dv NETLINK_ADD_MEMBERSHIP 108socket option. 109.Sh EXAMPLES 110The 111.Xr genl 1 112utility can be used to monitor events: 113.Bd -literal -offset indent 114genl monitor nlsysevent 115.Ed 116.Sh SEE ALSO 117.Xr genl 1 , 118.Xr snl 3 , 119.Xr devctl 4 , 120.Xr genetlink 4 , 121.Xr netlink 4 , 122.Xr devd 8 123.Sh HISTORY 124The 125.Nm 126module first appeared in 127.Fx 15.0 . 128.Sh AUTHORS 129The 130.Nm 131kernel module and this manual page were written by 132.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org . 133