Add prospective manual page for spawnd

1 files changed, 196 insertions, 0 deletions

diff --git a/spawnd.8 b/spawnd.8
new file mode 100644
index 0000000..fc97498
--- /dev/null
+++ b/spawnd.8
@@ -0,0 +1,196 @@
+.Dd August 13, 2020
+.Dt SPAWND 8
+.Os
+.
+.Sh NAME
+.Nm spawnd
+.Nd process supervisor
+.
+.Sh SYNOPSIS
+.Nm
+.Op Fl d
+.Op Fl C Ar path
+.Op Fl c Ar control
+.Op Fl f Ar spawntab
+.Op Fl g Ar group
+.Op Fl p Ar pidfile
+.Op Fl s Ar stopexits
+.Op Fl t Ar interval
+.Op Fl u Ar user
+.
+.Sh DESCRIPTION
+The
+.Nm
+daemon
+is a supervisor for processes
+with the following behavior:
+.Bl -enum
+.It
+The process runs in the foreground,
+not as a daemon.
+.It
+The process logs to standard output or standard error.
+.It
+The process handles errors by exiting
+and expects to be restarted.
+.It
+The process indicates its reason for exiting with
+.Xr sysexits 3 .
+.El
+.
+.Pp
+The
+.Nm
+daemon spawns processes for a list of
+.Em services ,
+redirects their output to syslog,
+and restarts the processes when they exit
+according to their exit status.
+Exponential backoff is applied to restarts.
+.
+.Pp
+The list of services is defined in a
+.Xr spawntab 5
+file.
+The services managed by
+.Nm
+can be controlled
+through a named pipe.
+The
+.Xr spawn 8
+utility is a wrapper
+around the named pipe,
+and its manual page
+describes the control command format.
+.
+.Pp
+The arguments are as follows:
+.Bl -tag -width Ds
+.It Fl C Ar path
+Change directory to
+.Ar path
+before starting services.
+By default the working directory is
+.Pa / .
+.
+.It Fl c Ar control
+Set the path of the named pipe
+used for control.
+.
+.It Fl d
+Do not run as a daemon.
+.
+.It Fl f Ar spawntab
+Set the path of the
+.Xr spawntab 5
+file.
+.
+.It Fl g Ar group
+Change group to
+.Ar group
+before starting services.
+If
+.Fl u
+is used,
+the default group is the user's group.
+.
+.It Fl p Ar pidfile
+Write the PID of the
+.Nm
+process to
+.Ar pidfile .
+.
+.It Fl s Ar stopexits
+Set the list of exit statuses
+for which a restart will not be attempted.
+The
+.Ar stopexits
+argument is a comma-separated list of integers.
+The default list contains the values of
+.Dv EX_USAGE ,
+.Dv EX_DATAERR ,
+.Dv EX_NOINPUT ,
+.Dv EX_OSFILE ,
+.Dv EX_CANTCREAT ,
+.Dv EX_CONFIG
+defined in
+.Xr sysexits 3 ,
+as well as 127.
+.
+.It Fl t Ar interval
+Set the initial interval between restarts
+in milliseconds.
+The default interval is 1000.
+.
+.It Fl u Ar user
+Change user to
+.Ar user
+before starting services.
+.El
+.
+.Pp
+When the
+.Nm
+daemon receives the
+.Dv HUP
+signal,
+the
+.Xr spawntab 5
+file is reloaded.
+Modified services
+are not automatically restarted,
+newly added services
+are not automatically started,
+and removed services
+are not automatically stopped.
+.
+.Pp
+When the
+.Nm
+daemon receives the
+.Dv TERM
+signal,
+the control named pipe is closed,
+all services are stopped,
+and
+.Nm
+exits.
+.
+.Sh ENVIRONMENT
+Services are started
+with empty environments
+apart from the following:
+.Bl -tag -width Ds
+.It Ev LOGNAME , Ev USER
+Set to the name of the user specified by
+.Fl u .
+.It Ev HOME
+Set to the home directory of the user specified by
+.Fl u .
+.It Ev SHELL
+Set to
+.Pa /bin/sh .
+.It Ev PATH
+Set to the system default defined by
+.Dv _PATH_DEFPATH
+in
+.In paths.h .
+.El
+.
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa /usr/local/etc/spawntab
+The default path of the
+.Xr spawntab 5
+file.
+.It Pa /var/run/spawnd.pipe
+The default path of the named pipe
+used for control.
+.El
+.
+.Sh SEE ALSO
+.Xr spawntab 5 ,
+.Xr spawn 8
+.
+.Sh AUTHORS
+.An June Bug Aq Mt june@causal.agency