PIDPROXY(1)

📦 version 4.3.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 PIDPROXY 💖

okay bestie, welcome to the pidproxy manual page — part of the Supervisor docs, and honestly? it's giving niche-but-essential 🎀

Supervisor is a client/server system that lets its users monitor and control a bunch of processes on UNIX-like operating systems. no cap.

It shares some of the same goals as programs like launchd, daemontools, and runit. but here's the plot twist: unlike some of those programs, it is not meant to be run as a substitute for init as "process id 1". instead, it's meant to be used to control processes related to a project or a customer, and it's meant to start like any other program at boot time. periodt. 💅

✨ OVERVIEW ✨

🦋 pidproxy Program

so here's the situation. some processes (like mysqld) straight-up ignore signals sent to the actual process which is spawned by supervisord. rude? kinda. instead, a "special" thread/process is created by these kinds of programs, and that thing is responsible for handling signals. this is problematic because supervisord can only kill a process which it creates itself. so if a process created by supervisord creates its own child processes, supervisord cannot kill them. 😭 the audacity.

fortunately 🍓, these types of programs typically write a "pidfile" which contains the "special" process' PID, and is meant to be read and used in order to kill the process. so as a workaround for this case, a special pidproxy program can handle startup of these kinds of processes.

the pidproxy program is a small shim that starts a process, and upon the receipt of a signal, sends the signal to the pid provided in a pidfile. tiny. mighty. iconic. 👑

a sample configuration program entry for a pidproxy-enabled program is provided below:

[program:mysql]
command=/path/to/pidproxy /path/to/pidfile /path/to/mysqld_safe

and where does this little legend live? the pidproxy program is put into your configuration's $BINDIR when supervisor is installed (it is a "console script"). slay. 💖

🌸 GLOSSARY 🌸

  • daemontools — a process control system by D.J. Bernstein.
  • runit — a process control system.

🫶 AUTHOR

this man page was created by Orestis Ioannou <orestis@oioannou.com> using the official documentation. shoutout 🎀

2004-2015, Agendaless Consulting and Contributors

okay that's the whole thing, bestie!! this page is from Supervisor version 3.2.0, dated December 10, 2015 — go forth and proxy those pids, mwah 💅✨🌈

📦 where this page comes from