From f703916c3702d8f32dc535161571874cb007ca6d Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 14 Aug 2018 20:22:43 +0000 Subject: Remove s6-devd, s6-uevent-listener, s6-uevent-spawner, prepare for 2.5.0.0 --- doc/index.html | 5 +- doc/s6-devd.html | 80 ------------------------------ doc/s6-uevent-listener.html | 117 -------------------------------------------- doc/s6-uevent-spawner.html | 87 -------------------------------- doc/upgrade.html | 5 +- 5 files changed, 5 insertions(+), 289 deletions(-) delete mode 100644 doc/s6-devd.html delete mode 100644 doc/s6-uevent-listener.html delete mode 100644 doc/s6-uevent-spawner.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 638b55e..98e43a5 100644 --- a/doc/index.html +++ b/doc/index.html @@ -50,7 +50,7 @@ library.

The current released version of s6-linux-utils is -2.4.0.3.

Alternatively, you can checkout a copy of the s6-linux-utils git repository: @@ -88,9 +88,6 @@ the previous versions of s6-linux-utils and the current one.

The s6-chroot program
The s6-devd program
The s6-uevent-listener program (deprecated)
The s6-uevent-spawner program (deprecated)
The s6-fillurandompool program
The s6-freeramdisk program
The s6-hostname program

s6-linux-utils: the s6-devd program

-s6-linux-utils
-Software
-skarnet.org -

The `s6-devd` program

-s6-devd listens to the netlink interface for udev events, and -launches a helper program for every event, similarly to what the hotplug -interface does. -

Interface

-     s6-devd [ -q | -v ] [ -b kbufsz ] [ -l linevar ] [ -t l:t:k ] prog...
-

s6-devd rewrites its command line into -s6-uevent-listener | -s6-uevent-spawner prog..., -dispatching its options to the appropriate programs; then it execs into -this new command line. It does nothing else: it's just a wrapper.
The first executed program, -s6-uevent-listener, -will listen to the netlink and pass the events sequentially to -s6-uevent-spawner, which will -spawn a prog... helper for every event.

Options

-q : be more quiet.
-v : be more verbose.
-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.
-l linevar : the short description of the -event, given by the kernel as the first string in the netlink message, -will be made available to prog under the environment variable -named linevar.
-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-devd yells and exits 99.

Notes

s6-devd is a daemon; it should be run under a proper supervision system such -as s6. The real long-lived -process is named s6-uevent-listener; -ir runs with the same pid as s6-devd.
The prog... helper, on the other hand, 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 buffers -along the way.

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

-s6-linux-utils
-Software
-skarnet.org -

The `s6-uevent-listener` program

-s6-uevent-listener 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. -

-This program is deprecated, and will disappear in a -near future version of s6-linux-utils. It has been replaced with the -mdevd-netlink -program, from the mdevd -package. -

Interface

-     s6-uevent-listener [ -v verbosity ] [ -b kbufsz ]
-

s6-uevent-listener binds to the netlink interface and listens for -hotplug events, as the udev 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 s6-uevent-listener, it should be piped into a handler -program such as -s6-uevent-spawner. -or mdevd.
s6-uevent-listener is a long-lived program. -When it receives a SIGTERM, it stops listening; it will -exit as soon as it has flushed its event queue to stdout.

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 (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; 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.
Examples of valid uses of s6-uevent-listener: -
- s6-uevent-listener | s6-uevent-spawner mdev
- s6-uevent-listener | mdevd
- Those examples can be made safer by using a supervision system: -under s6 or -s6-rc, write a service -pipeline where s6-uevent-listener is a producer and -s6-uevent-spawner mdev or mdevd is a consumer. This -setup has the advantage, among others, that you can restart the netlink -listener and the event handler separately.
-

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. -

-This program is deprecated, and will disappear in a -future version of s6-linux-utils. The -mdevd package makes it -obsolete. -

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. Since helpers are -spawned sequentially, slow helpers can make events queue up and fill up -buffers.

What has changed in s6-linux-utils

in 2.4.0.3

in 2.5.0.0

skalibs dependency bumped to 2.7.0.0.
Optional nsss support added.
s6-devd, s6-uevent-listener and s6-uevent-spawner +have been removed: mdevd obsoletes +them.

The s6-devd program

Interface

Options

Notes

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.4.0.3

in 2.5.0.0

in 2.4.0.2

The `s6-devd` program

The `s6-uevent-listener` program

The `s6-uevent-spawner` program