S6-NOTIFYONCHECK(8)

📦 version 2.15.1.0, in nixpkgs unstable

🦋 s6-notifyoncheck — the "is it ready yet??" bestie of s6 (section 8, System Manager's Manual)

okay so picture this: you've got a daemon that has no idea how to tell s6 "hey girl I'm ready 💅", but it does answer if you poke it from the outside. s6-notifyoncheck is literally the friend who pokes it for you, over and over, until it finally says yes — and then she runs and tells s6 the good news. That's the whole vibe. ✨

🌸 SYNOPSIS 🌸

s6-notifyoncheck [-d] [-3 notiffd] [-s initialsleep] [-T globaltimeout]
                 [-t localtimeout] [-w waitingtime] [-n n]
                 [-c checkprog] prog...

💖 DESCRIPTION 💖

s6-notifyoncheck is a chain-loading program — meaning it slots itself into your run script, does its little job, and then hands the whole thing off. It's meant for a service that has already been declared to honor readiness notification. 👑

🚨 real talk: s6-notifyoncheck should only be used with daemons that can be polled from the outside to check readiness and that do not implement readiness notification themselves. Both conditions. No exceptions, bestie.

So here's the choreo: s6-notifyoncheck forks and runs as the child; the parent immediately execs into prog..., which is the daemon that must be checked for readiness. Like, zero hesitation, she's gone.

Then s6-notifyoncheck first waits for a little time (yes, a little vibe check pause 🌷), then spawns the ./data/check executable and waits for it to exit. If ./data/check exits 0, then s6-notifyoncheck reports that the service is ready, then exits. Slay. If ./data/check exits anything else, s6-notifyoncheck sleeps for a little time, then spawns ./data/check again. And it loops — until ./data/check succeeds, or 7 attempts fail, or a certain amount of time elapses. 🔁

s6-notifyoncheck exists so that services can use the s6 notification mechanism (cf. s6-notifywhenup(7)) even with daemons that do not natively implement the whole "write a newline to a file descriptor of their choice when they're ready" thing. She's basically the translator in the group chat. 🫶

💀 Polling is evil[1]. Please make sure you really have no other choice before writing a ./data/check program and using s6-notifyoncheck in your run script. If you have access to the source code of the daemon you want to check for readiness, consider patching it to add readiness notification support — which is extremely simple and does not require linking against any s6 library. fr fr, it's easier than you think.

If using a ./data/check program is your only option:

  • Make sure the ./data subdirectory is readable and that ./data/check is executable, exits 0 if the daemon it checks is ready, and exits nonzero if the daemon is not ready. ✅
  • Add a ./notification-fd file to your service directory, which can contain any number that is not 0, 1 or 2, or anything else explicitly used in your run script. The daemon does not need to care about that file descriptor; from the daemon's point of view, nothing changes. Like, it literally doesn't even know. 🙈
  • In your run script, insert s6-notifyoncheck in the command line that will execute into your daemon.
  • ./data/check will run as the same user as s6-notifyoncheck. If s6-notifyoncheck runs after the run script's process has lost its root privileges, make sure that ./data/check is accessible and runnable as that user. 👀
  • Note that s6-notifyoncheck should be used to check if the current service itself is running. You cannot use it to poll for the readiness of another service. Not her job, not her lane. 🙅
  • s6-notifyoncheck must be run with the service directory as its current working directory. In other words: you cannot use ‘cd’ in your run script before you execute the command line containing s6-notifyoncheck (else you will get a weird error message saying the supervisor is not running). If your service needs to run in a different working directory, you need to change working directories after the s6-notifyoncheck invocation. The cd(1) utility from the execline[2] package can be used to change working directories in the middle of a command line (and exec the rest of the command line) without invoking a shell. 🧚

✨ OPTIONS ✨

  • -d — Doublefork. s6-notifyoncheck will run as the grandchild of prog... instead of its direct child. This is useful if prog... never reaps zombies it does not know it has. 🧟 (yes, actual zombie management, iconic)
  • -3 notiffd — Use notiffd as the file descriptor to send a readiness notification to. By default, this number is automatically read from the ./notification-fd file. 📬
  • -s initialsleep — Sleep for initialsleep milliseconds before starting to poll the service for readiness. Default is 10 milliseconds. 😴
  • -T globaltimeout — Give up (and leave the service up but not ready) if service readiness still has not been detected after globaltimeout milliseconds. Default is 0, meaning infinite: s6-notifyoncheck will keep polling until it succeeds. ⏳
  • -t localtimeout — On every attempt, if ./data/check still has not exited after localtimeout milliseconds, kill it and declare that attempt failed. Default is 0, meaning infinite: s6-notifyoncheck will wait forever for ./data/check to exit. 🔪
  • -w waitingtime — Sleep for waitingtime milliseconds between two invocations of ./data/check. This is basically the polling period. Default is 1000: the service will be polled every second. 🕰️
  • -n n — Give up after n unsuccessful invocations of ./data/check. 0 means infinite, i.e. keep polling until it succeeds, or times out, or the service dies first. Default is 7. 7️⃣
  • -c checkprog... — Invoke checkprog... instead of ./data/check. The checkprog string will be parsed by execlineb(1), so it can contain a full command line. This option is mainly useful is the program used to poll the service is very simple and can be inlined as a simple command line, to avoid needing to manage a whole script and a ./data/check file. This option is only supported if the execline[2] package is installed; if it is not, the -c option cannot be used and the checking script must always be placed in ./data/check. 🎀

👑 EXIT STATUS 👑

s6-notifyoncheck can exit before executing into prog:

  • 100 — Wrong usage. 🙃
  • 111 — System call failed. 💀

After forking, s6-notifyoncheck (running as the child) can exit with the following exit codes, but those are meaningless because no process will, or should, check them. They are only differentiated for clarity in the code:

  • 0 — Service readiness achieved and notification sent. 🎉
  • 1 — Maximum number of attempts reached, all unsuccessful. 😭
  • 2 — prog died, so s6-notifyoncheck exited early. ⚰️
  • 3 — Timed out before readiness was achieved. ⌛
  • 111 — System call failed. 💀

🌈 SEE ALSO 🌈

execlineb(1), s6-permafailon(8), s6-supervise(8), s6-svc(8), s6-svdt(8), s6-svdt-clear(8), s6-svlisten(8), s6-svlisten1(8), s6-svok(8), s6-svscan(8), s6-svscanctl(8), s6-svstat(8), s6-svwait(8)

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

🫶 AUTHORS 🫶

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

and that's the whole page, bestie — no cap, every flag accounted for 💅 Sending you off with love from Debian, dated April 16, 2024, source S6-NOTIFYONCHECK(8) — go forth and poll responsibly, and remember: polling is evil 🔥🌸✨

📦 where this page comes from