4 innwatch.ctl \- control Usenet supervision by innwatch
7 .I <pathetc in inn.conf>/innwatch.ctl
8 is used to determine what actions are taken during the periodic
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:
19 :label:state:condition:test:limit:command:reason
23 @label@state@condition@test@limit@command@reason
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
36 All delimiters must be present.
38 The first field is a label for this control line.
39 It is used as an internal state indicator and in
41 messages to control the server.
42 If this field is empty, the line number is used.
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:
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.
56 This line matches if the current state is ``run''.
58 This line always matches.
60 This line matches if the current state is the specified ``label''.
62 This line matches if the current state is not the specified ``label''.
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
73 .IR <patharticles\ in\ inn.conf> .
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
78 such as ``eq'', ``lt'' and the like.
79 The leading dash (``\-'') should not be included.
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:
86 test value -operator constant
89 The line is said to ``succeed'' if it returns true.
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:
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),
103 command will be sent to the server, and
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
110 Is identical to ``throttle'' except that the server is paused.
112 Sends a ``shutdown'' command to the server.
113 It is for emergency use only.
115 Sends a ``flush'' command to the server.
119 to send a ``go'' command to the server and to set the state to ``run''.
126 The remainder of the control file is skipped for the current pass.
128 The last field specifies the reason that is used in those
130 commands that require one.
131 More strictly, it is part of the reason \(em
133 appends some information to it.
134 In order to enable other sites to recognize the state of the local
136 server, this field should usually be set to one of several standard
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
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
150 can discover any other condition that may mean that the server should
155 @@@inndf .@lt@10000@throttle@No space
156 @@@inndf -i .@lt@1000@throttle@No space (inodes)
160 The first line causes the server to be throttled if the free space drops
162 (using whatever units
164 uses), and restarted again when free space increases above the threshold.
166 The second line does the same for inodes.
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.
174 !load!load hiload!loadavg!lt!5!go!
175 :hiload:+ load:loadavg:gt:8:throttle:loadav
176 /load/+/loadavg/ge/6/pause/loadav
180 The final line causes the server to be paused if
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
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.
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
194 is in the ``load'' or ``hiload'' state, and the load average drops below five.
196 Note that all three lines assume a mythical command
198 that is assumed to print the current load average as an integer.
199 In more practical circumstances, a pipe of
203 is more likely to be useful.
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.
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.
212 Using an ``unusual'' character for the delimiter such as ``('', ``*'',
213 ``&'', ``\(ga'', ``\(aa'', and the like, is likely to lead to obscure and
216 Written by <kre@munnari.oz.au> for InterNetNews.
218 This is revision \\$3, dated \\$4.
220 .R$ $Id: innwatch.ctl.5 5909 2002-12-03 05:17:18Z vinocur $