runsv(8)

📦
version 2.3.1 · 6 versions
, in alpine 3.24, nixpkgs unstable

💅 runsv(8) — like, the whole manual, but make it make sense

okay bestie, gather round, because this is runsv(8) from the System Manager's Manual and it's genuinely one of the most iconic little supervisors in the Unix cinematic universe. it starts your service, it watches your service, and if you're fancy it also runs your log service. main character energy fr fr. 🎀

✨ NAME ✨

runsv — starts and monitors a service and optionally an appendant log service 🦋

🌸 SYNOPSIS 🌸

runsv service

💖 DESCRIPTION 💖

so first things first: service must be a directory. that's the vibe check, no exceptions. 💅

runsv switches into the directory service and starts ./run. that's the whole ritual. then:

  • if ./run exits and ./finish exists, runsv starts ./finish.
  • if ./finish doesn't exist, or ./finish exits, runsv restarts ./run.

the cycle never ends bestie, it's a loop, it's giving immortal. 🔥

and lowkey important: if ./run or ./finish exit immediately, runsv waits a second before starting ./finish or restarting ./run. one whole second. it's pacing itself, as it should. ⭐

now the part where ./finish gets two arguments, and yes both matter:

  1. the first one is ./run's exit code — or -1 if ./run didn't exit normally. 😭
  2. the second one is the least significant byte of the exit status as determined by waitpid(2). for instance it's 0 if ./run exited normally, and the signal number if ./run was terminated by a signal. 💀

and if runsv cannot start ./run for some reason? the exit code is 111 and the status is 0. write that down. 🍓

okay so if the file service/down exists, runsv does not start ./run immediately. it's on pause, it's in its quiet era. the control interface (see below, keep scrolling bestie) can be used to start the service and to give other commands to runsv.

now the log service part, and this is where it gets highkey gorgeous: if the directory service/log exists, runsv creates a pipe, redirects service/run's and service/finish's standard output to the pipe, switches to the directory service/log and starts ./run. and the standard input of service/log/run is redirected to read from the pipe. it's a whole relay race and everyone ate. 🌈

runsv also keeps receipts. it maintains status information:

  • in a binary format (compatible to the daemontools' supervise program) in service/supervise/status and service/log/supervise/status
  • and in a human-readable format in service/supervise/stat, service/log/supervise/stat, service/supervise/pid, service/log/supervise/pid

yes that's four human-readable files and two binary ones. every single one of them listed. 🫶

👑 CONTROL 👑

the named pipes service/supervise/control, and (optionally) service/log/supervise/control are provided to give commands to runsv. you can use sv(8) to control the service or just write one of the following characters to the named pipe. it's that simple, no cap:

  • u — Up. if the service is not running, start it. if the service stops, restart it. ⬆️
  • d — Down. if the service is running, send it a TERM signal, and then a CONT signal. if ./run exits, start ./finish if it exists. after it stops, do not restart service. ⬇️
  • o — Once. if the service is not running, start it. do not restart it if it stops. 1️⃣
  • p — Pause. if the service is running, send it a STOP signal. ⏸️
  • c — Continue. if the service is running, send it a CONT signal. ▶️
  • h — Hangup. if the service is running, send it a HUP signal. 📞
  • a — Alarm. if the service is running, send it a ALRM signal. ⏰
  • i — Interrupt. if the service is running, send it a INT signal. 🙈
  • q — Quit. if the service is running, send it a QUIT signal. 🚪
  • 1 — User-defined 1. if the service is running, send it a USR1 signal. 🥇
  • 2 — User-defined 2. if the service is running, send it a USR2 signal. 🥈
  • t — Terminate. if the service is running, send it a TERM signal. ✂️
  • k — Kill. if the service is running, send it a KILL signal. 💀
  • x — Exit. if the service is running, send it a TERM signal, and then a CONT signal. do not restart the service. if the service is down, and no log service exists, runsv exits. if the service is down and a log service exists, runsv closes the standard input of the log service, and waits for it to terminate. if the log service is down, runsv exits. this command is ignored if it is given to service/log/supervise/control. 🚪✨

Example: to send a TERM signal to the socklog-unix service, either do

 # sv term /service/socklog-unix

or

 # printf t >/service/socklog-unix/supervise/control

both work, pick your fighter. 🥊

heads up bestie: printf(1) usually blocks if no runsv process is running in the service directory. so if it just hangs there staring at you, that's why. 🫠

🧚 CUSTOMIZE CONTROL 🧚

okay so this is the glow-up feature and it's so underrated. for each control character c other than o, d, and x sent to the control pipe, runsv first checks if service/control/c exists and is executable. if so, it starts service/control/c and waits for it to terminate, before interpreting the command. and if the program exits with return code 0, runsv refrains from sending the service the corresponding signal. ✨

the command o is always considered as command u. 👀 (yes, always. even though o was excluded above. that's the rule.)

on command d first service/control/t is checked, and then service/control/d. on command x first service/control/t is checked, and then service/control/x.

specifically, and here's the play-by-play 💅:

if the service is running or paused, control characters d and x are handled as follows:

  1. runsv checks whether service/control/t exists and is executable and runs it if yes.
  2. if service/control/t exits nonzero, or is not executable or doesn't exist, runsv sends the service a TERM signal.
  3. runsv sends the service a CONT signal, disregarding service/control/c even if it exists and is executable.
  4. runsv checks whether service/control/d (or control/x) exists and is executable and runs it if yes. its exit status is ignored.

that step 4 exit status? ignored. we simply do not perceive it. 🫶

the control program runs with the process id of service as its first argument, or the empty string if there's no pid. 📝

and the plot twist nobody wanted: the control of the optional log service cannot be customized. periodt. 💀

⭐ SIGNALS ⭐

if runsv receives a TERM signal, it acts as if the character x was written to the control pipe. so a TERM is basically a text message saying "x" and it understands immediately. ✨

🌸 EXIT CODES 🌸

  • runsv exits 111 on an error on startup or if another runsv is running in service. 🚨
  • runsv exits 0 if it was told to exit. 🕊️

🔥 SEE ALSO 🔥

sv(8), chpst(8), svlogd(8), runit(8), runit-init(8), runsvdir(8), runsvchdir(8), utmpset(8)

https://smarden.org/runit/

💜 AUTHOR 💜

Gerrit Pape <pape@smarden.org>

and that's the whole page, bestie 🎀 — it lives in the System Manager's Manual (that's the manual name, now you know ✨) and the page itself is runsv(8), both at the top of this little screed and stamped at the very bottom where the date/version footer normally sits. mwah 💋 🦋 🌈 ⭐

📦 where this page comes from