catsit/catsitd.8

227 lines
3.9 KiB
Groff
Raw Normal View History

.Dd August 16, 2020
2020-08-15 22:40:15 +02:00
.Dt CATSITD 8
2020-08-13 23:34:58 +02:00
.Os
.
.Sh NAME
2020-08-15 22:40:15 +02:00
.Nm catsitd
2020-08-13 23:34:58 +02:00
.Nd process supervisor
.
.Sh SYNOPSIS
.Nm
.Op Fl d
.Op Fl C Ar path
.Op Fl c Ar control
2020-08-15 22:40:15 +02:00
.Op Fl f Ar config
2020-08-13 23:34:58 +02:00
.Op Fl g Ar group
.Op Fl p Ar pidfile
.Op Fl r Ar reset
2020-08-13 23:34:58 +02:00
.Op Fl s Ar stopexits
.Op Fl t Ar restart
2020-08-13 23:34:58 +02:00
.Op Fl u Ar user
.
.Sh DESCRIPTION
The
.Nm
daemon
is a process supervisor for
.Fx
and
.Ox .
It is designed to supervise processes
2020-08-13 23:34:58 +02:00
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 automatic restarts.
2020-08-13 23:34:58 +02:00
.
.Pp
The list of services is defined in a
2020-08-15 22:40:15 +02:00
.Xr catsit.conf 5
2020-08-13 23:34:58 +02:00
file.
The services managed by
.Nm
can be controlled
through a named pipe.
The
2020-08-15 22:40:15 +02:00
.Xr catsit 8
2020-08-13 23:34:58 +02:00
utility is a wrapper
for writing to the named pipe,
2020-08-13 23:34:58 +02:00
and its manual page
describes the control command syntax.
2020-08-13 23:34:58 +02:00
.
.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 service control.
2020-08-13 23:34:58 +02:00
.
.It Fl d
Do not run as a daemon.
Log to standard error
as well as syslog.
2020-08-13 23:34:58 +02:00
.
2020-08-15 22:40:15 +02:00
.It Fl f Ar config
2020-08-13 23:34:58 +02:00
Set the path of the
2020-08-15 22:40:15 +02:00
.Xr catsit.conf 5
2020-08-13 23:34:58 +02:00
file.
.
.It Fl g Ar group
Change group to
.Ar group
before starting services.
If
.Fl u
is set,
2020-08-13 23:34:58 +02:00
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 r Ar reset
Set the interval in milliseconds
for which a process must live
to have its service restart interval
reset to the initial value.
The default interval is 15 minutes.
.
2020-08-13 23:34:58 +02:00
.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
and
.Dv EX_CANTCREAT
2020-08-13 23:34:58 +02:00
defined in
2020-08-14 23:36:31 +02:00
.Xr sysexits 3 .
The exit statuses 126 and 127
are always treated as stop exits.
2020-08-13 23:34:58 +02:00
.
.It Fl t Ar restart
Set the initial interval in milliseconds
between automatic restarts.
This interval is doubled
each time a service
is automatically restarted.
The default interval is 1 second.
2020-08-13 23:34:58 +02:00
.
.It Fl u Ar user
Change user to
.Ar user
before starting services.
Services which are
.Em privileged
are started without changing user.
The
.Xr catsit.conf 5
manual page
describes privileged services.
2020-08-13 23:34:58 +02:00
.El
.
.Pp
The
2020-08-13 23:34:58 +02:00
.Nm
daemon takes the following actions
in response to signals:
.Bl -tag -width Ds
.It Dv HUP
The
2020-08-15 22:40:15 +02:00
.Xr catsit.conf 5
2020-08-13 23:34:58 +02:00
file is reloaded.
Services are not automatically
started, stopped or restarted.
Removed services can be dropped with
.Xr catsit 8 .
.
.It Dv TERM
The named pipe used for service control
is closed and unlinked.
All services are stopped,
after which
2020-08-13 23:34:58 +02:00
.Nm
exits.
.
.It Dv INFO
The current status of all services is logged.
.El
.
2020-08-13 23:34:58 +02:00
.Sh ENVIRONMENT
Services are started
with empty environments
apart from the following:
.Bl -tag -width Ds
.It Ev USER
2020-08-13 23:34:58 +02:00
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
2020-08-15 22:40:15 +02:00
.It Pa /usr/local/etc/catsit.conf
2020-08-13 23:34:58 +02:00
The default path of the
2020-08-15 22:40:15 +02:00
.Xr catsit.conf 5
file on
.Fx .
.It Pa /etc/catsit.conf
The default path of the
.Xr catsit.conf 5
file on
.Ox .
2020-08-15 22:40:15 +02:00
.It Pa /var/run/catsitd.pipe
2020-08-13 23:34:58 +02:00
The default path of the named pipe
used for service control.
2020-08-13 23:34:58 +02:00
.El
.
.Sh SEE ALSO
2020-08-15 22:40:15 +02:00
.Xr catsit.conf 5 ,
.Xr catsit 8
2020-08-13 23:34:58 +02:00
.
.Sh AUTHORS
.An June Bug Aq Mt june@causal.agency