From 84b2c1858a5ef26bfa40a01fe57ed3cf0a1ada03 Mon Sep 17 00:00:00 2001 From: "C. McEnroe" Date: Mon, 17 Aug 2020 01:11:44 -0400 Subject: Flesh out documentation and improve examples --- catsit.8 | 31 +++++++++++++++++++-------- catsit.conf.5 | 28 +++++++++++++------------ catsitd.8 | 67 +++++++++++++++++++++++++++++++++-------------------------- 3 files changed, 75 insertions(+), 51 deletions(-) diff --git a/catsit.8 b/catsit.8 index ae4de38..7448012 100644 --- a/catsit.8 +++ b/catsit.8 @@ -39,6 +39,9 @@ Set the path of the named pipe. .It Cm start Start any matching services which are not already started. +Services scheduled for automatic restart +are started immediately +but their restart intervals are not reset. . .It Cm stop Stop any matching services @@ -49,8 +52,12 @@ signal. . .It Cm restart Restart any matching services. -Started services will first be stopped, -then stopped services will be started. +Started services will be stopped +and started again. +Stopped services will be started. +Services scheduled for automatic restart +will be started immediately +and their restart intervals will be reset. . .It Cm status Log the current status of any matching services. @@ -62,14 +69,21 @@ from the services list. .It Ar signal Send the named signal to the processes of any matching started services. +Signal names are case-insensitive. . .It Ar service ... The list of services to operate on. Service names can include -the shell-style pattern operators -.Sy *?[] . -Be sure to quote service name patterns -so they are not interpreted by the shell. +.Sy *?[] +shell-style pattern operators. +Patterns must be quoted +to be interpreted by +.Xr catsitd 8 +rather than the shell. +Each service name pattern +is operated on in order, +but services matched by each pattern +are in unspecified order. .El . .Sh ENVIRONMENT @@ -89,9 +103,8 @@ The default path of the named pipe. . .Sh EXAMPLES .Bd -literal -catsit start pounce/freenode -catsit status '*' -catsit USR1 'pounce/*' +catsit restart pounce/freenode +catsit INFO 'pounce/*' .Ed . .Sh SEE ALSO diff --git a/catsit.conf.5 b/catsit.conf.5 index eee5ed2..c18f683 100644 --- a/catsit.conf.5 +++ b/catsit.conf.5 @@ -20,7 +20,8 @@ is one of the following: .It Cm # Ar comment ... Lines beinning with .Ql # -and blank lines are ignored. +as well as blank lines +are ignored. . .It Cm % Ar command ... Lines beginning with @@ -62,20 +63,21 @@ or which call . .Sh EXAMPLES .Bd -literal -# Basic services: -calico calico -H irc.example.org /var/run/calico -pounce/freenode pounce /usr/local/etc/pounce/freenode.conf -pounce/tilde pounce /usr/local/etc/pounce/tilde.conf - # Setting environment variables: -% export PATH=$PATH:/usr/local/bin +% export LANG=en_US.UTF-8 -# Using variables to expand service command lines: -% pounce=/usr/local/bin/pounce -% conf=/usr/local/etc/pounce -pounce/freenode $pounce $conf/freenode.conf -pounce/tilde $pounce $conf/tilde.conf -.El +# Expanding command lines with variables: +% socks=/var/run/calico +calico calico -H irc.example.org $socks +pounce pounce -U $socks pounce.conf + +# Templating command lines using service names: +pounce/freenode pounce ${0#*/}.conf +pounce/tilde pounce ${0#*/}.conf + +# Privileged services: +@scooper kfcgi -d -U $USER -p ~/.local -- /bin/scooper +.Ed . .Sh SEE ALSO .Xr catsitd 8 diff --git a/catsitd.8 b/catsitd.8 index e5e7290..ae89531 100644 --- a/catsitd.8 +++ b/catsitd.8 @@ -47,7 +47,7 @@ daemon spawns processes for a list of redirects their output to syslog, and restarts the processes when they exit according to their exit status. -Exponential backoff is applied to restarts. +Exponential backoff is applied to automatic restarts. . .Pp The list of services is defined in a @@ -60,9 +60,9 @@ through a named pipe. The .Xr catsit 8 utility is a wrapper -around the named pipe, +for writing to the named pipe, and its manual page -describes the control command format. +describes the control command syntax. . .Pp The arguments are as follows: @@ -76,10 +76,12 @@ By default the working directory is . .It Fl c Ar control Set the path of the named pipe -used for control. +used for service control. . .It Fl d Do not run as a daemon. +Log to standard error +as well as syslog. . .It Fl f Ar config Set the path of the @@ -92,7 +94,7 @@ Change group to before starting services. If .Fl u -is used, +is set, the default group is the user's group. . .It Fl p Ar pidfile @@ -118,11 +120,12 @@ The default list contains the values of .Dv EX_USAGE , .Dv EX_DATAERR , .Dv EX_NOINPUT , -.Dv EX_OSFILE , +.Dv EX_OSFILE +and .Dv EX_CANTCREAT defined in .Xr sysexits 3 . -The exit statuses 127 and 126 +The exit statuses 126 and 127 are always treated as stop exits. . .It Fl t Ar restart @@ -137,36 +140,42 @@ The default interval is 1 second. 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. .El . .Pp -When the +The .Nm -daemon receives the -.Dv HUP -signal, -the +daemon takes the following actions +in response to signals: +.Bl -tag -width Ds +.It Dv HUP +The .Xr catsit.conf 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 named pipe is closed, -all services are stopped, -and +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 .Nm exits. . +.It Dv INFO +The current status of all services is logged. +.El +. .Sh ENVIRONMENT Services are started with empty environments @@ -196,7 +205,7 @@ The default path of the file. .It Pa /var/run/catsitd.pipe The default path of the named pipe -used for control. +used for service control. .El . .Sh SEE ALSO -- cgit 1.4.1