1INNWATCH.CTL(5) File Formats Manual INNWATCH.CTL(5)
2
6 innwatch.ctl - control Usenet supervision by innwatch
7
9 The file <pathetc in inn.conf>/innwatch.ctl is used to determine what
10 actions are taken during the periodic supervisions by innwatch.
11 The file consists of a series of lines; blank lines and lines beginning
13 with a number sign (``#'') are ignored. All other lines consist of
14 seven fields, each preceded by a delimiting character, for example:
15 :label:state:condition:test:limit:command:reason
17 or
18 @label@state@condition@test@limit@command@reason
19 The delimiter can be any one of several non-alphanumeric characters
21 that does not appear elsewhere in the line; there is no way to quote it
22 to include it in any of the fields. Any of ``!'', ``,'', ``:'', ``@'',
23 ``;'', or ``?'' is a good choice. Each line can have a different
24 delimiter; the first character on each line is the delimiter for that
25 line. White space surrounding delimiters, except before the first, is
26 ignored, and does not form part of the fields; white space within
27 fields is permitted. All delimiters must be present.
28 The first field is a label for this control line. It is used as an
30 internal state indicator and in ctlinnd messages to control the server.
31 If this field is empty, the line number is used.
32 The second field specifies when this control line should be used. It
34 consists of a list of labels and special indicators, separated by
35 whitespace. If the current state matches against any of the labels in
36 this field, this line will be used as described below. The values that
37 may be used are:
38 - This line matches if the current state is the same as the label
40 on this line, or if the current state is ``run'', the initial
41 state. This is also the default state if this field is empty.
42 + This line matches if the current state is ``run''.
44 * This line always matches.
46 label This line matches if the current state is the specified
48 ``label''.
49 -label This line matches if the current state is not the specified
51 ``label''.
52 The third field specifies a shell command that is invoked if this line
54 matches. Do not use any shell filename expansion characters such as
55 ``*'', ``?'', or ``['' (even quoted, they're not likely to work as
56 intended). If the command succeeds, as indicated by its exit status,
57 it is expected to have printed a single integer to standard output.
58 This gives the value of this control line, to be used below. If the
59 command fails, the line is ignored. The command is executed with its
60 current directory set to the news spool articles directory, <patharti‐
61 cles in inn.conf>.
62 The fourth field specifies the operator to use to test the value
64 returned above. It should be one of the two letter numeric test opera‐
65 tors defined in test(1) such as ``eq'', ``lt'' and the like. The lead‐
66 ing dash (``-'') should not be included.
67 The fifth field specifies a constant with which to compare the value
69 using the operator just defined. This is done by invoking the command:
70 test value -operator constant
72 The line is said to ``succeed'' if it returns true.
74 The sixth field specifies what should be done if the line succeeds, and
76 in some cases if it fails. Any of the following words may be used:
77 throttle
79 Causes innwatch to throttle the server if this line succeeds.
80 It also sets the state to the value of the line's label. If the
81 line fails, and the state was previously equal to the label on
82 this line (that is, this line had previously succeeded), then a
83 go command will be sent to the server, and innwatch will return
84 to the ``run'' state. The ``throttle'' is only performed if the
85 current state is ``run'' or a state other than the label of this
86 line, regardless of whether the command succeeds.
87 pause Is identical to ``throttle'' except that the server is paused.
89 shutdown
91 Sends a ``shutdown'' command to the server. It is for emergency
92 use only.
93 flush Sends a ``flush'' command to the server.
95 go Causes innwatch to send a ``go'' command to the server and to
97 set the state to ``run''.
98 exit Causes innwatch to exit.
100 skip The remainder of the control file is skipped for the current
102 pass.
103 The last field specifies the reason that is used in those ctlinnd com‐
105 mands that require one. More strictly, it is part of the reason —
106 innwatch appends some information to it. In order to enable other
107 sites to recognize the state of the local innd server, this field
108 should usually be set to one of several standard values. Use
109 ``No space'' if the server is rejecting articles because of a lack of
110 filesystem resources. Use ``loadav'' if the server is rejecting arti‐
111 cles because of a lack of CPU resources.
112 Once innwatch has taken some action as a consequence of its control
114 line, it skips the rest of the control file for this pass. If the
115 action was to restart the server (that is, issue a ``go'' command),
116 then the next pass will commence almost immediately, so that innwatch
117 can discover any other condition that may mean that the server should
118 be suspended again.
119
121 @@@inndf .@lt@10000@throttle@No space
122 @@@inndf -i .@lt@1000@throttle@No space (inodes)
123 The first line causes the server to be throttled if the free space
125 drops below 10000 units (using whatever units inndf(8) uses), and
126 restarted again when free space increases above the threshold.
127 The second line does the same for inodes.
129 The next three lines act as a group and should appear in the following
131 order. It is easier to explain them, however, if they are described
132 from the last up.
133 !load!load hiload!loadavg!lt!5!go!
135 :hiload:+ load:loadavg:gt:8:throttle:loadav
136 /load/+/loadavg/ge/6/pause/loadav
137 The final line causes the server to be paused if innwatch is in the
139 ``run'' state and the load average rises to, or above, six. The state
140 is set to ``load'' when this happens. The previous line causes the
141 server to be throttled when innwatch is in the ``run'' or ``load''
142 state, and the load average rises above eight. The state is set to
143 ``hiload'' when this happens. Note that innwatch can switch the server
144 from ``paused'' to ``throttled'' if the load average rises from below
145 six to between six and seven, and then to above eight. The first line
146 causes the server to be sent a ``go'' command if innwatch is in the
147 ``load'' or ``hiload'' state, and the load average drops below five.
148 Note that all three lines assume a mythical command loadavg that is
150 assumed to print the current load average as an integer. In more prac‐
151 tical circumstances, a pipe of uptime into awk is more likely to be
152 useful.
153
155 This file must be tailored for each individual site, the sample sup‐
156 plied is truly no more than a sample. The file should be ordered so
157 that the more common problems are tested first.
158 The ``run'' state is not actually identified by the label with that
160 three letter name, and using it will not work as expected.
161 Using an ``unusual'' character for the delimiter such as ``('', ``*'',
163 ``&'', ```'', ``´'', and the like, is likely to lead to obscure and
164 hard to locate bugs.
165
167 Written by <kre@munnari.oz.au> for InterNetNews. This is revision
168 5909, dated 2002-12-03.
169
171 inn.conf(5), innd(8), inndf(8), ctlinnd(8), news.daily(8).
172 INNWATCH.CTL(5)