root/docs/config/noitd.xml

Revision 23dea7e00df87480acb58bb3398283c2bb227949, 13.8 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 3 years ago)

pull docs into master

  • Property mode set to 100644
Line 
1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4 [
5   <!ENTITY % magic.fixup SYSTEM "http://labs.omniti.com/docbook/ent">
6   %magic.fixup;
7 ]>
8 <chapter id="config.noitd">
9   <title>noitd</title>
10   <example>
11   <title>Basic noitd configuration struture</title>
12   <programlisting><![CDATA[
13   <noit>
14     <eventer/>
15     <modules>
16       <...>
17         <module />
18       </...>
19     </modules>
20     <logs>
21       <...>
22         <log>
23           <outlet />
24           <outlet />
25         </log>
26       </...>
27     </logs>
28     <listeners>
29       <...>
30         <listener/>
31         <listener>
32           <config />
33           <sslconfig />
34         <listener>
35       </...>
36     </listeners>
37     <checks>
38       <...>
39         <check uuid="xxx" />
40       </...>
41     </checks>
42   </noit>
43 ]]></programlisting>
44 </example>
45
46 <section id="config.noitd.implicitinheritance">
47 <title>Implicit Inheritance</title>
48 <para>
49 Unless otherwise specified, elements and attributes are inherited from
50 all ancestors.  As is typical with inheritance, the youngest/deepest
51 value overrides values of ancestors.  If the value requested is a set
52 of key/value pairs, the top-most ancestor is queried, then its
53 child is queried, merging values, replacing conflicts and so on until
54 the youngest/deepest node is reached.
55 </para>
56
57 <example>
58 <title>Simple implicit inheritance configuration example</title>
59 <programlisting><![CDATA[
60       <a foo="bar">
61         <config>
62           <key1>val a 1</key1>
63           <key2>val a 2</key2>
64         </config>
65         <b quux="baz">
66           <config>
67             <key1>val b 1</key1>
68             <key3>val b 3</key3>
69           </config>
70           <c foo="meme" />
71         </b>
72       </a>
73 ]]></programlisting>
74 </example>
75
76 <para>
77 When looking at the "foo" attribute we see the following values at nodes:
78 </para>
79 <variablelist>
80   <varlistentry><term>a</term><listitem><para>bar</para></listitem></varlistentry>
81   <varlistentry><term>b</term><listitem><para>bar</para></listitem></varlistentry>
82   <varlistentry><term>c</term><listitem><para>meme</para></listitem></varlistentry>
83 </variablelist>
84
85 <para>
86 When looking at the "quux" attribute we see the following values at nodes:
87 </para>
88 <variablelist>
89   <varlistentry><term>a</term><listitem><para>(none)</para></listitem></varlistentry>
90   <varlistentry><term>b</term><listitem><para>baz</para></listitem></varlistentry>
91   <varlistentry><term>c</term><listitem><para>baz</para></listitem></varlistentry>
92 </variablelist>
93
94 <para>
95 When looking at the key/value set "config" we see the following values at nodes:
96 </para>
97 <variablelist>
98   <varlistentry><term>a</term><listitem><para>{ key1: "val a 1", key2: "val a 2" }</para></listitem></varlistentry>
99   <varlistentry><term>b</term><listitem><para>{ key1: "val b 1", key2: "val a 2", key3: "val b 3" }</para></listitem></varlistentry>
100   <varlistentry><term>c</term><listitem><para>{ key1: "val b 1", key2: "val a 2", key3: "val b 3" } (same as b)</para></listitem></varlistentry>
101 </variablelist>
102
103 <para>
104 This inheritance model allows for "non-repetitive" configuration
105 approaches: "express yourself once and reuse."
106 </para>
107 </section>
108
109 <section id="config.noitd.explicitinheritance">
110 <title>Explicit Inheritance</title>
111
112 <para>
113 Sometimes it is useful to define a configuration key/value set
114 for reuse, but the strict parent-child inheritance model is awkward.
115 Under these circumstances, the explicit inheritance often solves the
116 issue at hand.  With explicit inheritance, a configuration can inherit
117 from another named node elsewhere in the configuration.
118 </para>
119 <para>
120 The &lt;config /&gt; stanzas can be identified, as is typical in XML, with
121 the "id" attribute: &lt;config id="sample" /&gt;.  Additionally, any config
122 may explicitly specify that it inherits from a named config by
123 specifying the "inherit" attribute.
124 </para>
125 <para>
126 Any &lt;config /&gt;, A, which has the "inherit" attribute will first
127 inherit from its most direct parent, then supplement/replace those
128 key/values with the configuration whose "id" attribute matches the
129 "inherit" attribute of A, and finally supplement/replace those
130 key/values with key/values directly beneath A.  The entire tree is
131 searched for a node whose "id" matches A's "inherit" attribute.
132 </para>
133
134 <example>
135 <title>Simple explicity inheritance configuration example</title>
136 <programlisting><![CDATA[
137   <config name="A">
138     <key1>a</key1>
139     <key2>b</key2>
140     <key3>c</key3>
141     <config name="C" inherit="bob">
142       <key1>AAA</key1>
143       <key4>DDD</key4>
144     </config>
145   </config>
146   <x>
147     <y>
148       <z>
149         <config name="B" id="bob">
150           <key2>bobB</key2>
151           <key5>bobE</key5>
152         </config>
153       </z>
154     </y>
155   </x>
156 ]]></programlisting>
157 </example>
158
159 <para>The config named "A" contains:</para>
160 <variablelist spacing="compact">
161   <varlistentry><term>key1</term><listitem><para>a</para></listitem></varlistentry>
162   <varlistentry><term>key2</term><listitem><para>b</para></listitem></varlistentry>
163   <varlistentry><term>key3</term><listitem><para>c</para></listitem></varlistentry>
164 </variablelist>
165
166 <para>The config named "C" contains:</para>
167 <variablelist>
168   <varlistentry><term>key1</term><listitem><para>AAA</para></listitem></varlistentry>
169   <varlistentry><term>key2</term><listitem><para>bobB</para></listitem></varlistentry>
170   <varlistentry><term>key3</term><listitem><para>c</para></listitem></varlistentry>
171   <varlistentry><term>key4</term><listitem><para>DDD</para></listitem></varlistentry>
172   <varlistentry><term>key5</term><listitem><para>bobE</para></listitem></varlistentry>
173 </variablelist>
174
175 <para>
176 It should be noted hat all config's include the one named "B" above
177 follows this same inheritance model.
178 </para>
179 </section>
180
181 <section id="config.noitd.section.eventer">
182   <title>The &lt;eventer&gt; section</title>
183
184 <para>
185 This section provides configuration directives to the eventing
186 subsystem.  Think of the eventer as the engine that drives all I/O,
187 jobs, and timed events.  To choose the eventer, the "implementation"
188 attribute is used in the eventer node.  For example, to select the
189 kqueue eventer (for Mac OS X or modern BSDs):
190 </para>
191
192 <programlisting><![CDATA[
193   <eventer implementation="kqueue" />
194 ]]></programlisting>
195
196 <para>
197 The following eventer implementations exist: kqueue (Mac/BSD), epoll (Linux), ports (Solaris 10+).
198 </para>
199 </section>
200
201 <section id="config.noitd.section.logs">
202   <title>The &lt;logs&gt; section</title>
203
204 <para>
205 The logs section contains &lt;log&gt; elements at arbitrary depths.  A log
206 requires several attributes to be useful:
207 </para>
208
209 <variablelist>
210   <varlistentry><term>name</term><listitem><para>
211    "name" this must me unique.  Several names have meaning within the
212    product.  If you match that name, you control how that information
213    is logged.
214   </para></listitem></varlistentry>
215
216   <varlistentry><term>type</term><listitem><para>
217    "type" this specified ths underlying log writing implementation.
218    Valid options are "file" (the default if unspecified), "jlog" which
219    is the a binary 'auto-rotating', consumable, multi-subscriber log
220    format.
221   </para></listitem></varlistentry>
222
223   <varlistentry><term>path</term><listitem><para>
224    "path" the path to the log (interpreted by the "type"
225    implementation).
226   </para></listitem></varlistentry>
227
228   <varlistentry><term>debug</term><listitem><para>
229    "debug" (boolean: &lt;true|false&gt;, default false) that dictates
230    whether or not the file:line number of the callee will be included
231    in the log output.  This only applies loggers that have write
232    operations (like files and jlogs).
233   </para></listitem></varlistentry>
234
235   <varlistentry><term>disabled</term><listitem><para>
236    "disabled" (boolean: &lt;true|false&gt;, default false) that dictates
237    whether the log implmenation will actually write anything.  If set
238    to true, the log will be silences and will not propagate input to
239    any attached outlets.
240   </para></listitem></varlistentry>
241
242   <varlistentry><term>timestamps</term><listitem><para>
243    "debug" (boolean: &lt;true|false&gt;, default false) that dictates
244    whether or not a microsecond granular time will be included
245    in the log output.  This only applies loggers that have write
246    operations (like files and jlogs).
247   </para></listitem></varlistentry>
248
249   <varlistentry><term>rotate_seconds</term><listitem><para>
250    "rotate_seconds" (integer: default unset, minimum 600) that specifies
251    how many seconds of data the given log file should contain.  Every
252    "rotate_seconds" seconds (aligned with UNIX epoch), the log will be
253    rotated to a file of the same name with the current UNIX timestamp
254    dot-appended.  This can be used in combination with "rotate_bytes"
255    for rather interesting results.
256   </para></listitem></varlistentry>
257
258   <varlistentry><term>rotate_bytes</term><listitem><para>
259    "rotate_bytes" (integer: default unset, minimum 102400) that specifies
260    the maximum number of bytes the file may contain before rotation is
261    applied.  This is not enforced after each write, but instead
262    the file size is monitored "frequently" and rotation applied.  This
263    can mean that the file can grow slightly larger than the specified
264    amount.  This can be used in combination with "rotate_seconds" for
265    rather interesting results.
266   </para></listitem></varlistentry>
267 </variablelist>
268 <para>
269 Within a &lt;log&gt; element, zero, one or many &lt;outlet&gt; elements may be
270 present.  The outlet element must contain a "name" attribute (this
271 attribute is not inherited) that matches a *previously* declared &lt;log&gt;
272 by its "name" attribute.  Foreach &lt;outlet&gt; tag, a sink is created so
273 that any input sent to the containing &lt;log&gt; will additionally be
274 propagated to the &lt;outlet&gt;.
275 </para>
276 <para>
277 There is an implicit log named "stderr" that is attached to file
278 descriptor 2 that has timestamps enabled.
279 </para>
280
281 <section id="config.noitd.section.logs.special">
282   <title>Special log names</title>
283
284   <variablelist>
285   <varlistentry><term>stderr</term><listitem><para>
286    opened to file descriptor two during log initialization.
287   </para></listitem></varlistentry>
288
289   <varlistentry><term>error</term><listitem><para>
290    destination for error messages.
291   </para></listitem></varlistentry>
292
293   <varlistentry><term>debug</term><listitem><para>
294     destination for debugging output.
295   </para></listitem></varlistentry>
296
297   <varlistentry><term>check</term><listitem><para>
298    When a check is altered in any way (including creation),
299    the identifying attributes, including the uuid, are logged to this
300    facility.
301
302    <programlisting>
303    'C' TIMESTAMP UUID TARGET MODULE NAME
304    </programlisting>
305   </para></listitem></varlistentry>
306
307   <varlistentry><term>status</term><listitem><para>
308    When a check status changes (either availability or
309    state) and neither the new state nor the old state are "unknown", it
310    is considered a state change for the check.  The new availability
311    and new state are logged to this facility.
312
313    <programlisting>
314    'S' TIMESTAMP UUID STATE AVAILABILITY DURATION STATUS_MESSAGE
315    </programlisting>
316   </para></listitem></varlistentry>
317
318   <varlistentry><term>metrics</term><listitem><para>
319    Each time a check is completed, the various metrics
320    that were observed by the check are logged to this facility.  The
321    VALUE is always a string or [[null]] (never binary encoded/packed).
322    The TYPE indicates the datatype the check intended when it was
323    observed.
324
325    <programlisting>
326    'M' TIMESTAMP UUID NAME TYPE VALUE
327    </programlisting>
328
329    <variablelist>
330      <varlistentry><term>NAME</term><listitem><para>is the name of the metric
331       and the encouraged format for this is "name`subname`subsubname`etc"</para></listitem>
332       </varlistentry>
333
334      <varlistentry><term>TYPE</term><listitem>
335        <variablelist>
336          <varlistentry><term>i</term><listitem><para>INT32</para></listitem></varlistentry>
337          <varlistentry><term>I</term><listitem><para>UINT32</para></listitem></varlistentry>
338          <varlistentry><term>l</term><listitem><para>INT64</para></listitem></varlistentry>
339          <varlistentry><term>L</term><listitem><para>UINT64</para></listitem></varlistentry>
340          <varlistentry><term>n</term><listitem><para>DOUBLE</para></listitem></varlistentry>
341          <varlistentry><term>s</term><listitem><para>STRING</para></listitem></varlistentry>
342        </variablelist>
343        </listitem>
344       </varlistentry>
345    </variablelist>
346   </para>
347   </listitem>
348   </varlistentry>
349 </variablelist>
350
351 <example>
352 <title>Sample configuration for the log section</title>
353 <programlisting><![CDATA[
354   <logs>
355     <console>
356       <outlet name="stderr" />
357       <log name="error" />
358       <log name="debug" disabled="true" />
359     </console>
360     <log name="feed" type="jlog" path="/var/log/noitd.feed" />
361     <feeds>
362       <outlet name="feed" />
363       <log name="check" />
364       <log name="metrics" />
365       <log name="status">
366         <outlet name="error" />
367       </log>
368     </feeds>
369   </logs>
370 ]]></programlisting>
371 </example>
372
373  <para>In the above example:</para>
374  <itemizedlist>
375    <listitem><para>
376    a &lt;console&gt; metagroup is created for the purpose of inheriting the
377    "stderr" outlet.  The logs named "error" and "debug" are
378    instantiated and inherit the "stderr" outlet.  However, "debug" is
379    disabled, so no input to the "debug" log will be written anywhere.
380    </para></listitem>
381
382    <listitem><para>
383    a log named "feed" is created of type "jlog" writing to the
384    "/var/log/noitd.feed" directory (jlogs paths are directories, whereas
385    "file" paths are filenames).
386    </para></listitem>
387
388    <listitem><para>
389    a &lt;feeds&gt; metagroup is created for the purpose of inheriting the
390    "feed" outlet.  The logs "check," "metrics," and "status" are
391    instantiated and will log via the "feed" outlet (all writing to the
392    same jlog).  Additionally, the "status" feed is given an additional
393    outlet named "error" so we will see inputs to status in both the
394    "feed" jlog and on the console ("stderr").
395    </para></listitem>
396  </itemizedlist>
397 </section>
398 </section>
399 </chapter>
Note: See TracBrowser for help on using the browser.