From 32759d402e7327865ea18a203bd1c09f98735bd1 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 22 Oct 2017 17:09:25 +0000 Subject: Initial commit --- doc/mdevd-netlink.html | 123 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 doc/mdevd-netlink.html (limited to 'doc/mdevd-netlink.html') diff --git a/doc/mdevd-netlink.html b/doc/mdevd-netlink.html new file mode 100644 index 0000000..9747f13 --- /dev/null +++ b/doc/mdevd-netlink.html @@ -0,0 +1,123 @@ + + + + + + mdevd: the mdevd-netlink program + + + + + + +

+mdevd
+Software
+skarnet.org +

+ +

The `mdevd-netlink` program

+ +

+mdevd-netlink listens to the netlink interface for uevents +(also called "hotplug" or "udev" events), and writes those uevents to +its standard output, using a simple format. +

+ +

+mdevd expects uevents in the same +format mdevd-netlink writes them. So the +mdevd-netlink | mdevd command line will function as +a daemon reading uevents from the netlink and handling them. +

+ +

Interface

+ +

+     mdevd-netlink [ -d notif ] [ -v verbosity ] [ -b kbufsz ]
+

+ +

mdevd-netlink binds to the netlink interface and listens for +hotplug events, as the udevd program does.
It writes event information to its stdout. The output contains +null characters, so a terminal will not display them correctly. To +properly use mdevd-netlink, it should be piped into a handler +program such as mdevd.
mdevd-netlink is a long-lived program. +When it receives a SIGTERM, it stops listening to hotplug events; +it will exit as soon as it has flushed its event queue to stdout.

+ +

Options

+ +

-d notif : when ready (actually +listening to the netlink), write a newline to file descriptor notif +then close it. This allows mdevd-netlink to use the +s6 mechanism to +notify readiness. notif cannot be lesser than 3. If this +option is not given, no readiness notification is sent.
-v verbosity : be more or less verbose. +Default verbosity is 1. 0 will only print fatal error messages, 3 will +print warnings every time the netlink interface sends something +unexpected.
-b kbufsz : try and reserve a kernel buffer of +kbufsz bytes for the netlink queue. Too large a buffer wastes kernel memory; +too small a buffer risks losing events. The default is 65536 (which is on +the large side).

+ +

Protocol

+ +

An event is a series of null-terminated strings as they are sent by +the kernel to the netlink; mdevd-netlink adds a final empty string +(i.e. an additional null character) to mark the end of the series.
The first string is a short description of the event; it normally +contains the string "@/". Other strings after the first are of the form +"VARIABLE=value", and describe the environment which a hotplug helper +for the event (registered in /proc/sys/kernel/hotplug) would be +spawned with.

Example (newlines added for clarity):

+add@/class/input/input9/mouse2\0
+ACTION=add\0
+DEVPATH=/class/input/input9/mouse2\0
+SUBSYSTEM=input\0
+SEQNUM=106\0
+PHYSDEVPATH=/devices/pci0000:00/0000:00:1d.1/usb2/22/22:1.0
+PHYSDEVBUS=usb\0
+PHYSDEVDRIVER=usbhid\0
+MAJOR=13\0
+MINOR=34\0
+\0

+ +

Notes

+ +

mdevd-netlink is a daemon; it should be run under a proper supervision system such +as s6.
If you are running mdevd-netlink, the program you pipe its +output into should be the only program handling uevents; that means +that /proc/sys/kernel/hotplug should be empty.
The mdevd-netlink | mdevd command line is a quick +way of running a uevent manager, but there are ways to improve it: +
- Using the +execline scripting +language, the pipeline { mdevd-netlink } mdevd command +line will avoid leaving a shell around.
- The best way to use mdevd-netlink and mdevd is with a +supervision system: +under s6 or +s6-rc, write a service +pipeline where mdevd-netlink is a producer and +mdevd is a consumer. This setup has the advantage, among +others, that you can restart the netlink listener and the event handler +separately.

+ + + -- cgit v1.2.3

The mdevd-netlink program

Interface

Options

Protocol

Notes

The `mdevd-netlink` program