diff options
Diffstat (limited to 'src/genrc.8')
| -rw-r--r-- | src/genrc.8 | 116 |
1 files changed, 104 insertions, 12 deletions
diff --git a/src/genrc.8 b/src/genrc.8 index 0fdfa54..beb599c 100644 --- a/src/genrc.8 +++ b/src/genrc.8 @@ -1,8 +1,8 @@ .\" This file is part of genrc. -.\" Copyright (C) 2018, 2019 Sergey Poznyakoff. +.\" Copyright (C) 2018-2022 Sergey Poznyakoff. .\" .\" Genrc is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 3, or (at your option) .\" any later version. .\" @@ -10,33 +10,39 @@ .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with genrc. If not, see <http://www.gnu.org/licenses/>. -.TH GENRC 8 "September 13, 2019" "GENRC" "Genrc User Manual" +.TH GENRC 8 "March 26, 2022" "GENRC" "Genrc User Manual" .SH NAME genrc \- generic system initialization script helper .SH SYNOPSIS .nh .na \fBgenrc\fR\ [\fB\-hev\fR]\ [\fB\-F\fR \fIPIDFILE\fR]\ [\fB\-P\fR \fISOURCE\fR]\ [\fB\-c\fR \fICOMMAND\fR]\ [\fB\-g\fR \fIGROUP\fR[,\fIGROUP\fR...]]\ + [\fB\-l\fR \fILIMIT\fR]\ + [\fB\-k\fR \fIMODE\fR]\ [\fB\-p\fR \fIPROGRAM\fR]\ [\fB\-s\fR \fISHELL\fR]\ [\fB\-t\fR \fISECONDS\fR]\ [\fB\-u\fR \fIUSER\fR]\ [\fB\-\-command=\fICOMMAND\fR]\ [\fB\-\-create\-pidfile=\fIPIDFILE\fR]\ [\fB\-\-exec\fR]\ [\fB\-\-group=\fIGROUP\fR[,\fIGROUP\fR...]]\ [\fB\-\-help\fR]\ + [\fB\-\-kill\-mode=\fIMODE\fR]\ + [\fB\-\-log\-facility=\fIFACILITY\fR]\ + [\fB\-\-log\-tag=\fITAG\fR]\ + [\fB\-\-limit=\fILIMIT\fR]\ [\fB\-\-no\-reload\fR]\ [\fB\-\-pid\-from=\fISOURCE\fR]\ [\fB\-\-pidfile=\fIPIDFILE\fR]\ [\fB\-\-program=\fIPROGRAM\fR]\ [\fB\-\-restart\-on\-exit=\fR[\fB!\fR]\fISTATUS\fR[\fB,\fISTATUS\fR...]]\ [\fB\-\-restart\-on\-signal=\fR[\fB!\fR]\fISIG\fR[\fB,\fISIG\fR...]]\ @@ -62,13 +68,13 @@ genrc \- generic system initialization script helper .ad .hy .SH DESCRIPTION .B genrc is a generic helper program for writing system initialization scripts. Depending on the operation mode, it starts, stops, -reconfigures or displays the status of a specific program. +reconfigures or displays current status of a specific program. .PP The operation mode of the program is set by its only mandatory argument. Other program settings are specified via the command line options or environment variables. Most options have a corresponding environment variable. For example, the command line of the program to be run is given by the \fB\-\-command\fR option, @@ -88,26 +94,26 @@ The program operation modes are: .SS start If given this argument, \fBgenrc\fR runs the supplied command. Before, it checks if the program is not already running and refuses to start its second copy if so. .PP It is supposed that the program to be run will detach from the -controlling terminal and will continue running in the background (i.e. it +controlling terminal and continue running in the background (i.e. it is a \fIdaemon\fR, in UNIX sense). If it is not the case, use the \fB\-\-sentinel\fR option. With this option, \fBgenrc\fR will start -the command and become a daemon itself, controlling the execution +the command and become a daemon, controlling the execution of the program. It will exit when the command terminates. So long as the command runs, \fBgenrc\fR will pipe its standard output and error to syslog facility \fBdaemon\fR. The standard output will be logged with the priority \fBinfo\fR and the error with the priority \fBerr\fR. .PP If the \fB\-\-create\-pidfile=\fIFILENAME\fR option is given together with -\fB\-\-sentinel\fR, the PID of the subsidiary command will be stored +\fB\-\-sentinel\fR, the PID of the started command will be stored in \fIFILE\fR. The file will be unlinked after the subsidiary command -terminates. Unless the \fB\-\-pid\-from\fR option is given, +terminates. Unless the \fB\-\-pid\-from\fR option is also given, \fB\-\-pid\-from=FILE:\fIFILENAME\fR will be assumed. .PP In sentinel mode, it is possible to restart the program if it terminates with a specific exit code or on a specific signal. This is controlled by the \fB\-\-restart\-on\-exit\fR and \fB\-\-restart\-on\-signal\fR options. Use this feature to ensure the @@ -134,13 +140,13 @@ the program restarted again. In \fBstatus\fR mode \fBgenrc\fR verifies if the \fICOMMAND\fR is already running and outputs its status on the standard output. To this effect, it uses an abstraction called \fIPID source\fR, which allows it to determine the PID of the program. .PP The default PID source is the Linux \fB/proc\fR filesystem (or, if it -is not available, the output of \fBps -ef\fR), which is scanned for +is not available, the output of \fBps -efw\fR), which is scanned for the name of the program (as given by \fB\-\-program\fR or \fB\-\-command\fR options). .PP The source to use can be supplied with the \fB\-\-pid\-from\fR option (or the \fB\-\-pidfile\R option, which is equivalent to \fB\-\-pid\-from=FILE:\fR). See the section \fBPID SOURCES\fR for a @@ -151,15 +157,26 @@ In the \fBstop\fR mode \fBgenrc\fR stops the command by sending it \fB\-\-signal\-stop\fR option). If the PID source returns multiple PIDs, by default only parent PID is selected. However, \fBgenrc\fR can be instructed to signal all PIDs instead (see the \fBa\fR flag in the description of \fBPROC\fR or \fBPS\fR PID source). .PP After sending the signal, the program will wait for all processes to -terminate. It will report an error if they don't terminate within 5 -seconds. This timeout can be changed using the \fB\-\-timeout\fR +terminate. If they don't terminate within 5 seconds, \fBgenrc\fR will +send the \fBSIGKILL\fR signal and wait another 5 seconds for them to +terminate. The timeout can be changed using the \fB\-\-timeout\fR option. +.PP +The way to send the signals to the program is determined by the +\fB\-k\fR (\fB\-\-kill\-mode\fR) option. If its value is \fBgroup\fR, +both \fBSIGTERM\fR and, if necessary subsequent \fBSIGKILL\fR will be +sent to all processes in the process control group. This is the +default mode if the command is a daemon (i.e., if \fB\-\-sentinel\fR) +is not given). If the value is \fBprocess\fR, the signal will be sent +to the process individually. Finally, if the value is \fBmixed\fR, the +\fBSIGTERM\fR is sent to the main process, while the subsequent +\fBSIGKILL\fR is sent to the control group of the process. .SS restart Restarts the program. It is equivalent to running .B genrc stop immediately followed by .BR "genrc start" . .SS reload @@ -209,12 +226,81 @@ list of groups, the first group becomes the principal, and the rest of them supplementary groups. Each \fIGROUP\fR is either a group name or a numeric group number prefixed with a plus sign. Whatever notation is used, the groups must exist in the system group database. See also the \fB\-\-user\fR option. .TP +\fB\-k\fR, \fB\-\-kill\-mode=\fIMODE\fR +Specifies how to send termination signal to the main +process. \fIMODE\fR is one of \fBgroup\fR (send termination signal to +the process control group), \fBprocess\fR (send it to the process +itself), or \fBmixed\fR (send termination signal to the process, and +send subsequent \fBSIGKILL\fR to the program control group). Refer to +the description of the \fBstop\fR command above for a detailed +discussion of these three modes. +.TP +\fB\-l\fR, \fB\-\-limit=\fILIM\fR +Set resource limit. \fILIM\fR is a resource letter followed by +a value. Resource letters are: +.RS +.TP +.B c +Core file size (KB). +.TP +.B d +Data size (KB). +.TP +.B f +File size (KB). +.TP +.B l +Locked-in-memory address space (KB). +.TP +.B m +Resident set size (KB). +.TP +.B n +Number of open files. +.TP +.B p +Process priority (nice value), -20..20. +.TP +.B s +Stack size (KB). +.TP +.B t +CPU time (seconds). +.TP +.B u +Number of subprocesses. +.TP +.B v +Virtual memory size (KB). +.RE +.TP +.TP +\fB\-\-log\-facility=\fIFACILITY\fR +Selects \fBsyslog\fR facility for use in sentinel mode. Valid arguments are +.BR auth , +.BR authpriv , +.BR cron , +.BR daemon , +.BR ftp , +.BR lpr , +.BR mail , +.BR user , +and +.BR local0 +through +.BR local7 . +The default is +.BR daemon . +.TP +\fB\-\-log\-tag=\fITAG\fR +Sets \fBsyslog\fR tag for use in sentinel mode. +.TP \fB\-\-no\-reload\fR Makes \fBreload\fR equivalent to \fBrestart\fR. .TP \fB\-p\fR, \fB\-\-program=\fIPROGRAM\fR Name of the program to run. .TP @@ -247,12 +333,15 @@ restart the program unless it terminates on one of the listed signals. \fB\-\-sentinel\fR \fIPROGRAM\fR runs in foreground; disconnect from the controlling terminal, start it and run in background until it terminates. The program's stdout and stderr are sent to the syslog facility \fBdaemon\fR, priorities \fBinfo\fR and \fBerr\fR, correspondingly. +The default facility and syslog tag can be changed using the +\fB\-\-log\-facility\fR and \fB\-\-log-tag\fR options. + See the options \fB\-\-restart\-on\-exit\fR and \fB\-\-restart\-on\-signal\fR for details on how to restart the program. .TP \fB\-s\fR, \fB\-\-shell=\fISHELL\fR In sentinel mode, use \fISHELL\fR to run the command, instead of the @@ -372,20 +461,23 @@ Influential environment variables and corresponding options: \fBGENRC_PROGRAM=\fINAME\fR \fB\-\-program=\fINAME\fR \fBGENRC_PID_FROM=\fISOURCE\fR \fB\-\-pid\-from=\fISOURCE\fR \fBGENRC_TIMEOUT=\fISECONDS\fR \fB\-\-timeout=\fISECONDS\fR \fBGENRC_SENTINEL=1\fR \fB\-\-sentinel\fR \fBGENRC_CREATE_PIDFILE=\fINAME\fR \fB\-\-create\-pidfile=\fINAME\fR \fBGENRC_USER=\fINAME\fR \fB\-\-user=\fINAME\fR - \fBGENRC_GROUP=\fIGROUPS\fR \fB\-\-group=\fIGROUPS\fR + \fBGENRC_GROUP=\fIGROUPS\fR \fB\-\-group=\fIGROUPS\fR + \fBGENRC_KILL_MODE=\fIMODE\fR \fB\-\-kill\-mode=\fIMODE\fR + \fBGENRC_LOG_FACILITY=\fIF\fR \fB\-\-log\-facility=\fIF\fR + \fBGENRC_LOG_TAG=\fISTR\fR \fB\-\-log\-tag=\fISTR\fR .fi .SH AUTHORS Sergey Poznyakoff .SH "BUG REPORTS" Report bugs to <gray@gnu.org>. .SH COPYRIGHT -Copyright \(co 2018, 2019 Sergey Poznyakoff +Copyright \(co 2018 -- 2022 Sergey Poznyakoff .br .na License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> .br .ad This is free software: you are free to change and redistribute it. |