S6-SVLINK(8)

📦 version 2.15.1.0, in nixpkgs unstable

okay bestie, so this is s6-svlink, straight out of the System Manager's Manual. It's a little utility that plugs service directories into a service manager sequence that's already running, and — plot twist — it kills race conditions while doing it. 🦋

✨ NAME ✨

s6-svlink — integrate service directories into an existing service manager sequence and eliminate race conditions. yes, "eliminate race conditions" is literally in the name-drop, she's confident.

🎀 SYNOPSIS 🎀

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

💖 DESCRIPTION 💖

So here's the vibe: s6-svlink creates a symlink to an s6-service-directory(7) inside an s6-scan-directory(7), and then it tells s6-svscan(8) "hey girl, new service just dropped." Then it waits — patiently, main character energy — until an s6-supervise(8) supervisor process has actually been spawned to manage that new service. Only then does it exit.

Let's break the whole routine down:

  • s6-svlink expects a running s6-svscan(8) process on scandir, plus a fully functional but unsupervised s6-service-directory(7) in servicedir. Both gotta be there, no cap.
  • It symlinks servicedir into scandir. The symbolic link is named name; and if you didn't pass a name argument, the link just takes the basename of servicedir. (She names it after herself, basically. 💅)
  • It sends a command to s6-svscan(8) to signal that a new service is available.
  • It waits for an s6-supervise(8) process to be spawned on servicedir.
  • It exits 0. slay.
ngl, using s6-svlink to start services is a suboptimal pattern. It requires precise manipulations involving s6-ftrigrd(8) in order to avoid race conditions, so it's relatively expensive. 😭

The simpler, more efficient pattern? Have all the supervisors already started at boot time — then the existence of the supervisor is a thing you can just rely on, and starting the service becomes a trivial and instant operation. That's exactly how the s6-rc service manager[1] behaves, iykyk. But it can be genuinely difficult to implement this pattern with other service managers such as OpenRC — and in those cases, s6-svlink, which starts the supervisors one at a time, is your girl 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. two supervisors, one icon. 👑

Also important: s6-svlink sends an s6-svscanctl -a command to scandir, which means the system's view of services will be refreshed. Depending on what links exist in scandir, other services than servicedir may also appear. so like, don't be shocked if the guest list grows. 🌈

The symmetrical program to s6-svlink is named s6-svunlink(8). they're a matching set, your honor. 🎀

🌸 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. ngl she's a little strict about this by default, and -f is you telling her to be strict on purpose. 💀
  • -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. so like, infinite patience unless you say otherwise. 🧚

⭐ EXIT STATUS ⭐

  • 0 — Success. we love to see it.
  • 99 — Timeout while waiting for the supervisor to start. 😭
  • 100 — Wrong usage. bestie, check your flags.
  • 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)

and that's the whole page, bestie 🫶 — brought to you by Debian, dated September 29, 2021, filed under s6-svlink(8). periodt. 💖✨

📦 where this page comes from