S6-SVC(8)

📦 version 2.15.1.0, in nixpkgs unstable

💅 S6-SVC(8) — send commands to a running s6-supervise(8) process

okay so bestie, welcome to s6-svc, from the System Manager's Manual (that's the manual name, we're folding it in right here at the top, you're welcome ✨). This is the little tool that lets you boss around a daemon without ever needing to know its PID. no cap.

🌸 SYNOPSIS

s6-svc [-wu | -wU | -wd | -wD | -wr | -wR] [-T timeout]
       [-s signal | abqhkti12pcyrPCK] [-oduDUxO] servicedirs...

🦋 DESCRIPTION

s6-svc is literally your remote control for a supervised process. Among other benefits — and this is the iconic part — it lets an administrator send signals to daemons without knowing their PIDs, and without resorting to horrible hacks like .pid files. we do not do that here. 💀

s6-svc sends the given series of commands to the s6-supervise(8) processes monitoring the servicedirs directories, then exits 0.

If an error occurs, s6-svc prints an error message and keeps processing servicedirs. It then exits with an error code corresponding to the last directory in servicedir that caused an error.

🎀 Notes

The -t and -r options make s6-supervise(8) send a signal to the service it's supervising if it is up; but if the service is currently down, they do nothing, and in particular they do not instruct s6-supervise(8) to bring the service up. Consequently, s6-svc -rwr servicedirs may wait forever for one of the services to be up, if it is currently wanted down. 😭 To avoid that, make sure your services are wanted up by using s6-svc -ruwr servicedirs instead. slay.

The U and D letters, which convey the same idea as u and d (up and down) but with added emphasis, do not have the same meaning in the -U / -D and -wU / -wD options. listen closely, this is the part that gets people:

  • In the -U / -D case, they mean "change the external service configurations to match what the supervisors have been instructed that the starting state of the services should be".
  • In the -wU / -wD case, they mean "wait until the services have reached the wanted state and also are ready" (or "ready to be started again" for -wD).

The thing to remember is "it's up/down, with something more", but the "something" isn't the same. iykyk 🫶

✨ OPTIONS ✨

  • -a — Send a SIGALRM to the supervised process.
  • -b — Send a SIGABRT to the supervised process.
  • -q — Send a SIGQUIT to the supervised process.
  • -h — Send a SIGHUP to the supervised process.
  • -k — Send a SIGKILL to the supervised process.
  • -t — Send a SIGTERM to the supervised process.
  • -i — Send a SIGINT to the supervised process.
  • -1 — Send a SIGUSR1 to the supervised process.
  • -2 — Send a SIGUSR2 to the supervised process.
  • -p — Send a SIGSTOP to the supervised process.
  • -c — Send a SIGCONT to the supervised process.
  • -y — Send a SIGWINCH to the supervised process.
  • -s signal — Send signal to the supervised process. signal can be given as its name (case-insensitive) or its number, but only the signals listed above are accepted — you cannot, for instance, manually send a SIGSEGV to the supervised process. 🚫
  • -o — Once. Equivalent to -uO.
  • -d — Down. If the supervised process is up, send it a SIGTERM (by default) then a SIGCONT (to make sure even stopped processes receive the signal aimed to kill them) and do not restart it. The SIGTERM default can be changed by editing the ./down-signal file in the s6-service-directory(7).
  • -D — Down, and create a ./down file so the service does not restart automatically if the supervisor dies. This option is mostly used by automated systems working on top of s6; as a human user, you probably don't need it. 🙈
  • -u — Up. If the supervised process is down, start it. Automatically restart it when it dies.
  • -U — Up, and remove any ./down file that may exist, in order to make sure the service is automatically restarted even if the supervisor dies. This option is mostly used by automated systems working on top of s6; as a human user, you probably don't need it. 🙈
  • -x — Exit. When the service is asked to be down and the supervised process dies, s6-supervise(8) will exit too. This command should normally never be used on a working system. 😬 Note that if this command is sent and a ./finish script exists for the service, the last ./finish invocation before s6-supervise(8) exits will run with its stdin and stdout redirected to /dev/null.
  • -O — Mark the service to run once at most. iow: do not restart the supervised process when it dies. If it is down when the command is received, do not even start it.
  • -Q — Once at most, and create a ./down file. Like -D, but do not terminate the service if it is currently running.
  • -r — If the service is up, restart it, by sending it a signal to kill it and letting s6-supervise(8) start it again. By default, the signal is a SIGTERM; this can be configured via the ./down-signal file in the s6-service-directory(7).
  • -T timeout — If the -wstate option has been given, -T specifies a timeout (in milliseconds) after which s6-svc will exit 1 with an error message if the service still hasn't reached the desired state. By default, the timeout is 0, which means that s6-svc will block indefinitely. ⏳
  • -wd — s6-svc will not exit until the service is down, i.e. until the run process has died.
  • -wD — s6-svc will not exit until the service is down and ready to be brought up, i.e. a possible finish script has exited.
  • -wu — s6-svc will not exit until the service is up, i.e. there is a process running the run executable.
  • -wU — s6-svc will not exit until the service is up and ready (cf. s6-notifywhenup(7)) as notified by the daemon itself. If the s6-service-directory(7) does not contain a notification-fd file to tell s6-supervise(8) to accept readiness notification, s6-svc will print a warning and act as if the -wu option had been given instead.
  • -wr — s6-svc will not exit until the service has been started or restarted.
  • -wR — s6-svc will not exit until the service has been started or restarted and has notified readiness.
  • -P — Send a SIGSTOP to the process group of the supervised process.
  • -C — Send a SIGCONT to the process group of the supervised process.
  • -K — Send a SIGKILL to the process group of the supervised process.

🔥 IMPLEMENTATION NOTES

s6-svc writes control commands into the x/supervise/control FIFO for every service directory x listed in servicedirs. An s6-supervise(8) process running on x will be listening to this FIFO, and will read and interpret those commands. cute, right? 🎀

When invoked with one of the -w options, s6-svc executes into s6-svlisten(8), which will listen to service state changes and spawn another s6-svc instance (without the -w option) that will send the commands to the services. Any error message written during the waiting period will mention it is being written by s6-svlisten(8); this is normal. don't panic bestie 💜

🧚 EXIT STATUS

  • 0 — Success. 💖
  • 100 — Usage error.
  • 102 — One of the arguments in servicedirs is not a currently supervised service directory.
  • 111 — System call failure.

🌈 EXAMPLES

s6-svc -h /run/service/httpd

Send a SIGHUP to the process represented by the /run/service/httpd service directory. Traditionally, this makes web servers reload their configuration file. ✨

s6-svc -r /run/service/sshd /run/service/httpd

Kill (and automatically restart, if the wanted state of the service is up) the process represented by the /run/service/sshd service directory — typically the sshd server — as well as the process represented by the /run/service/httpd directory — typically the Web server.

s6-svc -wD -d /run/service/ftpd

Take down the ftpd server and block until the process is down and the finish script has completed.

s6-svc -wU -T 5000 -u /run/service/ftpd

Bring up the ftpd server and block until it has sent notification that it is ready. Exit 1 if it is still not ready after 5 seconds.

s6-svc -twR /run/service/ftpd /run/service/gitd

Send a SIGTERM to the ftpd server and the git server; wait for their respective supervisors (cf. s6-supervise(8)) to restart them, and block until they both have notified that they are ready to serve again. See the "Notes" section. 👀

s6-svc -a /run/service/httpd/log

Send a SIGALRM to the logger process for the httpd server. If this logger process is s6-log(8), this triggers a log rotation. 🌀

👑 SEE ALSO

s6-notifyoncheck(8), s6-permafailon(8), s6-supervise(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-svc.html

🌸 AUTHORS

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

ok that's the whole page bestie, you ate that 💅 so anyway — this version came from Debian, dated November 2, 2025, and honestly? iconic. go forth and signal things responsibly. 🌟
📦 where this page comes from