doc/man/innwatch.ctl.5

   1 .\" $Revision: 5909 $
   2 .TH INNWATCH.CTL 5
   3 .SH NAME
   4 innwatch.ctl \- control Usenet supervision by innwatch
   5 .SH DESCRIPTION
   6 The file
   7 .I <pathetc in inn.conf>/innwatch.ctl
   8 is used to determine what actions are taken during the periodic
   9 supervisions by
  10 .IR innwatch .
  11 .PP
  12 The file consists of a series of lines; blank lines and lines beginning
  13 with a number sign (``#'') are ignored.
  14 All other lines consist of seven fields, each preceded by a delimiting
  15 character, for example:
  16 .sp 1
  17 .nf
  18 .RS
  19 :label:state:condition:test:limit:command:reason
  20 .RE
  21 or
  22 .RS
  23 @label@state@condition@test@limit@command@reason
  24 .RE
  25 .fi
  26 .PP
  27 The delimiter can be any one of several non-alphanumeric characters that does
  28 not appear elsewhere in the line; there is no way to quote it to
  29 include it in any of the fields.
  30 Any of ``!'', ``,'', ``:'', ``@'', ``;'', or ``?'' is a good choice.
  31 Each line can have a different delimiter; the first character on each line
  32 is the delimiter for that line.
  33 White space surrounding delimiters, except before the first, is ignored,
  34 and does not form part of the fields; white space within fields is
  35 permitted.
  36 All delimiters must be present.
  37 .PP
  38 The first field is a label for this control line.
  39 It is used as an internal state indicator and in
  40 .I ctlinnd
  41 messages to control the server.
  42 If this field is empty, the line number is used.
  43 .PP
  44 The second field specifies when this control line should be used.
  45 It consists of a list of labels
  46 and special indicators,
  47 separated by whitespace.
  48 If the current state matches against any of the labels in this field,
  49 this line will be used as described below.
  50 The values that may be used are:
  51 .IP "\-"
  52 This line matches if the current state is the same as the label on
  53 this line, or if the current state is ``run'', the initial state.
  54 This is also the default state if this field is empty.
  55 .IP "+"
  56 This line matches if the current state is ``run''.
  57 .IP "*"
  58 This line always matches.
  59 .IP "label"
  60 This line matches if the current state is the specified ``label''.
  61 .IP "\-label"
  62 This line matches if the current state is not the specified ``label''.
  63 .PP
  64 The third field specifies a shell command that is invoked if this line matches.
  65 Do not use any shell filename expansion characters such as ``*'', ``?'',
  66 or ``['' (even quoted, they're not likely to work as intended).
  67 If the command succeeds, as indicated by its exit status, it is expected
  68 to have printed a single integer to standard output.
  69 This gives the value of this control line, to be used below.
  70 If the command fails, the line is ignored.
  71 The command is executed with its current directory set to the news spool
  72 articles directory,
  73 .IR <patharticles\ in\ inn.conf> .
  74 .PP
  75 The fourth field specifies the operator to use to test the value returned above.
  76 It should be one of the two letter numeric test operators defined in
  77 .IR test (1)
  78 such as ``eq'', ``lt'' and the like.
  79 The leading dash (``\-'') should not be included.
  80 .PP
  81 The fifth field specifies a constant with which to compare the value using
  82 the operator just defined.
  83 This is done by invoking the command:
  84 .sp 1
  85 .RS
  86 test value -operator constant
  87 .RE
  88 .sp 1
  89 The line is said to ``succeed'' if it returns true.
  90 .PP
  91 The sixth field specifies what should be done if the line succeeds,
  92 and in some cases if it fails.
  93 Any of the following words may be used:
  94 .IP throttle
  95 Causes
  96 .I innwatch
  97 to throttle the server if this line succeeds.
  98 It also sets the state to the value of the line's label.
  99 If the line fails, and the state was previously equal to
 100 the label on this line (that is, this line had previously succeeded),
 101 then a
 102 .I go
 103 command will be sent to the server, and
 104 .I innwatch
 105 will return to the ``run'' state.
 106 The ``throttle'' is only performed if the current state is ``run'' or a
 107 state other than the label of this line, regardless of whether the command
 108 succeeds.
 109 .IP pause
 110 Is identical to ``throttle'' except that the server is paused.
 111 .IP shutdown
 112 Sends a ``shutdown'' command to the server.
 113 It is for emergency use only.
 114 .IP flush
 115 Sends a ``flush'' command to the server.
 116 .IP go
 117 Causes
 118 .I innwatch
 119 to send a ``go'' command to the server and to set the state to ``run''.
 120 .IP exit
 121 Causes
 122 .I innwatch
 123 to exit.
 124 .PP
 125 .IP skip
 126 The remainder of the control file is skipped for the current pass.
 127 .PP
 128 The last field specifies the reason that is used in those
 129 .I ctlinnd
 130 commands that require one.
 131 More strictly, it is part of the reason \(em
 132 .I innwatch
 133 appends some information to it.
 134 In order to enable other sites to recognize the state of the local
 135 .I innd
 136 server, this field should usually be set to one of several standard
 137 values.
 138 Use ``No\ space'' if the server is rejecting articles because of a lack
 139 of filesystem resources.
 140 Use ``loadav'' if the server is rejecting articles because of a lack
 141 of CPU resources.
 142 .PP
 143 Once
 144 .I innwatch
 145 has taken some action as a consequence of its control line, it skips the
 146 rest of the control file for this pass.
 147 If the action was to restart the server (that is, issue a ``go'' command),
 148 then the next pass will commence almost immediately, so that
 149 .I innwatch
 150 can discover any other condition that may mean that the server should
 151 be suspended again.
 152 .SH EXAMPLES
 153 .RS
 154 .nf
 155 @@@inndf .@lt@10000@throttle@No space
 156 @@@inndf -i .@lt@1000@throttle@No space (inodes)
 157 .fi
 158 .RE
 159 .PP
 160 The first line causes the server to be throttled if the free space drops
 161 below 10000 units
 162 (using whatever units
 163 .IR inndf (8)
 164 uses), and restarted again when free space increases above the threshold.
 165 .PP
 166 The second line does the same for inodes.
 167 .PP
 168 The next three lines act as a group and should
 169 appear in the following order.
 170 It is easier to explain them, however, if they are described from the last up.
 171 .PP
 172 .RS
 173 .nf
 174 !load!load hiload!loadavg!lt!5!go!
 175 :hiload:+ load:loadavg:gt:8:throttle:loadav
 176 /load/+/loadavg/ge/6/pause/loadav
 177 .fi
 178 .RE
 179 .PP
 180 The final line causes the server to be paused if
 181 .I innwatch
 182 is in the ``run'' state and the load average rises to, or above, six.
 183 The state is set to ``load'' when this happens.
 184 The previous line causes the server to be throttled when
 185 .I innwatch
 186 is in the ``run'' or ``load'' state, and the load average rises above eight.
 187 The state is set to ``hiload'' when this happens.
 188 Note that
 189 .I innwatch
 190 can switch the server from ``paused'' to ``throttled'' if the load average
 191 rises from below six to between six and seven, and then to above eight.
 192 The first line causes the server to be sent a ``go'' command if
 193 .I innwatch
 194 is in the ``load'' or ``hiload'' state, and the load average drops below five.
 195 .PP
 196 Note that all three lines assume a mythical command
 197 .I loadavg
 198 that is assumed to print the current load average as an integer.
 199 In more practical circumstances, a pipe of
 200 .I uptime
 201 into
 202 .I awk
 203 is more likely to be useful.
 204 .SH BUGS
 205 This file must be tailored for each individual site, the sample supplied
 206 is truly no more than a sample.
 207 The file should be ordered so that the more common problems are tested first.
 208 .PP
 209 The ``run'' state is not actually identified by the label with that three
 210 letter name, and using it will not work as expected.
 211 .PP
 212 Using an ``unusual'' character for the delimiter such as ``('', ``*'',
 213 ``&'', ``\(ga'', ``\(aa'', and the like, is likely to lead to obscure and
 214 hard to locate bugs.
 215 .SH HISTORY
 216 Written by <kre@munnari.oz.au> for InterNetNews.
 217 .de R$
 218 This is revision \\$3, dated \\$4.
 219 ..
 220 .R$ $Id: innwatch.ctl.5 5909 2002-12-03 05:17:18Z vinocur $
 221 .SH "SEE ALSO"
 222 inn.conf(5),
 223 innd(8),
 224 inndf(8),
 225 ctlinnd(8),
 226 news.daily(8).