From 691c69e626e4ceb85567a5288348bd04378fd410 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 30 Aug 2021 19:11:44 +0000 Subject: s6-svlink, s6-svunlink, .h changes Renamed from s6-svdir-(un)link. Doc added. Full functionality added. Still need to be tested. Unrelated: .h names simplified. Signed-off-by: Laurent Bercot --- doc/s6-svlink.html | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 doc/s6-svlink.html (limited to 'doc/s6-svlink.html') diff --git a/doc/s6-svlink.html b/doc/s6-svlink.html new file mode 100644 index 0000000..2e03eec --- /dev/null +++ b/doc/s6-svlink.html @@ -0,0 +1,111 @@ + + + + + + s6: the s6-svlink program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-svlink program

+ +

+ s6-svlink creates, in a scan +directory, a symlink to a service +directory, and notifies s6-svscan +that a new service has been registered. It waits until a +s6-supervise supervisor process has +been spawned to manage the new service, then exits. +

+ +

+ The point of s6-svlink is to help integrate existing +service directories into an existing service manager sequence and +eliminating race conditions. +

+ +

Interface

+ +

+     s6-svlink [ -d | -D ] [ -P ] [ -f ] [ -t timeout ] scandir servicedir [ name ]
+

+ +

s6-svlink expects a running s6-svscan +process on scandir and a fully functional, but unsupervised, +service directory in servicedir.
It symlinks servicedir into scandir. The symbolic link +is named name; if no name argument has been given, the name given +to the symbolic link is the basename of servicedir.
It sends a command to s6-svscan to signal it +that a new service is available.
It waits for a s6-supervise process to be +spawned on servicedir.
It exits 0.

+ +

Exit codes

+ +

0: success
99: timeout while waiting for the supervisor to start
100: wrong usage
111: system call failed

+ +

Options

+ +

-d : down. The supervisor will be started, but the service +itself will remain down. Any servicedir/down file will be +deleted. By default, if neither the -d nor -D options have +been given, the supervisor auto-starts the service as soon as it runs.
-D : down, and stay down. The supervisor will be started, +but the service itself will remain down. A servicedir/down file +will be created. By default, if neither the -d nor -D options have +been given, the supervisor auto-starts the service as soon as it runs.
-P : public. If servicedir/event does not +exist, it will be created as public, i.e. anyone will be able to subscribe to +this fifodir. By default, it will be created as private, +i.e. only processes running with the same gid as the s6-svscan +process will be able to susbscribe to it.
-f : force permissions. The presence or absence of the -P +option (i.e. the public or private state of servicedir/event) will be +enforced even if servicedir/event already exists. By default, +s6-svlink exits with an error message if servicedir/event +exists and its public/private state mismatches what is requested.
-t timeout : if the supervisor has not started +after timeout milliseconds, s6-svlink will print a message +to stderr and exit 99. By default, timeout is 0, which means no time +limit.

+ +

Notes

+ +

Using s6-svlink to start services is a suboptimal pattern: it +requires precise manipulations involving use of s6-ftrigrd +in order to avoid race conditions, so it is relatively expensive. The simpler, +more efficient pattern is to have all the supervisors already started at boot +time, so the existence of the supervisor can be relied on, and starting the +service becomes a trival and instant operation - this is, for instance, how +the s6-rc service manager behaves. +However, it can be difficult to implement this pattern with other services +managers such as OpenRC; in those cases, s6-svlink, which starts the +supervisors one at a time, can be used instead.
If servicedir is logged, i.e. servicedir/log +is also a valid service directory, then s6-svlink will wait until +supervisors have been spawned for both the service and its logger.

+ + + -- cgit v1.2.3