add daemon supervisor

The supervise-daemon process is meant to be a lightweight supervisor
which can monitor and restart a daemon if it crashes.

1 files changed, 45 insertions, 0 deletions

diff --git a/supervise-daemon-guide.md b/supervise-daemon-guide.md
new file mode 100644
index 00000000..7dae0e65
--- /dev/null
+++ b/supervise-daemon-guide.md
@@ -0,0 +1,45 @@
+# Using supervise-daemon
+
+Beginning with OpenRC-0.21 we have our own daemon supervisor,
+supervise-daemon., which can start a daemon and restart it if it
+terminates unexpectedly.
+
+## Use Default start, stop and status functions
+
+If you write your own start, stop and status functions in your service
+script, none of this will work. You must allow OpenRC to use the default
+functions.
+
+## Daemons must not fork
+
+Any deamon that you would like to have monitored by supervise-daemon
+must not fork. Instead, it must stay in the foreground. If the daemon
+itself forks, the supervisor will be unable to monitor it.
+
+If the daemon has an option to instruct it not to fork, you should add this
+to the command_args_foreground variable listed below.
+
+## Variable Settings
+
+The most important setting is the supervisor variable. At the top of
+your service script, you should set this variable as follows:
+
+supervisor=supervise-daemon
+
+Several other variables affect the way services behave under
+supervise-daemon. They are documented on the  openrc-run man page, but I
+will list them here for convenience:
+
+pidfile=/pid/of/supervisor.pid
+
+If you are using start-stop-daemon to monitor your scripts, the pidfile
+is the path to the pidfile the daemon creates. If, on the other hand,
+you are using supervise-daemon, this is the path to the pidfile the
+supervisor creates.
+
+command_args_foreground should be used if the daemon you want to monitor
+forks and goes to the background by default. This should be set to the
+command line option that instructs the daemon to stay in the foreground.
+
+This is very early support, so feel free to file bugs if you have
+issues.