From 90b12bd71bb9fc79a4640b9112c13ef529d0196a Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 5 Dec 2014 22:26:11 +0000 Subject: Initial commit --- doc/fifodir.html | 123 +++++++++ doc/index.html | 291 ++++++++++++++++++++++ doc/libftrig.html | 184 ++++++++++++++ doc/libftrigr.html | 283 +++++++++++++++++++++ doc/libftrigw.html | 115 +++++++++ doc/libs6lock/index.html | 256 +++++++++++++++++++ doc/libs6lock/s6lockd-helper.html | 52 ++++ doc/libs6lock/s6lockd.html | 73 ++++++ doc/notifywhenup.html | 75 ++++++ doc/s6-cleanfifodir.html | 42 ++++ doc/s6-envdir.html | 66 +++++ doc/s6-envuidgid.html | 64 +++++ doc/s6-fghack.html | 50 ++++ doc/s6-ftrig-listen.html | 73 ++++++ doc/s6-ftrig-listen1.html | 88 +++++++ doc/s6-ftrig-notify.html | 44 ++++ doc/s6-ftrig-wait.html | 51 ++++ doc/s6-ftrigrd.html | 73 ++++++ doc/s6-log.html | 508 ++++++++++++++++++++++++++++++++++++++ doc/s6-mkfifodir.html | 46 ++++ doc/s6-notifywhenup.html | 80 ++++++ doc/s6-setlock.html | 65 +++++ doc/s6-setsid.html | 47 ++++ doc/s6-setuidgid.html | 49 ++++ doc/s6-softlimit.html | 54 ++++ doc/s6-supervise.html | 125 ++++++++++ doc/s6-svc.html | 104 ++++++++ doc/s6-svok.html | 38 +++ doc/s6-svscan-1.html | 374 ++++++++++++++++++++++++++++ doc/s6-svscan-not-1.html | 140 +++++++++++ doc/s6-svscan.html | 176 +++++++++++++ doc/s6-svscanctl.html | 108 ++++++++ doc/s6-svstat.html | 45 ++++ doc/s6-svwait.html | 73 ++++++ doc/s6-tai64n.html | 50 ++++ doc/s6-tai64nlocal.html | 73 ++++++ doc/scandir.html | 145 +++++++++++ doc/servicedir.html | 187 ++++++++++++++ doc/systemd.html | 120 +++++++++ doc/ucspilogd.html | 94 +++++++ doc/upgrade.html | 32 +++ doc/why.html | 203 +++++++++++++++ 42 files changed, 4939 insertions(+) create mode 100644 doc/fifodir.html create mode 100644 doc/index.html create mode 100644 doc/libftrig.html create mode 100644 doc/libftrigr.html create mode 100644 doc/libftrigw.html create mode 100644 doc/libs6lock/index.html create mode 100644 doc/libs6lock/s6lockd-helper.html create mode 100644 doc/libs6lock/s6lockd.html create mode 100644 doc/notifywhenup.html create mode 100644 doc/s6-cleanfifodir.html create mode 100644 doc/s6-envdir.html create mode 100644 doc/s6-envuidgid.html create mode 100644 doc/s6-fghack.html create mode 100644 doc/s6-ftrig-listen.html create mode 100644 doc/s6-ftrig-listen1.html create mode 100644 doc/s6-ftrig-notify.html create mode 100644 doc/s6-ftrig-wait.html create mode 100644 doc/s6-ftrigrd.html create mode 100644 doc/s6-log.html create mode 100644 doc/s6-mkfifodir.html create mode 100644 doc/s6-notifywhenup.html create mode 100644 doc/s6-setlock.html create mode 100644 doc/s6-setsid.html create mode 100644 doc/s6-setuidgid.html create mode 100644 doc/s6-softlimit.html create mode 100644 doc/s6-supervise.html create mode 100644 doc/s6-svc.html create mode 100644 doc/s6-svok.html create mode 100644 doc/s6-svscan-1.html create mode 100644 doc/s6-svscan-not-1.html create mode 100644 doc/s6-svscan.html create mode 100644 doc/s6-svscanctl.html create mode 100644 doc/s6-svstat.html create mode 100644 doc/s6-svwait.html create mode 100644 doc/s6-tai64n.html create mode 100644 doc/s6-tai64nlocal.html create mode 100644 doc/scandir.html create mode 100644 doc/servicedir.html create mode 100644 doc/systemd.html create mode 100644 doc/ucspilogd.html create mode 100644 doc/upgrade.html create mode 100644 doc/why.html (limited to 'doc') diff --git a/doc/fifodir.html b/doc/fifodir.html new file mode 100644 index 0000000..99805ed --- /dev/null +++ b/doc/fifodir.html @@ -0,0 +1,123 @@ + + + + + s6: fifodirs + + + + + + +

+s6
+Software
+skarnet.org +

+ +

Fifodirs

+ +

+ A fifodir is a rendez-vous point between the notifier +of certain events and its listeners. It is implemented via a +directory in the filesystem. No data is stored; it is appropriate to +create fifodirs in a RAM filesystem. +

+ +

Manipulating fifodirs

+ +

C API

+ + + +

Unix API

+ + + +

Internals and Unix permissions

+ + + +

+Fifodirs are created by, so they always originally have the same uid and gid as, +their notifier. A notifier must be able to make his fifodir either publically +accessible (anyone can subscribe) or restricted (only a given group can +subscribe). +

+ +

+ A publically accessible fifodir must have rights 1733: +

+ + + +

+ A restricted fifodir must have the gid g of the group of allowed +listeners and have rights 3730. Unless the notifier is root, it +must be in the group of allowed listeners to be able to create +such a fifodir. +

+ + + +

+ A named pipe in a fifodir must always belong to its listener and have +rights 0622: +

+ + + +

+ The libftrig interface takes care of all +the subtleties. +

+ + + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..048af4f --- /dev/null +++ b/doc/index.html @@ -0,0 +1,291 @@ + + + + + s6 - skarnet's small supervision suite + + + + + + +

+Software
+skarnet.org +

+ +

s6

+ +

What is it ?

+ +

+ s6 is a small suite of programs for UNIX, designed to allow process supervision +(a.k.a service supervision), +in the line of daemontools +and runit. +

+ +

+ The s6 documentation tries to be complete and self-contained; however, +if you have never heard of process supervision before, you might be +confused at first. See the related resources section +below for pointers to more resources, and earlier approaches to process +supervision that might help you understand the basics. +

+ +
+ + + +
+ +

Installation

+ +

Requirements

+ + + +

Licensing

+ +

+ s6 is free software. It is available under the +ISC license. +

+ +

Download

+ + + +

Compilation

+ + + +

Upgrade notes

+ + + +
+ +

Reference

+ +

Commands

+ +

+ All these commands exit 111 if they encounter a temporary error or +hardware error, and +100 if they encounter a permanent error - such as a misuse. Short-lived +commands exit 0 on success. +

+ +

Supervision system

+ +

+ s6-svscan and s6-supervise +are the long-lived processes maintaining the supervision tree. Other programs are +a user interface to control those processes and monitor service states. +

+ + + +

Other daemontools-like utilities

+ +

+ These programs are a rewrite of the corresponding utilities from +daemontools, with +a few extras. The +s6-log program is important in itself: it's +a powerful, scriptable, general-purpose filtering and logging tool +that can be used to entirely replace syslogd. It has many more +features than its multilog +counterpart. +

+ + + +

Fifodir management, notification and subscription

+ +

+These programs are a clean rewrite of the obsolete "pipe-tools" package; they +are now based on a properly designed notification library. +They provide a command-line interface to +inter-process notification and +synchronization. +

+ + +

+

+ +

+

+ + +

Internal commands

+ + + + +

Libraries

+ + + +

Definitions

+ + + +
+ + +

Related resources

+ + +

s6 discussion

+ + + +

Similar work

+ + + +

Other init systems

+ + + +

+All-in-one init systems generally feel complex and convoluted, and when most +people find out about the process supervision approach to init systems, they +usually find it much simpler. +There is a good reason for this. +

+ + +

Credits

+ + s6 is one of the (late...) results of a long design discussion that +happened in 2002-2003 on the +supervision list +and the log list. +The main contributors to the thread were + + +

Miscellaneous

+ +

Why "s6" ?

+ +

+skarnet.org's small and secure +supervision software suite. +

+ +

+ Also, s6 is a nice command name prefix to have: it identifies the origin of the +software, and it's short. Expect more use of s6- in future skarnet.org software +releases. And please avoid using that prefix for your own projects. +

+ + + diff --git a/doc/libftrig.html b/doc/libftrig.html new file mode 100644 index 0000000..da4c25b --- /dev/null +++ b/doc/libftrig.html @@ -0,0 +1,184 @@ + + + + + s6: libftrig + + + + + + +

+s6
+Software
+skarnet.org +

+ +

libftrig

+ +

+libftrig is a portable Unix C programming interface allowing a +process (the subscriber or listener) to be instantly +notified when another process (the notifier or writer) +signals an event. +

+ + +

What is notification ?

+ + +

Notification vs. polling

+ +

+ Process A is notified of an event E when it gets a instant +notice that event E has happened; the notice may disrupt A's execution +flow. Notification is the opposite of polling, where A has to +periodically (every T milliseconds) check whether E happened and has no +other way to be informed of it. +

+ +

+ Polling is generally considered bad practice - and is inferior to +notification in practically every case - for three reasons: +

+ + + +

+ Notification, on the other hand, is generally optimal: reaction time is +zero, and resource consumption is minimal - a process can sleep as soon as +it's not handling an event, and only wake up when needed. +

+ +

+ Of course, the problem of notification is that it's often more difficult +to implement. Notification frameworks are generally more complex, involving +lots of asynchronism; polling is widely used +because +it's easy. +

+ +

Notifications and Unix

+ +

+ Unix provides several frameworks so that a process B (or the kernel) can +notify process A. +

+ + + +

What we want

+ +

+ We need a general framework to: +

+ + + +

+ This requires a many-to-many approach that Unix does not provide natively, and +that is what libftrig does. +

+ + +

That's what a bus is for. D-Bus already does all this.

+ + +

+ Yes, a bus is a good many-to-many notification mechanism indeed. However, +a Unix bus can only be implemented via a daemon - you need a long-running +process, i.e. a service, to implement a bus. And s6 is a +supervision suite, i.e. a set of programs designed to manage +services; we would like to be able to use notifications in the supervision +suite, to be able to wait for a service to be up or down... without +relying on a particular service to be up. libftrig provides a notification +mechanism that does not need a bus service to be up, that's its +main advantage over a bus. +

+ +

+ If you are not concerned with supervision and can depend on a bus service, +though, then yes, by all means, use a bus for your notification needs. +There is a skabus +project in the making, which aims to be simpler, smaller and more +maintainable than D-Bus. +

+ +

How to use libftrig

+ +

+ libftrig is really a part of libs6: all the functions +are implemented in the libs6.a archive, or the libs6.so +dynamic shared object. However, the interfaces are different for notifiers +and listeners: +

+ + + + + diff --git a/doc/libftrigr.html b/doc/libftrigr.html new file mode 100644 index 0000000..27ffd61 --- /dev/null +++ b/doc/libftrigr.html @@ -0,0 +1,283 @@ + + + + + s6: the ftrigr library interface + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The ftrigr library interface

+ +

+ The ftrigr library provides an API for listeners, i.e. +programs that want to subscribe to fifodirs and be instantly +notified when the proper sequence of events happens. +

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ +

+ Check the s6/ftrigr.h header for the +exact function prototypes. +

+ +

+ Make sure your application is not disturbed by children it doesn't +know it has. This means paying some attention to the SIGCHLD handler, +if any, and to the way you perform waitpid()s. The best +practice is to use a +self-pipe +to handle SIGCHLD (as well as other signals the application needs to trap), +and to always use wait_nohang() to reap children, +simply ignoring pids you don't know. +

+ +

+ If your (badly programmed) application has trouble handling unknown +children, consider using a ftrigrd service. +

+ +

A programming example

+ +

+ The src/pipe-tools/s6-ftrig-listen1.c and +src/supervision/s6-svwait.c files in the s6 package, +for instance, illustrate how to use the ftrigr library. +

+ + +

Synchronous functions with a specified maximum execution time

+ + + + +

Starting and ending a session

+ +
+ftrigr_t a = FTRIGR_ZERO ;
+struct taia deadline, stamp ;
+
+taia_now(&stamp) ;
+taia_addsec(&deadline, &stamp, 2)
+
+// char const *path = FTRIGR_IPCPATH ;
+// ftrigr_start(&a, path, &deadline, &stamp) ;
+ftrigr_startf(&a, &deadline, &stamp) ;
+
+ +

+ftrigr_start starts a session with a ftrigrd service listening on +path.
+ftrigr_startf starts a session with a ftrigrd process as a child +(which is the simplest usage).
+a is a ftrigr_t structure that must be declared in the stack and +initialized to FTRIGR_ZERO. +stamp must be an accurate enough timestamp.
+If the session initialization fails, the function returns 0 and errno is set; +else the function returns 1. +

+

+If the absolute time deadline is reached and the function +has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. + +Only local interprocess communications are involved; unless your system is +heavily overloaded, the function should return near-instantly. One or two +seconds of delay between stamp and deadline should be +enough: if the function takes more than that to return, then there is a +problem with the underlying processes. +

+ +

+ You can have more than one session open in parallel, by declaring +several distinct ftrigr_t structures and calling +ftrigr_startf (or ftrigr_start) more than once. +However, this is useless, since one single session can handle +virtually as many concurrent fifodirs as your application needs. +

+ +
+ftrigr_end(&a) ;
+
+ +

+ftrigr_end frees all the resources used by the session. The +a structure is then reusable for another session. +

+ +

Subscribing to a fifodir

+ +
+char const *path = "/var/lib/myservice/fifodir" ;
+char const *re = "a.*b|c*d" ;
+uint32 options = 0 ;
+
+uint16 id = ftrigr_subscribe (&a, path, re, options, &deadline, &stamp) ;
+
+ +

+ftrigr_subscribe instructs the +s6-ftrigrd daemon, related to the open +session represented by the a structure, to subscribe to the +path fifodir, and to notify the application when it receives +a series of events that matches the re regexp. +options can be 0 or FTRIGR_REPEAT. If it is 0, the daemon will +automatically unsubscribe from path once re has been +matched by a series of events. If it is FTRIGR_REPEAT, it will remain +subscribed until told otherwise. +

+ +

+ ftrigr_subscribe() returns 0 and sets errno in case of failure, or +a nonzero 16-bit number identifying the subscription in case of success. +

+ +

+ftrigr_subscribe should return near-instantly, but if +deadline is reached, it will return 0 ETIMEDOUT. If +ftrigr_subscribe returns successfully, then the +s6-ftrigrd daemon is guaranteed to be listening on path, +and events can be sent without the risk of a race condition. +

+ +

Synchronously waiting for events

+ +
+uint16 list[1] ;
+unsigned int n = 1 ;
+char trigger ;
+list[0] = id ;
+
+// r = ftrigr_wait_and(&a, list, n, &deadline) ;
+r = ftrigr_wait_or(&a, list, n, &deadline, &trigger) ;
+
+ +

+ ftrigr_wait_and() waits for all the n fifodirs +whose ids are listed in list to receive an event. It returns -1 +in case of error or timeout, or a non-negative integer in case of success.
+ ftrigr_wait_or() waits for one of the n fifodirs +whose ids are listed in list to receive an event. It returns -1 +in case of error or timeout; if it succeeds, the return value is the +position in list, starting at 0, of the identifier that received +an event; and trigger is set to the character that triggered that +event, i.e. the last character of a sequence that matched the regular +expression re used in the subscription. +

+ +

Asynchronously waiting for events

+ +

+ (from now on, the functions are listed with their prototypes instead +of usage examples.) +

+ +
+int ftrigr_fd (struct ftrigr const *a)
+
+ +

+ Returns a file descriptor to select on for reading. Do not +read() it though. +

+ +
+int ftrigr_update (ftrigr_ref a)
+
+ +

+ Call this function whenever the fd checks readability: it will +update a's internal structures with information from the +s6-ftrigrd daemon. It returns -1 if an error +occurs; in case of success, it returns the number of identifiers for +which something happened. +

+ +

+ When ftrigr_update returns, +genalloc_s(uint16, &a->list) points to an array of +genalloc_len(uint16, &a->list) 16-bit unsigned +integers. Those integers are ids waiting to be passed to +ftrigr_check. +

+ +
+int ftrigr_check (ftrigr_ref a, uint16 id, char *what)
+
+ +

+ Checks whether an event happened to id. Use after a +call to ftrigr_update(). +

+ + + + + diff --git a/doc/libftrigw.html b/doc/libftrigw.html new file mode 100644 index 0000000..d804976 --- /dev/null +++ b/doc/libftrigw.html @@ -0,0 +1,115 @@ + + + + + s6: the ftrigw library interface + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The ftrigw library interface

+ +

+ The ftrigw library provides an API for notifiers, i.e. +programs that want to regularly announce what they're doing. +

+ +

+ Notifiers should create a fifodir in a hardcoded place in the +filesystem, and document its location. Listeners will then be +able to subscribe to that fifodir, and receive the events. +

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ +

+ Check the s6/ftrigw.h header for the +exact function prototypes. +

+ +

Creating a fifodir

+ +
+char const *path = "/var/lib/myservice/fifodir" ;
+int gid = -1 ;
+int forceperms = 0 ;
+int r = ftrigw_fifodir_make(path, gid, forceperms) ;
+
+ +

+ftrigw_fifodir_make creates a fifodir at the path location. +It returns 0, and sets errno, if an error occurs. +It returns 1 if it succeeds.
+If a fifodir, owned by the user, already exists at path, and +forceperms is zero, then ftrigw_fifodir_make immediately +returns a success. If forceperms is nonzero, then +it tries to adjust path's permissions before returning. +

+ +

+If gid is negative, then path is created "public". +Any listener will be able to subscribe to path. +If gid is nonnegative, then path is created "private". +Only processes belonging to group gid will be able to +subscribe to path. +

+ +

Sending an event

+ +
+char event = 'a' ;
+r = ftrigw_notify(path, event) ;
+
+ +

+ftrigw_notify sends event to all the processes that are +currently subscribed to path. +It returns -1 if an error occurs, or the number of successfully notified +processes. +

+ +

Cleaning up

+ +

+When stray KILL signals hit s6-ftrigrd processes, +1. it's a sign of incorrect system administration, 2. they can leave +unused named pipes in the fifodir. It's the fifodir's owner's job, i.e. +the notifier's job, to periodically do some housecleaning and take out +the trash. +

+ +
+r = ftrigw_clean(path) ;
+
+ +

+ftrigw_clean cleans path. It returns 0, and sets errno, +if it encounters an error. It returns 1 if it succeeds. +

+ + + diff --git a/doc/libs6lock/index.html b/doc/libs6lock/index.html new file mode 100644 index 0000000..3696b41 --- /dev/null +++ b/doc/libs6lock/index.html @@ -0,0 +1,256 @@ + + + + + s6: the s6lock library interface + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6lock library interface

+ +

General information

+ +

+ libs6lock is a C interface to timed locks. Unix natively provides +locks, but the locking primitives are synchronous, so either they are +unbounded in execution time or they require polling. libs6lock provides +poll-free locks that can timeout during attempted acquisition. +

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ + + +

Starting and ending a session

+ +
+s6lock_t a = S6LOCK_ZERO ;
+struct taia deadline ;
+
+taia_now_g() ;
+taia_addsec_g(&deadline, 2)
+
+char const *path = S6LOCK_IPCPATH ;
+s6lock_start_g(&a, path, &deadline) ;
+// char const *lockdir = "/tmp/lock" ;
+// s6lock_startf_g(&a, lockdir, &deadline) ;
+
+ +

+s6lock_start_g starts a session by connecting to a s6lockd service +listening on path. The working directory is set by the administrator +of the service.
+s6lock_startf_g starts a session with a s6lockd process as a child, +using lockdir as its working directory. +
+a is a s6lock_t structure that must be declared in the stack and +initialized to S6LOCK_ZERO. +If the session initialization fails, the function returns 0 and errno is set; +else the function returns 1. +

+

+If the absolute time deadline is reached and the function +has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. + +Only local interprocess communications are involved; unless your system is +heavily overloaded, the function should return near-instantly. One or two +seconds of delay between the current time and deadline should be +enough: if the function takes more than that to return, then there is a +problem with the underlying processes. +

+ +

+ You can have more than one session open in parallel, by declaring +several distinct s6lock_t structures and calling +s6lock_startf_g (or s6lock_start_g) more than once. +However, one single session can handle +virtually as many concurrent locks as your application needs, so +opening several sessions is only useful if you need to acquire locks +in various distinct lock directories. +

+ +
+s6lock_end(&a) ;
+
+ +

+s6lock_end frees all the resources used by the session. The +a structure is then reusable for another session. +

+ +

Acquiring and releasing locks

+ +
+uint16 id ;
+char const *file = "lockfile" ;
+struct taia limit ;
+struct taia deadline ;
+
+int r = s6lock_acquire_sh_g (&a, &id, file, &limit, &deadline) ;
+/* int r = s6lock_acquire_ex_g (&a, &id, file, &limit, &deadline) ; */
+r = s6lock_release_g(&a, id, &deadline) ;
+
+ +

+s6lock_acquire_sh_g instructs the +s6lockd daemon, related to the open +session represented by the a handle, to try and acquire a +shared lock on the +file file located under that daemon's working directory +(typically /var/lock). file will be interpreted as +relative to the daemon's working directory even if it starts with a +slash; however, slashes in the middle of file are likely to +result in an error. +

+ +

+limit and deadline are two absolute dates. +deadline is a deadline for the execution of the +function: if by deadline the function has not returned, +then it instantly returns 0 and sets errno to ETIMEDOUT. The +function is normally near-instantaneous, so deadline can +be very close in the future and serves only as a protection against +malicious servers. limit is the acquisition deadline: if +by limit the daemon still has not been able to acquire a lock +on file, then it will report a timeout to the client. +

+ +

+The function returns 1 in case of success, or 0 if an error occurs, +with errno set to a suitable value. If it succeeds, then a 16-bit +number is stored into *id; this number serves as an identifier +for this lock. +

+ +

+s6lock_acquire_ex_g works just like s6lock_acquire_sh_g, +except that the daemon tries to acquire an exclusive lock. +

+ +

+s6lock_release_g releases the lock identified by id. +It normally returns 1. It can return 0 with errno set to a suitable +value if it fails. id is not valid after the corresponding +lock has been released. The function normally returns instantly, with +deadline as a safeguard. +

+ +

Asynchronously waiting for locks

+ +

+ (from now on, the functions are listed with their prototypes instead +of usage examples.) +

+ +
+int s6lock_fd (s6lock_t const *a)
+
+ +

+ Returns a file descriptor to select on for reading. Do not +read() it though. +

+ +
+int s6lock_update (s6lock_t *a)
+
+ +

+ Call this function whenever the fd checks readability: it will +update a's internal structures with information from the +s6lockd daemon. It returns -1 if an error +occurs; in case of success, it returns the number of identifiers for +which something happened. +

+ +

+ When s6lock_update returns, +genalloc_s(uint16, &a->list) points to an array of +genalloc_len(uint16, &a->list) 16-bit unsigned +integers. Those integers are ids waiting to be passed to +s6lock_check. +

+ +
+int s6lock_check (s6lock_t *a, uint16 id, char *what)
+
+ +

+ Checks whether the lock identified by id has +been acquired. Use after a call to s6lock_update(). +

+ + + +

Synchronously waiting for locks

+ +

+ int s6lock_wait_or_g (s6lock_t *a, uint16 const *idlist, unsigned int n, struct taia const *deadline)
+Synchronously waits for one of the locks represented by the array pointed to +by idlist of length n to be acquired. Returns -1 if it fails, +or a nonnegative number on success, which is the index in idlist of the +acquired lock's id. If no result has been obtained by deadline, the +function returns -1 ETIMEDOUT. +

+ +

+ int s6lock_wait_and_g (s6lock_t *a, uint16 const *idlist, unsigned int n, struct taia const *deadline)
+Synchronously waits for all of the locks represented by the array pointed to +by idlist of length n to be acquired. Returns -1 if it fails and +0 if it succeeds. If no result has been obtained by deadline, the +function returns -1 ETIMEDOUT. +

+ + + diff --git a/doc/libs6lock/s6lockd-helper.html b/doc/libs6lock/s6lockd-helper.html new file mode 100644 index 0000000..839dce4 --- /dev/null +++ b/doc/libs6lock/s6lockd-helper.html @@ -0,0 +1,52 @@ + + + + + s6: the s6lockd-helper internal program + + + + + + +libs6lock
+s6
+Software
+skarnet.org

+ +

The s6lockd-helper program

+ +

+s6lockd-helper is a helper program for the s6lock daemon. +It just acquires a lock and holds it until it is killed or told to +exit by its parent daemon. +

+ +

Interface

+ +

+ s6lockd-helper is not meant to be invoked directly by the user: +it will be spawned by the +s6lockd program. +

+ +

Notes

+ + + + + diff --git a/doc/libs6lock/s6lockd.html b/doc/libs6lock/s6lockd.html new file mode 100644 index 0000000..726d2f8 --- /dev/null +++ b/doc/libs6lock/s6lockd.html @@ -0,0 +1,73 @@ + + + + + s6: the s6lockd internal program + + + + + + +libs6lock
+s6
+Software
+skarnet.org

+ +

The s6lockd program

+ +

+s6lockd is the s6lock daemon. It is a program that manages +a set of lock files in a given directory, and associated timeouts. +

+ +

Interface

+ +

+ s6lockd does not fork, does not background itself automatically, +and does not use syslog. It is not meant to be run directly by the +user: it will be spawned by the +s6lock client library. +

+ +

+ There are 2 ways to use s6lockd: +

+ +
    +
  1. Use the s6lock_startf() library call. +A s6lockd child will then be spawned from your +calling process, and automatically reaped when you call +s6lock_end(). It requires care with applications that +trap SIGCHLD. It also requires care with lock file permissions: +a s6lockd instance might not be able +to open a lock file created by a former instance run by another +client with different permissions.
    2. +
  2. Use the s6lock_start() library call, together with a +s6lockd service. +For once, this is the recommended setup: s6lockd creates empty +lock files, and having all s6lockd instances run under the same user +simplifies permissions management considerably.
    3. + +
+ +

+When run as a service, s6lockd has no "standalone" mode: it is +designed to work with a Unix +domain superserver, like +s6-ipcserver. +s6lockd follows the UCSPI +interface, it can be directly executed from the superserver. +

+ +

Notes

+ + + + + diff --git a/doc/notifywhenup.html b/doc/notifywhenup.html new file mode 100644 index 0000000..40b0593 --- /dev/null +++ b/doc/notifywhenup.html @@ -0,0 +1,75 @@ + + + + + s6: service startup notifications + + + + + + +

+s6
+Software
+skarnet.org +

+ +

Service startup notifications

+ +

+ It is easy for a process supervision suite to know when a service that was up +is now down: the long-lived process implementing the service is dead. The +supervisor, running as the daemon's parent, is instantly notified via a SIGCHLD. +When it happens, s6-supervise sends a 'd' event +to its ./event fifodir, so every subscriber +knows that the service is down. All is well. +

+ +

+ It is much trickier for a process supervision suite to know when a service +that was down is now up. The supervisor forks and execs the +daemon, and knows when the exec has succeeded; but after that point, it's all +up to the daemon itself. Some daemons do a lot of initialization work before +they're actually ready to serve, and it is impossible for the supervisor to +know exactly when the service is really ready. +s6-supervise sends a 'u' event to its +./event fifodir when it successfully +spawns the daemon, but any subscriber +reacting to 'u' is subject to a race condition - the service provided by the +daemon may not be ready yet. +

+ +

+ Reliable startup notifications need support from the daemons themselves. +Daemons should notify the outside world when the service they are providing +is reliably up - because only they know when it is the case. +

+ +

+ s6 provides two ways for daemons to perform startup notification. +

+ +
    +
  1. Daemons can use the ftrigw_notify() function, provided in +the ftrigw library. This is extremely +simple and efficient, but requires specific s6 support in the daemon.
    2. +
  2. Daemons can write something to a file descriptor of their choice, +then close that file descriptor, when they're ready to serve. This is +a generic mechanism that some daemons already implement, and does not +require anything specific in the daemon's code. The administrator can +then run the daemon under s6-notifywhenup, +which will properly catch the daemon's message and notify all the subscribers +with a 'U' event, meaning that the service is now up with no possible race +condition.
    3. +
+ +

+ The second method should really be implemented in every long-running +program providing a service. When it is not the case, it's impossible +to provide race-free startup notifications, and subscribers should be +content with the unreliable 'u' events provided by s6-supervise. +

+ + + diff --git a/doc/s6-cleanfifodir.html b/doc/s6-cleanfifodir.html new file mode 100644 index 0000000..5724666 --- /dev/null +++ b/doc/s6-cleanfifodir.html @@ -0,0 +1,42 @@ + + + + + s6: the s6-cleanfifodir program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-cleanfifodir program

+ +

+s6-cleanfifodir cleans up a fifodir. +

+ +

Interface

+ +
+     s6-cleanfifodir fifodir
+
+ +

+s6-cleanfifodir cleans up fifodir, that must belong to the current user. +That means it removes all stale FIFOs in fifodir. +

+ +

+ In normal use, it is not necessary to call s6-cleanfifodir. However, stale +FIFOs can be left by s6-ftrigrd processes that +were violently killed, so it's good practice to regularly clean up fifodirs. +

+ + + diff --git a/doc/s6-envdir.html b/doc/s6-envdir.html new file mode 100644 index 0000000..5ac92e2 --- /dev/null +++ b/doc/s6-envdir.html @@ -0,0 +1,66 @@ + + + + + s6: the s6-envdir program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-envdir program

+ +

+s6-envdir changes its environment, then executes into another program. +

+ +

Interface

+ +
+     s6-envdir [ -I | -i ] [ -n ] [ -f ] [ -c nullis ] dir prog...
+
+ + + +

Options

+ + + +

Notes

+ +

+ s6-envdir without options behaves exactly like +envdir. +

+ + + diff --git a/doc/s6-envuidgid.html b/doc/s6-envuidgid.html new file mode 100644 index 0000000..680e841 --- /dev/null +++ b/doc/s6-envuidgid.html @@ -0,0 +1,64 @@ + + + + + s6: the s6-envuidgid program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-envuidgid program

+ +

+s6-envuidgid sets the UID, GID and GIDLIST environment variables, +then executes into another program. +

+ +

Interface

+ +
+     s6-envuidgid account prog...
+
+ + + +

Notes

+ +

+ s6-envuidgid behaves like +envuidgid, except that: +

+ + + +

+ s6-envuidgid is useful when running a program that must start as root but can +drop its privileges later. Such a program can read its new uid/gid/groups info +from the UID, GID and GIDLIST environment variables. Superservers such as +s6-tcpserver4 +make use of this. +

+ + + diff --git a/doc/s6-fghack.html b/doc/s6-fghack.html new file mode 100644 index 0000000..ba3f351 --- /dev/null +++ b/doc/s6-fghack.html @@ -0,0 +1,50 @@ + + + + + s6: the s6-fghack program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-fghack program

+ +

+s6-fghack is an anti-backgrounding tool. +

+ +

Interface

+ +
+     s6-fghack prog...
+
+ + + +

Notes

+ +

+ s6-fghack is what it says: a hack. Ideally, you should never have to use it. +It is only useful when you want to supervise a daemon that does not provide a +"stay in the foreground" option; and even then, the right thing is to report +this as a bug to the daemon author and have it fixed. +

+ + + diff --git a/doc/s6-ftrig-listen.html b/doc/s6-ftrig-listen.html new file mode 100644 index 0000000..e1d2518 --- /dev/null +++ b/doc/s6-ftrig-listen.html @@ -0,0 +1,73 @@ + + + + + s6: the s6-ftrig-listen program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-ftrig-listen program

+ +

+s6-ftrig-listen subscribes to several fifodirs, then +spawns a program, then waits for pattern of events to occur on the fifodirs. +

+ +

Interface

+ +

+ In an execlineb +script: +

+ +
+     s6-ftrig-listen [ -a | -o ] [ -t timeout ] { fifodir1 regexp1 fifodir2 regexp2 ... } prog...
+
+ + + +

Options

+ + + +

Notes

+ +

+ s6-ftrig-listen can be used outside of an execlineb script by using the +internal argv syntax, but this syntax is an implementation detail and is +not documented as stable. In a shell +script, use execlineb -Pc 's6-ftrig-listen ...' to get the +benefits of the execlineb brace syntax. +

+ + + diff --git a/doc/s6-ftrig-listen1.html b/doc/s6-ftrig-listen1.html new file mode 100644 index 0000000..88e2c6a --- /dev/null +++ b/doc/s6-ftrig-listen1.html @@ -0,0 +1,88 @@ + + + + + s6: the s6-ftrig-listen1 program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-ftrig-listen1 program

+ +

+s6-ftrig-listen1 subscribes to a fifodir, then +spawns a program, then waits for a pattern of events to occur on the fifodir. +

+ +

+s6-ftrig-listen1 acts just as s6-ftrig-wait, +except it can make sure that the process sending the notifications is actually +started after there is a listener for those events. +

+ +

Interface

+ +
+     s6-ftrig-listen1 [ -t timeout ] fifodir regexp prog...
+
+ + + +

Options

+ + + +

Usage example

+ +

+ The following sequence of shell commands has a race condition: +

+ +

In terminal 1:

+
+s6-mkfifodir /tmp/toto
+s6-ftrig-wait /tmp/toto "message"
+
+ +

Then in terminal 2

+
+s6-ftrig-notify /tmp/toto message
+
+ +

+ Depending on the operating system's scheduler, there is the possibility that +the s6-ftrig-notify process starts sending "message" before the +s6-ftrig-wait process has actually subscribed to /tmp/toto, in which +case the notification will be missed. The following sequence of shell commands +accomplishes the same goal in a reliable way, without the race condition: +

+ +
+s6-mkfifodir /tmp/toto
+s6-ftrig-listen1 /tmp/toto "message" s6-ftrig-notify /tmp/toto message
+
+ + + diff --git a/doc/s6-ftrig-notify.html b/doc/s6-ftrig-notify.html new file mode 100644 index 0000000..fa1e8b5 --- /dev/null +++ b/doc/s6-ftrig-notify.html @@ -0,0 +1,44 @@ + + + + + s6: the s6-ftrig-notify program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-ftrig-notify program

+ +

+s6-ftrig-notify sends a series of events to a fifodir. +

+ +

Interface

+ +
+     s6-ftrig-notify fifodir message
+
+ +

+s6-ftrig-notify notifies all the current listeners in fifodir +with all the characters in message, one by one. +

+ +

Notes

+ +

+s6-ftrig-notify cannot be used to send the null character (event 0x00). +If you need to send the null character, use the C API: +ftrigw_notify(). +

+ + + diff --git a/doc/s6-ftrig-wait.html b/doc/s6-ftrig-wait.html new file mode 100644 index 0000000..a833782 --- /dev/null +++ b/doc/s6-ftrig-wait.html @@ -0,0 +1,51 @@ + + + + + s6: the s6-ftrig-wait program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-ftrig-wait program

+ +

+s6-ftrig-listen1 subscribes to a fifodir and +waits for a pattern of events to occur on this fifodir. +

+ +

Interface

+ +
+     s6-ftrig-wait [ -t timeout ] fifodir regexp
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-ftrigrd.html b/doc/s6-ftrigrd.html new file mode 100644 index 0000000..dbd611e --- /dev/null +++ b/doc/s6-ftrigrd.html @@ -0,0 +1,73 @@ + + + + + s6: the s6-ftrigrd program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-ftrigrd program

+ +

+s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well +as regular expressions on events. It takes orders from its client program that controls +it via the ftrigr library, and notifies it when desired +events happen. +

+ +

Interface

+ +

+ s6-ftrigrd is not meant to be called directly. +

+ + + +

+ s6-ftrigrd handles the grunt work of creating fifos in a +fifodir for a subscriber. It also wakes up on every +event, and compares the chain of events it received on a given fifodir with the +client-provided regexp. If the chain of events matches the regexp, it notifies +the client. +

+ +

Notes

+ +

+ The connection management between the client and s6-ftrigrd is entirely done +by the skaclient +library. +

+ +

+ s6-ftrigrd is entirely asynchronous. It stores unread notifications into heap +memory; it can grow in size if there are a lot of events and the client fails +to read them. To avoid uncontrolled growth, make sure your client calls +ftrigr_update() as soon as ftrigr_fd() becomes readable. +

+ + + diff --git a/doc/s6-log.html b/doc/s6-log.html new file mode 100644 index 0000000..0a525d6 --- /dev/null +++ b/doc/s6-log.html @@ -0,0 +1,508 @@ + + + + + s6: the s6-log program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-log program

+ +

+s6-log is a reliable logging program with automated log rotation, similar to +daemontools' multilog, +with full POSIX regular expression support. +

+ +

Interface

+ +
+     s6-log [ -q | -v ] [ -b ] [ -p ] [ -t ] [ -e ] logging script
+
+ +

+s6-log reads and compiles logging script to an internal +form. Then it reads its standard input, line by line, and performs actions +on it, following the script it is given. It does its best to ensure there +is never any log loss. It exits cleanly when stdin closes or when +it receives SIGTERM. +

+ +

Options

+ + + +

Logdirs

+ +

+A logdir (logging directory) is a place where logs are +stored. s6-log can be scripted to write into one or more logdirs. +

+ +

+ A logdir may contain the following files: +

+ + + +

Rotation

+ +

+ In a logdir, selected lines are appended to the current file. +When current becomes too big, a rotation happens. +The current file will be possibly processed, then +it will become an archived log file named +@timestamp.s, where timestamp, a +TAI64N +timestamp, is the absolute time of the rotation. If there are too +many archived log files in the logdir, the older ones are then +suppressed. Logging then resumes, to a brand new current +file. +

+ +

+ You can use this mechanism to ensure that your logs never fill up +the available disk space, for instance: something that neither +syslogd, nor syslog-ng, nor rsyslog offers. +

+ +

Processors

+ +

+ A processor script can be set for every logdir. When a rotation +occurs, current (which has then been renamed previous) is +fed to processor's stdin, and processor's stdout is saved +and archived. processor can also read the state file +on its fd 4; what it writes to its fd 5 will be saved as the next +state file, for the next rotation. +

+ +

+ Processors should not background themselves: s6-log considers the +processing done when its processor direct child dies. +Processors should exit 0 on success and nonzero on failure; if a +processor fails, s6-log will try it again after some +cooldown time. +

+ +

+ Processors make s6-log Turing-complete by allowing you to use any +external program to handle log files that are going to be archived. +

+ +

Logging script syntax

+ +

+ When starting up, s6-log reads its arguments one by one; this +argument sequence, or directive sequence, forms a +logging script which tells s6-log what to log, where, and how. +

+ +

+ Every directive can be a selection directive, a control +directive or an action directive. A valid logging script always +contains at least one action directive; every action directive can be +preceded by zero or more selection or control directives. s6-log will exit 100 +if the script is invalid. If it can process the script but the last directive +is not an action directive, s6-log will emit a warning. +

+ +

Selection directives

+ +

+ These directives tell s6-log whether to select or deselect lines it reads +from stdin; actions will only happen on selected lines. By default, every +line is selected. +

+ + + +

Control directives

+ +

+ These directives tune s6-log's behaviour for the next actions. +

+ + + +

Action directives

+ +

+ These directives determine what s6-log actually does with the +selected lines. +

+ + + + +

Signals

+ + + +

Examples

+ +
+     s6-log -bt n20 s1000000 /var/log/services/stuff
+
+ +

+ Logs all of stdin, prepending every line with a timestamp, into the +/var/log/services/stuff logdir, with a maximum archive of +20 log files of 1 MB each; makes sure every line has been written +before reading the next one. +

+ +
+     s6-log -t n30 E500 - +fatal: e - +^STAT =/var/log/foobard/status f s10000000 S15000000 !"gzip -nq9" /var/log/foobard
+
+ + + + +

Why use execlineb to interpret the "processor" string ?

+ +

+ Because it is exactly what +execlineb +is for. +

+ + + +

Why have another logging mechanism ?

+ +

+ Because the syslog mechanism and all its implementations (save one) suck. +I'm not being judgmental; I'm just stating the obvious. +

+ +

The syslog design is flawed from the start

+ +

+When +asked why he started rsyslog, Rainer Gerhards came up with a lot of +hand-waving and not a single word about technical points. There is a +reason for that: rsyslog is forked from sysklogd! So, no matter how +many bells and whistles are added to it, it still suffers from the same +basic flaws. +

+ +

+ The problem with syslogd does not come from such or such implementation. +The problem comes from syslog's design in the first place. +

+ + + +

+ syslog is slow, it's unsafe, and it's incomplete. The only reason people +use it is because it's historical, it exists, and there hasn't been any +serious alternative yet, except maybe +multilog, which +s6-log improves upon. +

+ +

A not-so-modest proposal: the logging chain

+ +

+ Unix distributions already do this to some extent, but it's at best +unclear where the logs go for any given program. +

+ + + +

+ So, given a program, where are its logs sent ? +

+ + + +

What does s6-log have to do with all this ?

+ +

+ In a logging chain situation, every service must have +its own logger. To avoid syslogd's design mistakes, one logger process +per service must be run. s6-log fits that role. Using s6-log as +your one-stop logger offers the following benefits: +

+ + + + +

You're wrong about being as powerful as +syslogd: s6-log does not do remote logging.

+ +

+ You mean you want to send, live, every log line +over the network via UDP ? You can't be serious. +

+ +

+ Do yourself a favor and use s6-log to write log lines to a logdir, +with a processor script that sends files-being-archived to the +network, possibly after compressing them. More reliability, less +log lines lost, less network traffic, better engineering. If you +have no disk to even write the current files to, write +to a small RAM filesystem. +

+ +

+ If you have to log stuff live via the network, you +do not need any local logging software. You don't even need syslogd. +Just filter your stderr via some grep that selects lines for +you, then sends them to a network socket. A trivial shell script, or +execline +script, can do that for you. +

+ +

+ Do not insist on using syslogd. It does nothing magical, and nothing +that can't be done in a simpler way using simpler tools. +

+ + + diff --git a/doc/s6-mkfifodir.html b/doc/s6-mkfifodir.html new file mode 100644 index 0000000..818a514 --- /dev/null +++ b/doc/s6-mkfifodir.html @@ -0,0 +1,46 @@ + + + + + s6: the s6-mkfifodir program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-mkfifodir program

+ +

+s6-mkfifodir creates a fifodir. +

+ +

Interface

+ +
+     s6-mkfifodir [ -f ] [ -g gid ] fifodir
+
+ +

+s6-mkfifodir creates fifodir, belonging to the current user. +

+ +

Options

+ + + + + diff --git a/doc/s6-notifywhenup.html b/doc/s6-notifywhenup.html new file mode 100644 index 0000000..ad7ef8e --- /dev/null +++ b/doc/s6-notifywhenup.html @@ -0,0 +1,80 @@ + + + + + s6: the s6-notifywhenup program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-notifywhenup program

+ +

+s6-notifywhenup launches a daemon while listening to a file descriptor, +and sends a 'U' event to a fifodir when it +receives something on that file descriptor. +

+ +

+This page explains why this program is +needed. +

+ +

Interface

+ +
+     s6-notifywhenup [ -d fd ] [ -e fifodir ] [ -f ] [ -t timeout ] prog...
+
+ + + +

Options

+ + + +

Notes

+ + + + + diff --git a/doc/s6-setlock.html b/doc/s6-setlock.html new file mode 100644 index 0000000..bab3e23 --- /dev/null +++ b/doc/s6-setlock.html @@ -0,0 +1,65 @@ + + + + + s6: the s6-setlock program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-setlock program

+ +

+s6-setlock takes a lock on a file, then executes into another program. +

+ +

Interface

+ +
+     s6-setlock [ -n | -N | -t timeout ] [ -r | -w ] file prog...
+
+ + + +

Options

+ + + +

Notes

+ + + + + diff --git a/doc/s6-setsid.html b/doc/s6-setsid.html new file mode 100644 index 0000000..2fe991b --- /dev/null +++ b/doc/s6-setsid.html @@ -0,0 +1,47 @@ + + + + + s6: the s6-setsid program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-setsid program

+ +

+s6-setsid runs a program as session leader. +

+ +

Interface

+ +
+     s6-setsid [ -I | -i ] prog...
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-setuidgid.html b/doc/s6-setuidgid.html new file mode 100644 index 0000000..f12ae04 --- /dev/null +++ b/doc/s6-setuidgid.html @@ -0,0 +1,49 @@ + + + + + s6: the s6-setuidgid program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-setuidgid program

+ +

+s6-setuidgid executes a program as another user. +

+ +

Interface

+ +
+     s6-setuidgid account prog...
+
+ + + +

Notes

+ +

+ s6-setuidgid can only be run as root. Its main use is to drop root privileges before +starting a daemon. +

+ + + diff --git a/doc/s6-softlimit.html b/doc/s6-softlimit.html new file mode 100644 index 0000000..4b112f8 --- /dev/null +++ b/doc/s6-softlimit.html @@ -0,0 +1,54 @@ + + + + + s6: the s6-softlimit program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-softlimit program

+ +

+s6-softlimit changes its process limits, then executes into another program. +

+ +

Interface

+ +
+     s6-softlimit [ -a allmem ] [ -c core ] [ -d data ] [ -f fsize ] [ -l lock ] [ -m mem ] [ -o ofiles ] [ -p proc ] [ -r res ] [ -s stack ] [ -t cpusecs ] prog...
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html new file mode 100644 index 0000000..1c1551e --- /dev/null +++ b/doc/s6-supervise.html @@ -0,0 +1,125 @@ + + + + + s6: the s6-supervise program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-supervise program

+ +

+s6-supervise monitors a long-lived process (or service), making sure it +stays alive, sending notifications to registered processes when it dies, and +providing an interface to control its state. s6-supervise is designed to be the +last non-leaf branch of a supervision tree, the supervised process +being a leaf. +

+ +

Interface

+ +
+     s6-supervise servicedir
+
+ + + +

Signals

+ +

+ s6-supervise reacts to the following signals: +

+ + + +

Usage notes

+ + + +

Implementation notes

+ + + + + diff --git a/doc/s6-svc.html b/doc/s6-svc.html new file mode 100644 index 0000000..72f0776 --- /dev/null +++ b/doc/s6-svc.html @@ -0,0 +1,104 @@ + + + + + s6: the s6-svc program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-svc program

+ +

+s6-svc sends commands to a running s6-supervise +process. In other words, it's used to control a supervised process; among +other benefits, it allows an administrator to send signals to daemons without +knowing their PIDs, and without using horrible hacks such as .pid files. +

+ +

Interface

+ +
+     s6-svc [ -abqhkti12fFpcoduxO ] servicedir
+
+ +

+s6-svc sends the given series of commands to the +s6-supervise process monitoring the +servicedir directory, then exits 0. It exits 111 if it cannot send +a command, or 100 if no s6-supervise process is running on servicedir. +

+ +

Options

+ + + +

Usage examples

+ +
 s6-svc -h /service/httpd
+

+ Send a SIGHUP to the process represented by the /service/httpd +service directory. Traditionally, this makes web servers reload their +configuration file. +

+ +
 s6-svc -t /service/sshd
+

+ Kill (and automatically restart, if the wanted state of the service is up) +the process represented by the /service/sshd service directory - +typically the sshd server. +

+ +
 s6-svc -d /service/ftpd
+

+ Take down the ftpd server. +

+ +
 s6-svc -a /service/httpd/log
+

+ Send a SIGALRM to the logger process for the httpd server. If this logger +process is s6-log, this triggers a log rotation. +

+ +

Internals

+ +

+s6-svc writes control commands into the servicedir/supervise/control +FIFO. A s6-supervise process running on servicedir will be listening to this FIFO, +and will read and interpret those commands. +

+ + + diff --git a/doc/s6-svok.html b/doc/s6-svok.html new file mode 100644 index 0000000..a43d253 --- /dev/null +++ b/doc/s6-svok.html @@ -0,0 +1,38 @@ + + + + + s6: the s6-svok program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-svok program

+ +

+s6-svok checks whether a service directory is +currently supervised. +

+ +

Interface

+ +
+     s6-svok servicedir
+
+ + + + + diff --git a/doc/s6-svscan-1.html b/doc/s6-svscan-1.html new file mode 100644 index 0000000..76bc31c --- /dev/null +++ b/doc/s6-svscan-1.html @@ -0,0 +1,374 @@ + + + + + s6: How to run s6-svscan as process 1 + + + + + + +

+s6
+Software
+skarnet.org +

+ +

How to run s6-svscan as process 1

+ +

+ It is possible to run s6-svscan as process 1, i.e. the init +process. However, that does not mean you can directly boot +on s6-svscan; that little program cannot do everything +your stock init does. Replacing the init process requires a +bit of understanding of what is going on. +

+ + +

The three stages of init

+ + +

+ The life of a Unix machine has three stages: +

+ +
    +
  1. The early initialization phase. It starts when the +kernel launches the first userland process, traditionally called init. +During this phase, init is the only lasting process; its duty is to +prepare the machine for the start of other long-lived processes, +i.e. services. Work such as mounting filesystems, setting the system clock, +etc. can be done at this point. This phase ends when process 1 launches +its first services.
    2. +
  2. The cruising phase. This is the "normal", stable state of an +up and running Unix machine. Early work is done, and init launches and +maintains services, i.e. long-lived processes such as gettys, +the ssh server, and so on. During this phase, init's duties are to reap +orphaned zombies and to supervise services - also allowing the administrator +to add or remove services. This phase ends when the administrator +requires a shutdown.
    3. +
  3. The shutdown phase. Everything is cleaned up, services are +stopped, filesystems are unmounted, the machine is getting ready to be +halted. During this phase, everything but the shutdown procedure gets +killed - the only surefire way to kill everything is kill -9 -1, +and only process 1 can survive it and keep working: it's only logical +that the shutdown procedure, or at least the shutdown procedure from +the kill -9 -1 on and until the final poweroff or reboot +command, is performed by process 1.
    4. +
+ +

+ As you can see, process 1's duties are radically different from +one stage to the next, and init has the most work when the machine +is booting or shutting down, which means a normally negligible fraction +of the time it is up. The only common thing is that at no point is process +1 allowed to exit. +

+ +

+ Still, all common init systems insist that the same init +executable must handle these three stages. From System V init to launchd, +via busybox init, you name it - one init program from bootup to shutdown. +No wonder those programs, even basic ones, seem complex to write and +complex to understand! +

+ +

+Even the runit +program, designed with supervision in mind, remains as process 1 all the +time; at least runit makes things simple by clearly separating the three +stages and delegating every stage's work to a different script that is +not run as process 1. (This requires very careful handling of the +kill -9 -1 part of stage 3, though.) +

+ +

+ One init to rule them all? +It ain't necessarily so! +

+ + +

The role of s6-svscan

+ + +

+ init does not have the right to die, but fortunately, it has the right +to execve()! +During stage 2, why use precious RAM, or at best, swap space, to store data +that are only relevant to stages 1 or 3? It only makes sense to have an +init process that handles stage 1, then executes into an init process that +handles stage 2, and when told to shutdown, this "stage 2" init executes into +a "stage 3" init which just performs shutdown. Just as runit does with the +/etc/runit/[123] scripts, but exec'ing the scripts as process 1 +instead of forking them. +

+ +

+It becomes clear now that +s6-svscan is perfectly suited to +exactly fulfill process 1's role during stage 2. +

+ + + +

+ However, an init process for stage 1 and another one for stage 3 are still +needed. Fortunately, those processes are very easy to design! The only +difficulty here is that they're heavily system-dependent, so it's not possible +to provide a stage 1 init and a stage 3 init that will work everywhere. +s6 was designed to be as portable as possible, and it should run on virtually +every Unix platform; but outside of stage 2 is where portability stops, and +the s6 package can't help you there. +

+ +

+ Here are some tips though. +

+ + +

How to design a stage 1 init

+ + +

What stage 1 init must do

+ + + +

+ Unlike the /etc/runit/1 script, an init-stage1 script running as +process 1 has nothing to back it up, and if it fails and dies, the machine +crashes. Does that mean the runit approach is better? It's certainly safer, +but not necessarily better, because init-stage1 can be made extremely +small, to the point it is practically failproof, and if it fails, it +means something is so wrong that you +would have had to reboot the machine with init=/bin/sh anyway. +

+ +

+ To make init-stage1 as small as possible, only this realization is needed: +you do not need to perform all of the one-time initialization tasks before +launching s6-svscan. Actually, once init-stage1 has made it possible for +s6-svscan to run, it can fork a background "init-stage2" process and exec +into s6-svscan immediately! The "init-stage2" process can then pursue the +one-time initialization, with a big advantage over the "init-stage1" +process: s6-svscan is running, as well as a few vital services, and if +something bad happens, there's a getty for the administrator to log on. +No need to play fancy tricks with /dev/console anymore! Yes, +the theoretical separation in 3 stages is a bit more supple in practice: +the "stage 2" process 1 can be already running when a part of the +"stage 1" one-time tasks are still being run. +

+ +

+ Of course, that means that the scan directory is still incomplete when +s6-svscan first starts, because most services can't yet be run, for +lack of mounted filesystems, network etc. The "init-stage2" one-time +initialization script must populate the scan directory when it has made +it possible for all wanted services to run, and trigger the scanner. +Once all the one-time tasks are done, the scan directory is fully +populated and the scanner has been triggered, the machine is fully +operational and in stage 2, and the "init-stage2" script can die. +

+ +

Is it possible to write stage 1 init in a scripting language?

+ +

+ It is very possible, and I even recommend it. If you are using +s6-svscan as stage 2 init, stage 1 init should be simple enough +that it can be written in any scripting language you want, just +as /etc/runit/1 is if you're using runit. And since it +should be so small, the performance impact will be negligible, +while maintainability is enhanced. Definitely make your stage 1 +init a script. +

+ +

+ Of course, most people will use the shell as scripting +language; however, I advocate the use of +execline +for this, and not only for the obvious reasons. Piping s6-svscan's +stderr to a logging service before said service is even up requires +some tricky fifo handling that execline can do +and the shell cannot. +

+ + +

How to design a stage 3 init

+ + +

+ If you're using s6-svscan as stage 2 init on /service, then +stage 3 init is naturally the /service/.s6-svscan/finish program. +Of course, /service/.s6-svscan/finish can be a symbolic link +to anything else; just make sure it points to something in the root +filesystem (unless your program is an execline script, in which case +it is not even necessary). +

+ +

What stage 3 init must do

+ + + +

+ This is also very simple; even simpler than stage 1. + The only tricky part is the kill -9 -1 phase: you must make sure +that process 1 regains control and keeps running after it, because +it will be the only process left alive. But since we're running stage 3 +init directly, it's almost automatic! this is an advantage of running +the shutdown procedure as process 1, as opposed to, for instance, +/etc/runit/3. +

+ +

Is it possible to write stage 3 init in a scripting language?

+ +

+ You'd have to be a masochist, or have extremely specific needs, not to +do so. +

+ + +

How to log the supervision tree's messages

+ + +

+ When the Unix kernel launches your (stage 1) init process, it does it +with descriptors 0, 1 and 2 open and reading from or writing to +/dev/console. This is okay for the early boot: you actually +want early error messages to be displayed to the system console. But +this is not okay for stage 2: the system console should only be used +to display extremely serious error messages such as kernel errors, or +errors from the logging system itself; everything else should be +handled by the logging system, following the +logging chain mechanism. The +supervision tree's messages should go to the catch-all logger instead +of the system console. (And the console should never be read, so no +program should run with /dev/console as stdin, but this is easy +enough to fix: s6-svscan will be started with stdin redirected from +/dev/null.) +

+ +

+ The catch-all logger is a service, and we want every +service to run under the supervision tree. Chicken and egg problem: +before starting s6-svscan, we must redirect s6-svscan's output to +the input of a program that will only be started once s6-svscan is +running and can start services. +

+ +

+ There are several solutions to this problem, but the simplest one is +to use a FIFO, a.k.a. named pipe. s6-svscan's stdout and stderr can +be redirected to a named pipe before s6-svscan is run, and the +catch-all logger service can be made to read from this named pipe. +Only two minor problems remain: +

+ + + +

+ This second point cannot be solved in a shell script, and that is why +you are discouraged to write your stage 1 init script in the shell +language: you cannot properly set up a FIFO output for s6-svscan without +resorting to horrible and unreliable hacks involving a temporary background +FIFO reader process. +

+ +

+ Instead, you are encouraged to use the +execline language - +or, at least, +the redirfd +command, which is part of the execline distribution. The +redirfd +command does just the right amount of trickery with FIFOs for you to be +able to properly redirect process 1's stdout and stderr to the logging FIFO +without blocking: redirfd -w 1 /service/s6-svscan-log/fifo blocks +if there's no process reading on /service/s6-svscan-log/fifo, but +redirfd -wnb 1 /service/s6-svscan-log/fifo does not. +

+ +

+ This trick with FIFOs can even be used to avoid potential race conditions +in the one-time initialization script that runs in stage 2. If forked from +init-stage1 right before executing s6-svscan, depending on the scheduler +mood, this script may actually run a long way before s6-svscan is actually +executed and running the initial services - and may do dangerous things, +such as writing messages to the logging FIFO before there's a reader, and +eating a SIGPIPE and dying without completing the initialization. To avoid +that and be sure that s6-svscan really runs and initial services are really +started before the stage 2 init script is allowed to continue, it is possible +to redirect the child script's output (stdout and/or stderr) once again +to the logging FIFO, but in the normal way without redirfd trickery, before +it execs into the init-stage2 script. So, the child process blocks on the +FIFO until a reader appears, while process 1 - which does not block - execs +into s6-svscan and starts the logging service, which then opens the logging +FIFO for reading and unblocks the child process, which then runs the +initialization tasks with the guarantee that s6-svscan is running. +

+ +

+ It really is simpler than it sounds. :-) +

+ +

A working example

+ +

+ This whole page may sound very theoretical, dry, wordy, and hard to +grasp without a live example to try things on; unfortunately, s6 cannot provide +live examples without becoming system-specific. However, it provides a whole +set of script skeletons for you to edit and make your own working init. +

+ +

+ The examples/ROOT subdirectory in the s6 distribution contains +the relevant parts of a small root filesystem that works under Linux and follows +all that has been explained here. In every directory, a README file +has been added, to sum up what this directory does. You can copy those files +and modify them to suit your needs; if you have the proper software installed, +and the right configuration, some of them might even work verbatim. +

+ + + diff --git a/doc/s6-svscan-not-1.html b/doc/s6-svscan-not-1.html new file mode 100644 index 0000000..613ba3d --- /dev/null +++ b/doc/s6-svscan-not-1.html @@ -0,0 +1,140 @@ + + + + + s6: How to run s6-svscan under another init process + + + + + + +

+s6
+Software
+skarnet.org +

+ +

How to run s6-svscan under another init process

+ +

+ You can have a reliable supervision tree even if s6-svscan is not your process 1. +The supervision tree just has to be rooted in process 1: that means that +your process 1 will have to supervise your s6-svscan process somehow. That way, +if s6-svscan dies, it will be restarted, and your set of services will always +be maintained. +

+ +

+ Be aware, though, that pipes between services and loggers are maintained +by the s6-svscan process; if this process dies, the pipes will be closed and +some logs may be lost. +

+ + +

Logging the supervision tree's output

+ + +

+ s6-svscan and the various s6-supervise processes might produce error or +warning messages; those messages are written to s6-svscan's stderr (which +is inherited by the s6-supervise processes). To log these messages: +

+ + + +

+ In the following examples, we'll assume that /command/s6-svscanboot +is the name of the script you are using to start s6-svscan. Adjust this accordingly. +

+ + +

System V init

+ + +

+ Put an appropriate line in your /etc/inittab file, then reload this +config file with telinit q. +

+ +

Example

+ +
 SV:123456:respawn:/command/s6-svscanboot
+ + + +

Upstart

+ + +

+ Put an appropriate configuration file in the /etc/init folder, +for instance /etc/init/s6-svscan.conf, then start the service +with start s6-svscan. +

+ +

Example

+ +
# s6-svscan
+start on runlevel [2345]
+stop on runlevel [!2345]
+
+oom never
+respawn
+exec /command/s6-svscanboot
+
+ + +

systemd

+ +

+ systemd has +its +own way of supervising services. If you are a systemd user, chances +are you do not need s6. If you are interested in using s6, I encourage +you to also stop using systemd. +

+ +

+ +

+ + +

BSD init

+ + +

+ Put an appropriate line in your /etc/ttys file, then reload this +file with kill -s HUP 1. +

+ +

Example

+ +
 sv /command/s6-svscanboot "" on
+ + +

MacOS X launchd

+ + +

+ Like systemd, launchd comes with its own +way +of supervising services; if you are a launchd user, you probably do +not need s6. +

+ + + + diff --git a/doc/s6-svscan.html b/doc/s6-svscan.html new file mode 100644 index 0000000..4a7e800 --- /dev/null +++ b/doc/s6-svscan.html @@ -0,0 +1,176 @@ + + + + + s6: the s6-svscan program + + + + + + +

+s6
+Software
+www.skarnet.org +

+ +

The s6-svscan program

+ +

+s6-svscan starts and monitors a collection of s6-supervise +processes, each of these processes monitoring a single service. It is designed to be either +the root or a branch of a supervision tree. +

+ +

Interface

+ +
+     s6-svscan [ -c max ] [ -t rescan ] [ scandir ]
+
+ + + +

Options

+ + + +

Signals

+ +

+ s6-svscan reacts to the following signals: +

+ + + +

The reaper

+ +

+ Upon receipt of a SIGCHLD, or a s6-svscanctl -z +command, s6-svscan runs a reaper routine. +

+ +

+The reaper acknowledges (via some +wait() +function), without blocking, every terminated child of s6-svscan, even ones it does not +know it has. This is especially important when s6-svscan is +run as process 1. +

+ +

+ If the dead child is a s6-supervise process watched +by s6-svscan, and the last scan flagged that process as active, then it is restarted +one second later. +

+ +

The scanner

+ +

+ Every rescan milliseconds, or upon receipt of a SIGALRM or a +s6-svscanctl -a command, s6-svscan runs a +scanner routine. +

+ +

+ The scanner scans the current directory for subdirectories (or symbolic links +to directories), which must be service directories. +It skips names starting with dots. It will not create services for more than +max subdirectories. +

+ +

+ For every new subdirectory dir it finds, the scanner spawns a +s6-supervise process on it. If +dir/log exists, it spawns a s6-supervise process on +both dir and dir/log, and maintains a +never-closing pipe from the service's stdout to the logger's stdin. +This is starting the service, with or without a corresponding +logger. +Every service the scanner finds is flagged as "active". +

+ +

+ The scanner remembers the services it found. If a service has been +started in an earlier scan, but the current scan can't find the corresponding +directory, the service is then flagged as inactive. No command is sent +to stop inactive s6-supervise processes (unless the administrator +uses s6-svscanctl -n), but inactive +s6-supervise processes will not be restarted if they die. +

+ +

Implementation notes

+ + + + + diff --git a/doc/s6-svscanctl.html b/doc/s6-svscanctl.html new file mode 100644 index 0000000..cc7ae99 --- /dev/null +++ b/doc/s6-svscanctl.html @@ -0,0 +1,108 @@ + + + + + s6: the s6-svscanctl program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-svscanctl program

+ +

+s6-svscanctl sends commands to a running s6-svscan +process. +

+ +

Interface

+ +
+     s6-svscanctl [ -phratszbnNiq0678 ] svscandir
+
+ +

+s6-svscanctl sends the given series of commands to the +s6-svscan process monitoring the +svscandir directory, then exits 0. It exits 111 if it cannot send +a command, or 100 if no s6-svscan process is running on svscandir. +

+ +

Options

+ + + +

Usage examples

+ +
 s6-svscanctl -an /service
+

+ Updates the process supervision tree +to exactly match the services listed in /service. +

+ +
 s6-svscanctl -6 /service
+

+ Orders the s6-svscan process monitoring /service to exit in +reboot mode: all the supervision tree at /service will be terminated, +and s6-svscan will execute into the /service/.s6-svscan/finish +script with the reboot argument. +

+ +

Internals

+ +

+s6-svscanctl writes control commands into the svscandir/.s6-svscan/control +FIFO. A s6-svscan process running on svscandir will be listening to this FIFO, +and will read and interpret those commands. +

+ + + diff --git a/doc/s6-svstat.html b/doc/s6-svstat.html new file mode 100644 index 0000000..75ee7e2 --- /dev/null +++ b/doc/s6-svstat.html @@ -0,0 +1,45 @@ + + + + + s6: the s6-svstat program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-svstat program

+ +

+s6-svstat prints a short, human-readable summary of the state of a supervised +service. +

+ +

Interface

+ +
+     s6-svstat servicedir
+
+ +

+ s6-svstat gives the following information about the process being monitored +at the servicedir service directory, then +exits 0: +

+ + + + + diff --git a/doc/s6-svwait.html b/doc/s6-svwait.html new file mode 100644 index 0000000..6e15704 --- /dev/null +++ b/doc/s6-svwait.html @@ -0,0 +1,73 @@ + + + + + s6: the s6-svwait program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-svwait program

+ +

+s6-svwait blocks until a collection of supervised services goes up, or down. +

+ +

+s6-svwait only waits for notifications; it never polls. +

+ +

Interface

+ +
+     s6-svwait [ -U | -u | -d ] [ -a | -o ] [ -t timeout ] servicedir...
+
+ +

+s6-svwait monitors one or more service +directories given as its arguments, waiting for a state (up or down) to +happen. It exits 0 when the wanted condition becomes true. +

+ +

Options

+ + + + +

Internals

+ +

+s6-svwait spawns a s6-ftrigrd child to +listen to notifications sent by s6-supervise. +It also checks supervise/status files to get the current service +states, so it is immune to race conditions. +

+ + + diff --git a/doc/s6-tai64n.html b/doc/s6-tai64n.html new file mode 100644 index 0000000..8b7f5e0 --- /dev/null +++ b/doc/s6-tai64n.html @@ -0,0 +1,50 @@ + + + + + s6: the s6-tai64n program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-tai64n program

+ +

+s6-tai64n acts as a filter, reading from stdin and writing to stdout. +It prepends lines with a +TAI64N +timestamp and a space. +

+ +

Interface

+ +
+     s6-tai64n
+
+ + + +

Notes

+ +

+ s6-tai64n does neither "line buffering" nor "block buffering". It does +optimal buffering, i.e. it flushes its output buffer every time +it risks blocking on input. Every filter should behave this way, whether +its output is a tty or not: it's simpler and more efficient in every +case. +

+ + + diff --git a/doc/s6-tai64nlocal.html b/doc/s6-tai64nlocal.html new file mode 100644 index 0000000..f6d2280 --- /dev/null +++ b/doc/s6-tai64nlocal.html @@ -0,0 +1,73 @@ + + + + + s6: the s6-tai64nlocal program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-tai64nlocal program

+ +

+s6-tai64nlocal acts as a filter, reading from stdin and writing to stdout. +For every line that begins with a +TAI64N +timestamp, it replaces this timestamp with a human-readable local date and +time. +

+ +

Interface

+ +
+     s6-tai64nlocal
+
+ + + +

Notes

+ + + +

Troubleshooting

+ +

+ If s6-tai64nlocal does not appear to give the correct local time: +

+ + + + + diff --git a/doc/scandir.html b/doc/scandir.html new file mode 100644 index 0000000..366bd08 --- /dev/null +++ b/doc/scandir.html @@ -0,0 +1,145 @@ + + + + + s6: scan directories + + + + + + +

+s6
+Software
+skarnet.org +

+ +

Scan directories

+ +

+ A scan directory is a directory containing a list of +service directories, or symbolic links +pointing to service directories. +

+ +

+ A scan directory represents a list of services that are supposed to +be supervised. Running s6-svscan on this +scan directory launches a supervision tree: every service +listed in the scan directory will be supervised. +

+ +

+ There is normally only one scan directory per system, although nothing +prevents a system administrator from having more. +daemontools traditionally +uses /service, and runit +traditionally uses /etc/service. s6 does not care where your +scan directory is, but I would advise /service for compatibility +with daemontools. Depending on your installation, /service could +be a symbolic link and point to a place either in a RAM filesystem or in +/var. +

+ + +

Where and how to build a scan directory

+ + +

+ Opinions and practices differ. +

+ +

+ It is generally accepted that the place where you store all your +service directories (your "service repository") should not be +used as a scan directory - for a simple reason: you might want to have +service directories for more services than what you want to start at +any given time. In other words, your scan directory will be a subset +of your service repository, so you cannot just run s6-svscan on every +service you have a service directory for. So, the first thing is to +separate your service repository, which is just a storage place +for all the services you might want to manage someday, and your scan +directory, which is a directory representing all the services that +you are currently managing. +

+ +

Service repository

+ +

+ Where to store your service repository is purely a matter of personal +preference. You just have to be aware that +s6-supervise needs writable supervise and event +subdirectories in a service directory it monitors. +

+ +

Scan directory

+ +

+ Where and how to build your scan directory depends heavily on your boot +system - and on your personal preference too. +

+ +

+ Standard daemontools and +runit installations like to have +a fixed scan directory containing symlinks to service directories located +in the service repository. In other words, the service repository contains +the real working copies of the service directories. This works, +as long as: +

+ + + +

+ My own recommendation would be to have working copies of the service +directories entirely separate from the service repository. The +service repository can be safely stored on the root filesystem, and the +needed directories copied to a RAM filesystem at boot time. The scan +directory can be either the place where the working copies are written, +or another directory containing symlinks to those working copies. (The +latter is useful if you are not using s6-svscan -t0: copying a +directory is not atomic, but making a symlink is, so there is no risk +of your scanner finding an incomplete directory.) +

+ +

+ An example: +

+ + + + + diff --git a/doc/servicedir.html b/doc/servicedir.html new file mode 100644 index 0000000..b5c4d23 --- /dev/null +++ b/doc/servicedir.html @@ -0,0 +1,187 @@ + + + + + s6: service directories + + + + + + +

+s6
+Software
+skarnet.org +

+ +

Service directories

+ +

+ A service directory is a directory containing all the information +related to a service, i.e. a long-running process maintained and +supervised by s6-supervise. +

+ +

+ (Strictly speaking, a service is not always equivalent to a +long-running process. Things like Ethernet interfaces fit the definition +of services one may want to supervise; however, s6 does not +provide service supervision; it provides process supervision, +and it is impractical to use the s6 architecture as is to supervise +services that are not equivalent to one long-running process. However, +we still use the terms service and service directory +for historical and compatibility reasons.) +

+ +

Contents

+ + A service directory foo may contain the following elements: + + + + +

Where to store my service directories ?

+ + +

+ Service directories describe the way services are launched. Once they are +designed, they have little reason to change on a given machine. They can +theoretically reside on a read-only filesystem - for instance, the root +filesystem, to avoid problems with mounting failures. +

+ +

+ However, two subdirectories - namely supervise and event - +of every service directory need to be writable. So it has to be a bit more +complex. Here are a few possibilities. +

+ + + + + diff --git a/doc/systemd.html b/doc/systemd.html new file mode 100644 index 0000000..49ba2aa --- /dev/null +++ b/doc/systemd.html @@ -0,0 +1,120 @@ + + + + + s6: a word about systemd + + + + + + +

+s6
+Software
+skarnet.org +

+ +

A word about systemd

+ +

+ systemd +is becoming de facto a standard init system for Linux. But even +this choice of words is treacherous, because systemd is much more than +an init system. It's basically an integrated redesign of all the low-level +userspace of a Linux system, with great plans to change how software is +run and organized. + +

+ Which is not a bad thing per se: Unix software can definitely benefit +from improvements in this area, and the s6 suite, among other software, +comes from the same assessment and ultimately has the same goal. But +systemd suffers from a single conception flaw that sets it apart from +the other initiatives, and that has both political and technical +repercussions. +

+ +

+ + The single, overarching problem with systemd is that it attempts, in every +possible way, to do more instead of less. + +

+ +

The political issue

+ +

+ systemd attempts to cover more ground instead of less. +In other words, rather than simply being an init system, it tries to be +a complete overhaul of the way a Linux system is run, and tries to force +other software to hook with it in order to be supported. This goes very +much against: +

+ + + +

+ The reason why systemd has become so prevalent is not that it has been +accepted by the community. It's that it has manpower. It is backed up by +open source software companies that can provide much more manpower than +developers like myself working on free software on their own time. The +distribution model of systemd, made of lobbying and bullying, is much more +akin to the distribution model of Microsoft Windows than the one of GNU/Linux. +

+ +

+ Which says something. +

+ +

The technical issue

+ +

+ Software that does more instead of less is, simply put, +badly designed software. Trying to come up with an all-encompassing solution +is always a sign of developer hubris and inexperience, and never a sign of +good engineering. Ever. Remember sendmail, BIND, INN, and, definitely a better +analogy, the early days of Microsoft Windows ? Yes, systemd is in +exactly the same league. It's as if we had learned nothing from the +mistakes of the past 20 years. Technically as well as politically, systemd +is actually very close to Windows; is that the future we want for Linux +machines ? +

+ +

+ Doing more instead of less is bad, and it's especially true in the case of +system software, i.e. low-level software that +aims to make the machine work and that application software depends upon. +The goal of an operating system is to make it possible to run applications, +and system software should always partake in that goal. System software +should stay the heck out of the way, and systemd is big, loud and +obnoxious. Embedded devices are common, and will become even more common in +the future; that is a market that systemd will have trouble breaking into, because +it's a lot more complex than embedded devices need. And that, too, says something: +if a software suite is too complex for an embedded device, maybe it's just too +complex, period. +

+ +

Links

+ + + + + diff --git a/doc/ucspilogd.html b/doc/ucspilogd.html new file mode 100644 index 0000000..1b06335 --- /dev/null +++ b/doc/ucspilogd.html @@ -0,0 +1,94 @@ + + + + + s6: the ucspilogd program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The ucspilogd program

+ +

+ ucspilogd acts as a filter, converting syslog facility +numbers and alert levels into names. +

+ +

Interface

+ +
+     ucspilogd [ var ... ]
+
+ + + +

Common use

+ +

+ You can emulate the whole syslogd behaviour by combining the following +components: +

+ + + +

+ The resulting suite of programs is still smaller, and way more reliable, +than a standard syslogd. +

+ +

+ In the examples/ROOT/img/services-local/syslogd-linux subdirectory of the s6 package, you will +find a suitable ucspilogd service directory. +The run scripts are written in the +execline +language. +

+ +

Using ucspilogd as a klogd replacement

+ +

+ Certain Unix kernels offer a nice interface to the kernel logs. +For instance, the Linux kernel provides the /proc/kmsg fake +file, that can be opened and read like a normal file, excepts that +it gives the kernel logs when they are available and blocks otherwise. +You can use ucspilogd to process data from those interfaces. +

+ +

+ The examples/ROOT/img/services-local/klogd-linux subdirectory of the s6 package +is a service directory providing such a klogd service +for Linux, using the /proc/kmsg interface. +

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..1a35178 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,32 @@ + + + + + How to upgrade s6 + + + + + + +

+s6
+Software
+skarnet.org +

+ +

How to upgrade s6

+ +

to 2.0.0.0

+ + + + + diff --git a/doc/why.html b/doc/why.html new file mode 100644 index 0000000..1901259 --- /dev/null +++ b/doc/why.html @@ -0,0 +1,203 @@ + + + + + s6: why another supervision suite + + + + + + +

+s6
+Software
+skarnet.org +

+ +

Why another supervision suite ?

+ +

+ Supervision suites are becoming quite common. Today, we already have: +

+ + + +

+ Why is s6 needed ? What does it do differently ? Here are the criteria I used. +

+ + +

Supervision suites should not wake up unless notified.

+ + + + +

Supervision suites should provide a program that can run as process 1.

+ + + + +

Supervision suites should be bug-free, lightweight and easy to understand.

+ + + + +

Supervision suites should provide a basis for high-level service management.

+ + + + +

Artistic considerations

+ + + + +

Conclusion

+ +

+ All in all, I believe that s6 offers the best overall implementation of a +supervision suite as it should be designed. At worst, it's just another +take on daemontools with a reliable +base library and a few nifty features. +

+ + + -- cgit v1.3.1