chiark / gitweb /
Commit 2.4.5-5 as unpacked
[inn-innduct.git] / doc / man / innwatch.ctl.5
1 .\" $Revision: 5909 $
4 innwatch.ctl \- control Usenet supervision by innwatch
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.
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.
216 Written by <> 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).