S6-SVLINK(8)

NAME
s6-svlink - integrate service directories into an existing service manager sequence and eliminate race conditions

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

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

•   s6-svlink expects a running s6-svscan(8) process on scandir and a fully functional, but unsupervised, s6-service-directory(7) 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(8) to signal it that a new service is available.

•   It waits for an s6-supervise(8) process to be spawned on servicedir.

•   It exits 0.

Using s6-svlink to start services is a suboptimal pattern: it requires precise manipulations involving use of s6-ftrigrd(8) 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[1] 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.

s6-svlink sends an ‘s6-svscanctl -a’ command to scandir, which means that the system's view of services will be refreshed. Depending on what links exist in scandir, other services than servicedir may also appear.

The symmetrical program to s6-svlink is named s6-svunlink(8).

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 s6-fifodir(7). By default, it will be created as private, i.e. only processes running with the same gid as the s6-svscan(8) process will be able to subscribe 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.

EXIT STATUS

0   Success.

99  Timeout while waiting for the supervisor to start.

100 Wrong usage.

111 System call failed.

SEE ALSO
s6-fifodir(7), s6-scan-directory(7), s6-service-directory(7), s6-ftrigrd(8), s6-supervise(8), s6-svscan(8), s6-svscanctl(8), s6-svunlink(8)

[1] https://skarnet.org/software/s6-rc/

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-svlink.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)