s6: the s6-svlink program
Keywords: s6 command s6-svlink supervision service start scandir servicedir

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 service directories into an existing service manager sequence and eliminate 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 an 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.
- `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.