s6-linux-utils: the s6-uevent-listener program

From 496b7282f2b8fb56cc88d7113202ef0e1d9ce22c Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 9 Mar 2015 17:21:12 +0000 Subject: - Added s6-uevent-listener and s6-uevent-spawner - s6-devd is now a wrapper around the former two - version: bump to 2.0.2.0, still missing s6-devd doc --- doc/index.html | 6 ++- doc/s6-devd.html | 4 +- doc/s6-uevent-listener.html | 99 +++++++++++++++++++++++++++++++++++++++++++++ doc/s6-uevent-spawner.html | 79 ++++++++++++++++++++++++++++++++++++ doc/upgrade.html | 11 +++++ 5 files changed, 195 insertions(+), 4 deletions(-) create mode 100644 doc/s6-uevent-listener.html create mode 100644 doc/s6-uevent-spawner.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index a899be8..a0fe7d7 100644 --- a/doc/index.html +++ b/doc/index.html @@ -32,7 +32,7 @@

A Linux-based system with a standard C development environment

GNU make, version 4.0 or later

skalibs version -2.3.1.0 or later. It's a build-time requirement. It's also a run-time +2.3.1.2 or later. It's a build-time requirement. It's also a run-time requirement if you link against the shared version of the skalibs library.

@@ -47,7 +47,7 @@ library.

Download

The current released version of s6-linux-utils is 2.0.1.0.
The current released version of s6-linux-utils is 2.0.2.0.
Alternatively, you can checkout a copy of the s6-linux-utils git repository:
```
 git clone git://git.skarnet.org/s6-linux-utils 
```

@@ -79,6 +79,8 @@ the previous versions of s6-linux-utils and the current one.

The s6-chroot program
The s6-devd program
The s6-uevent-listener program
The s6-uevent-spawner program
The s6-freeramdisk program
The s6-halt program
The s6-hostname program

udev

prog...

/proc/sys/kernel/hotplug

However, unlike the kernel, s6-devd spawns the prog... helpers -sequentially: it waits for an instance to finish before spawning another one.�
s6-devd is a long-lived program; it exits 0 when it receives a SIGTERM. If a helper program is alive at that time, s6-devd waits for it to die before exiting.

-t

�If you are using busybox and want a +
If you are using busybox and want a minimal udev-style dynamic /dev handling, /sbin/mdev is a suitable prog... helper.
The point of s6-devd is that it runs the helpers sequentially, so it solves diff --git a/doc/s6-uevent-listener.html b/doc/s6-uevent-listener.html new file mode 100644 index 0000000..9050e9f --- /dev/null +++ b/doc/s6-uevent-listener.html @@ -0,0 +1,99 @@ + + + + + s6-linux-utils: the s6-uevent-listener program + + + + + + +
+s6-linux-utils
+Software
+skarnet.org +
+ +
The s6-uevent-listener program
+ +
+s6-uevent-listener spawns a long-lived helper program. +It then listens to the netlink interface for uevents (also called +"hotplug" or "udev" events), and passes those events to the +helper program's standard input, using a simple format. +
+ +
Interface
+ +
```
+     s6-uevent-listener [ -v verbosity ] [ -b kbufsz ] prog...
+
```
+ +
- s6-uevent-listener spawns prog... with a pipe writing to +prog' stdin.
- s6-uevent-listener binds to the netlink interface and listens for +hotplug events, as the udev program does.
- It tranmits event information to prog via the pipe.
- s6-uevent-listener, as well as prog, are long-lived programs. +When it receives a SIGTERM, s6-uevent-listener stops listening; it will +exit as soon as it has flushed its event queue to prog.
+ +
Options
+ +
- -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.
+ +
Protocol
+ +
- prog should read a series of events on its stdin, and exit +on EOF.
- An event is a series of null-terminated strings as they are sent by +the kernel to the netlink; s6-uevent-listener 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
+ +
- s6-uevent-listener is a daemon; it should be run under a proper supervision system such +as s6.
- If you are running s6-uevent-listener, prog... should be the +only program handling uevents, which means that +/proc/sys/kernel/hotplug should be empty.
- If you want the serialization benefit of the netlink, but still +want to spawn a program such as busybox's +or toybox's mdev, use +s6-uevent-spawner mdev as +s6-uevent-listener's prog.
+ + + diff --git a/doc/s6-uevent-spawner.html b/doc/s6-uevent-spawner.html new file mode 100644 index 0000000..e9be726 --- /dev/null +++ b/doc/s6-uevent-spawner.html @@ -0,0 +1,79 @@ + + + + + s6-linux-utils: the s6-uevent-spawner program + + + + + + +
+s6-linux-utils
+Software
+skarnet.org +
+ +
The s6-uevent-spawner program
+ +
+s6-uevent-spawner listens to its standard input for +netlink-style events, and launches a helper program for every event, +similarly to what the hotplug interface does. +
+ +
+ It is meant to be used together with +s6-uevent-listener. +
+ +
Interface
+ +
```
+     s6-uevent-spawner [ -v verbosity ] [ -l linevar ] [ -t l:t:k ] prog...
+
```
+ +
- s6-uevent-spawner listens to its stdin for a series of strings +representing kernel uevents, as formatted by +s6-uevent-listener.
- For every event it reads, it spawns prog... with +the event variables added to the environment, just as if prog... +had been registered in /proc/sys/kernel/hotplug. However, +it reads the events sequentially, and waits for a prog instance +to finish before spawning another one.
- When s6-uevent-spawner receives EOF: if an instance of +prog is alive, it first waits for it to die. Then it exits +0.
+ +
Options
+ +
- -v verbosity : be more or less verbose. +Default verbosity is 1. 0 only prints fatal error messages. 3 is too much.
- -l linevar : make the event description +(i.e. the first string in the netlink message announcing the event) +available in prog under the environment variable linevar. +By default, this first string is ignored - it is not needed, all the +event information is already in the other variables.
- -t l:t:k : If l, t or k is +specified, they specify timeouts; by default, they are infinite. +If prog... is still alive after l milliseconds, s6-devd sends +it a SIGTERM. Then, if prog... is still alive after t more +milliseconds, s6-devd sends it a SIGKILL. Then, if prog... is still +alive after k more milliseconds, s6-uevent-spawner yells and exits 99.
+ +
Notes
+ +
- The prog... helper should be very short-lived, +even if you are not using the -t option to s6-devd. Since helpers are +spawned sequentially, slow helpers can make events queue up and fill up +buffers.
+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html index b9dcfeb..847324d 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -17,6 +17,17 @@
What has changed in s6-linux-utils
+
in 2.0.2.0
+ +
- skalibs dependency bumped to 2.3.1.1
- New commands: +s6-uevent-listener and +s6-uevent-spawner
- +
- s6-devd is now a wrapper +around those commands.
+
in 2.0.1.0

Download

The `s6-uevent-listener` program

Interface

Options

Protocol

Notes

The `s6-uevent-spawner` program

Interface

Options

Notes

What has changed in s6-linux-utils

in 2.0.2.0

in 2.0.1.0

Download

The s6-uevent-listener program

Interface

Options

Protocol

Notes

The s6-uevent-spawner program

Interface

Options

Notes

What has changed in s6-linux-utils

in 2.0.2.0

in 2.0.1.0

The `s6-uevent-listener` program

The `s6-uevent-spawner` program