root/docs/config/modules/noit.module.http.xml

Revision 3d84df203288f50b595551aef51beb98b81b939d, 13.6 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 2 years ago)

fix XML in docs

  • Property mode set to 100644
Line 
1 <?xml version="1.0"?>
2 <section>
3   <title>http</title>
4   <para>The http module performs GET requests over either HTTP or HTTPS and checks the return code and optionally the body.</para>
5   <variablelist>
6     <varlistentry>
7       <term>loader</term>
8       <listitem>
9         <para>lua</para>
10       </listitem>
11     </varlistentry>
12     <varlistentry>
13       <term>object</term>
14       <listitem>
15         <para>noit.module.http</para>
16       </listitem>
17     </varlistentry>
18   </variablelist>
19   <section>
20     <title>Module Configuration</title>
21   </section>
22   <section>
23     <title>Check Configuration</title>
24     <variablelist>
25       <varlistentry>
26         <term>url</term>
27         <listitem>
28           <variablelist>
29             <varlistentry>
30               <term>required</term>
31               <listitem>
32                 <para>required</para>
33               </listitem>
34             </varlistentry>
35             <varlistentry>
36               <term>allowed</term>
37               <listitem>
38                 <para>.+</para>
39               </listitem>
40             </varlistentry>
41           </variablelist>
42           <para>The URL including schema and hostname (as you would type into a browser's location bar).</para>
43         </listitem>
44       </varlistentry>
45     </variablelist>
46     <variablelist>
47       <varlistentry>
48         <term>header_(\S+)</term>
49         <listitem>
50           <variablelist>
51             <varlistentry>
52               <term>required</term>
53               <listitem>
54                 <para>optional</para>
55               </listitem>
56             </varlistentry>
57             <varlistentry>
58               <term>allowed</term>
59               <listitem>
60                 <para>.+</para>
61               </listitem>
62             </varlistentry>
63           </variablelist>
64           <para>Allows the setting of arbitrary HTTP headers in the request.</para>
65         </listitem>
66       </varlistentry>
67     </variablelist>
68     <variablelist>
69       <varlistentry>
70         <term>method</term>
71         <listitem>
72           <variablelist>
73             <varlistentry>
74               <term>required</term>
75               <listitem>
76                 <para>optional</para>
77               </listitem>
78             </varlistentry>
79             <varlistentry>
80               <term>default</term>
81               <listitem>
82                 <para>GET</para>
83               </listitem>
84             </varlistentry>
85             <varlistentry>
86               <term>allowed</term>
87               <listitem>
88                 <para>\S+</para>
89               </listitem>
90             </varlistentry>
91           </variablelist>
92           <para>The HTTP method to use.</para>
93         </listitem>
94       </varlistentry>
95     </variablelist>
96     <variablelist>
97       <varlistentry>
98         <term>payload</term>
99         <listitem>
100           <variablelist>
101             <varlistentry>
102               <term>required</term>
103               <listitem>
104                 <para>optional</para>
105               </listitem>
106             </varlistentry>
107             <varlistentry>
108               <term>allowed</term>
109               <listitem>
110                 <para>.*</para>
111               </listitem>
112             </varlistentry>
113           </variablelist>
114           <para>The information transferred as the payload of an HTTP request.</para>
115         </listitem>
116       </varlistentry>
117     </variablelist>
118     <variablelist>
119       <varlistentry>
120         <term>auth_method</term>
121         <listitem>
122           <variablelist>
123             <varlistentry>
124               <term>required</term>
125               <listitem>
126                 <para>optional</para>
127               </listitem>
128             </varlistentry>
129             <varlistentry>
130               <term>allowed</term>
131               <listitem>
132                 <para>^(?:Basic|Digest|Auto)$</para>
133               </listitem>
134             </varlistentry>
135           </variablelist>
136           <para>HTTP Authentication method to use.</para>
137         </listitem>
138       </varlistentry>
139     </variablelist>
140     <variablelist>
141       <varlistentry>
142         <term>auth_user</term>
143         <listitem>
144           <variablelist>
145             <varlistentry>
146               <term>required</term>
147               <listitem>
148                 <para>optional</para>
149               </listitem>
150             </varlistentry>
151             <varlistentry>
152               <term>allowed</term>
153               <listitem>
154                 <para>[^:]*</para>
155               </listitem>
156             </varlistentry>
157           </variablelist>
158           <para>The user to authenticate as.</para>
159         </listitem>
160       </varlistentry>
161     </variablelist>
162     <variablelist>
163       <varlistentry>
164         <term>auth_password</term>
165         <listitem>
166           <variablelist>
167             <varlistentry>
168               <term>required</term>
169               <listitem>
170                 <para>optional</para>
171               </listitem>
172             </varlistentry>
173             <varlistentry>
174               <term>allowed</term>
175               <listitem>
176                 <para>.*</para>
177               </listitem>
178             </varlistentry>
179           </variablelist>
180           <para>The password to use during authentication.</para>
181         </listitem>
182       </varlistentry>
183     </variablelist>
184     <variablelist>
185       <varlistentry>
186         <term>ca_chain</term>
187         <listitem>
188           <variablelist>
189             <varlistentry>
190               <term>required</term>
191               <listitem>
192                 <para>optional</para>
193               </listitem>
194             </varlistentry>
195             <varlistentry>
196               <term>allowed</term>
197               <listitem>
198                 <para>.+</para>
199               </listitem>
200             </varlistentry>
201           </variablelist>
202           <para>A path to a file containing all the certificate authorities that should be loaded to validate the remote certificate (for SSL checks).</para>
203         </listitem>
204       </varlistentry>
205     </variablelist>
206     <variablelist>
207       <varlistentry>
208         <term>certificate_file</term>
209         <listitem>
210           <variablelist>
211             <varlistentry>
212               <term>required</term>
213               <listitem>
214                 <para>optional</para>
215               </listitem>
216             </varlistentry>
217             <varlistentry>
218               <term>allowed</term>
219               <listitem>
220                 <para>.+</para>
221               </listitem>
222             </varlistentry>
223           </variablelist>
224           <para>A path to a file containing the client certificate that will be presented to the remote server (for SSL checks).</para>
225         </listitem>
226       </varlistentry>
227     </variablelist>
228     <variablelist>
229       <varlistentry>
230         <term>key_file</term>
231         <listitem>
232           <variablelist>
233             <varlistentry>
234               <term>required</term>
235               <listitem>
236                 <para>optional</para>
237               </listitem>
238             </varlistentry>
239             <varlistentry>
240               <term>allowed</term>
241               <listitem>
242                 <para>.+</para>
243               </listitem>
244             </varlistentry>
245           </variablelist>
246           <para>A path to a file containing key to be used in conjunction with the cilent certificate (for SSL checks).</para>
247         </listitem>
248       </varlistentry>
249     </variablelist>
250     <variablelist>
251       <varlistentry>
252         <term>ciphers</term>
253         <listitem>
254           <variablelist>
255             <varlistentry>
256               <term>required</term>
257               <listitem>
258                 <para>optional</para>
259               </listitem>
260             </varlistentry>
261             <varlistentry>
262               <term>allowed</term>
263               <listitem>
264                 <para>.+</para>
265               </listitem>
266             </varlistentry>
267           </variablelist>
268           <para>A list of ciphers to be used in the SSL protocol (for SSL checks).</para>
269         </listitem>
270       </varlistentry>
271     </variablelist>
272     <variablelist>
273       <varlistentry>
274         <term>code</term>
275         <listitem>
276           <variablelist>
277             <varlistentry>
278               <term>required</term>
279               <listitem>
280                 <para>optional</para>
281               </listitem>
282             </varlistentry>
283             <varlistentry>
284               <term>default</term>
285               <listitem>
286                 <para>^200$</para>
287               </listitem>
288             </varlistentry>
289             <varlistentry>
290               <term>allowed</term>
291               <listitem>
292                 <para>.+</para>
293               </listitem>
294             </varlistentry>
295           </variablelist>
296           <para>The HTTP code that is expected.  If the code received does not match this regular expression, the check is marked as "bad."</para>
297         </listitem>
298       </varlistentry>
299     </variablelist>
300     <variablelist>
301       <varlistentry>
302         <term>redirects</term>
303         <listitem>
304           <variablelist>
305             <varlistentry>
306               <term>required</term>
307               <listitem>
308                 <para>optional</para>
309               </listitem>
310             </varlistentry>
311             <varlistentry>
312               <term>default</term>
313               <listitem>
314                 <para>0</para>
315               </listitem>
316             </varlistentry>
317             <varlistentry>
318               <term>allowed</term>
319               <listitem>
320                 <para>\d+</para>
321               </listitem>
322             </varlistentry>
323           </variablelist>
324           <para>The maximum number of Location header redirects to follow.</para>
325         </listitem>
326       </varlistentry>
327     </variablelist>
328     <variablelist>
329       <varlistentry>
330         <term>body</term>
331         <listitem>
332           <variablelist>
333             <varlistentry>
334               <term>required</term>
335               <listitem>
336                 <para>optional</para>
337               </listitem>
338             </varlistentry>
339             <varlistentry>
340               <term>allowed</term>
341               <listitem>
342                 <para>.+</para>
343               </listitem>
344             </varlistentry>
345           </variablelist>
346           <para>This regular expression is matched against the body of the response.  If a match is not found, the check will be marked as "bad."</para>
347         </listitem>
348       </varlistentry>
349     </variablelist>
350     <variablelist>
351       <varlistentry>
352         <term>extract</term>
353         <listitem>
354           <variablelist>
355             <varlistentry>
356               <term>required</term>
357               <listitem>
358                 <para>optional</para>
359               </listitem>
360             </varlistentry>
361             <varlistentry>
362               <term>allowed</term>
363               <listitem>
364                 <para>.+</para>
365               </listitem>
366             </varlistentry>
367           </variablelist>
368           <para>This regular expression is matched against the body of the response globally.  The first capturing match is the key and the second capturing match is the value.  Each key/value extracted is registered as a metric for the check.</para>
369         </listitem>
370       </varlistentry>
371     </variablelist>
372     <variablelist>
373       <varlistentry>
374         <term>pcre_match_limit</term>
375         <listitem>
376           <variablelist>
377             <varlistentry>
378               <term>required</term>
379               <listitem>
380                 <para>optional</para>
381               </listitem>
382             </varlistentry>
383             <varlistentry>
384               <term>default</term>
385               <listitem>
386                 <para>10000</para>
387               </listitem>
388             </varlistentry>
389             <varlistentry>
390               <term>allowed</term>
391               <listitem>
392                 <para>\d+</para>
393               </listitem>
394             </varlistentry>
395           </variablelist>
396           <para>This sets the PCRE internal match limit (see pcreapi documentation).</para>
397         </listitem>
398       </varlistentry>
399     </variablelist>
400     <variablelist>
401       <varlistentry>
402         <term>include_body</term>
403         <listitem>
404           <variablelist>
405             <varlistentry>
406               <term>required</term>
407               <listitem>
408                 <para>optional</para>
409               </listitem>
410             </varlistentry>
411             <varlistentry>
412               <term>default</term>
413               <listitem>
414                 <para>false</para>
415               </listitem>
416             </varlistentry>
417             <varlistentry>
418               <term>allowed</term>
419               <listitem>
420                 <para>^(?:true|false|on|off)$</para>
421               </listitem>
422             </varlistentry>
423           </variablelist>
424           <para>Include whole response body as a metric with the key 'body'.</para>
425         </listitem>
426       </varlistentry>
427     </variablelist>
428   </section>
429   <example>
430     <title>Checking an HTTP and HTTPS URL.</title>
431     <para>This example checks the OmniTI Labs website over both HTTP and HTTPS.</para>
432     <programlisting>
433       &lt;noit&gt;
434         &lt;modules&gt;
435           &lt;loader image="lua" name="lua"&gt;
436             &lt;config&gt;&lt;directory&gt;/opt/reconnoiter/libexec/modules-lua/?.lua&lt;/directory&gt;&lt;/config&gt;
437           &lt;/loader&gt;
438           &lt;module loader="lua" name="http" object="noit.module.http" /&gt;
439         &lt;/modules&gt;
440         &lt;checks&gt;
441           &lt;labs target="8.8.38.5" module="http"&gt;
442             &lt;check uuid="fe3e984c-7895-11dd-90c1-c74c31b431f0" name="http"&gt;
443               &lt;config&gt;&lt;url&gt;http://labs.omniti.com/&lt;/url&gt;&lt;/config&gt;
444             &lt;/check&gt;
445             &lt;check uuid="1ecd887a-7896-11dd-b28d-0b4216877f83" name="https"&gt;
446               &lt;config&gt;&lt;url&gt;https://labs.omniti.com/&lt;/url&gt;&lt;/config&gt;
447             &lt;/check&gt;
448           &lt;/labs&gt;
449         &lt;/checks&gt;
450       &lt;/noit&gt;
451     </programlisting>
452   </example>
453 </section>
Note: See TracBrowser for help on using the browser.