root/src/README.txt

Revision a136e6147196fd1969fa920391a6d55ed3975fde, 5.8 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 6 years ago)

rework a lot of config stuff, add docs in a bad place.. README.txt? come on Theo.

  • Property mode set to 100644
Line 
1 = Configuration File =
2
3 === Sample Heirarchy ===
4
5   <noit>
6     <eventer/>
7     <modules>
8       <...>
9         <module />
10       </...>
11     </modules>
12     <logs>
13       <...>
14         <log>
15           <outlet />
16           <outlet />
17         </log>
18       </...>
19     </logs>
20     <listeners>
21       <...>
22         <listener/>
23         <listener>
24           <config />
25           <sslconfig />
26         <listener>
27       </...>
28     </listeners>
29     <checks>
30       <...>
31         <check uuid="xxx" />
32       </...>
33     </checks>
34   </noit>
35
36 Unless otherwise specified, elements and attributes are inherited from
37 all anscestors.  As is typical with inheritence, the youngest/deepest
38 value overrides values of anscestors.  If the value requests is a set
39 of key/value pairs, the the top-most anscestor is is queried, then its
40 child is queries merging values replacing conflicts and so on until
41 the youngest/deepest node is reached.
42
43 === Example: ===
44
45       <a foo="bar">
46         <config>
47           <key1>val a 1</key1>
48           <key2>val a 2</key2>
49         </config>
50         <b quux="baz">
51           <config>
52             <key1>val b 1</key1>
53             <key3>val b 3</key3>
54           </config>
55           <c foo="meme" />
56         </b>
57       </a>
58
59 When looking at the "foo" attribute we see the following values at nodes:
60   a: bar
61   b: bar
62   c: meme
63
64 When looking at the "quux" attribute we see the following values at nodes:
65   a: (none)
66   b: baz
67   c: baz
68
69 When looking at the key/value set "config" we see the following values at nodes:
70   a: { key1: "val a 1", key2: "val a 2" }
71   b: { key1: "val b 1", key2: "val a 2", key3: "val b 3" }
72   c: { key1: "val b 1", key2: "val a 2", key3: "val b 3" }  (same as b)
73
74 This inheritance model allows for "non-repetitive" configuration
75 approaches: "express yourself once and reuse."
76
77
78 == Seciton <eventer>: ==
79
80 This section provides configuration directives to the eventing
81 subsystem.  Think of the eventer as the engine that drives all I/O,
82 jobs, and timed events.  To choose the eventer, the "implementation"
83 attribute is used in the eventer node.  For example, to select the
84 kqueue eventer (for Mac OS X or modern BSDs):
85
86   <eventer implementation="kqueue" />
87
88 == Section <logs>: ==
89
90 The logs section contains <log> elements at arbitrary depths.  A log
91 requires several attributes to be useful:
92
93  * "name" this must me unique.  Several names have meaning within the
94    product.  If you match that name, you control how that information
95    is logged.
96
97  * "type" this specified ths underlying log writing implementation.
98    Valid options are "file" (the default if unspecified), "jlog" which
99    is the a binary 'auto-rotating', consumable, multi-subscriber log
100    format.
101
102  * "path" the path to the log (interpreted by the "type"
103    implementation).
104
105  * "disabled" (boolean: <true|false>, default false) that dictates
106    whether the log implmenation will actually write anything.  If set
107    to true, the log will be silences and will not propagate input to
108    any attached outlets.
109
110 Within a <log> element, zero, one or many <outlet> elements may be
111 present.  The outlet element must contain a "name" attribute (this
112 attribute is not inherited) that matches a *previously* declared <log>
113 by its "name" attribute.  Foreach <outlet> tag, a sink is created so
114 that any input sent to the containing <log> will additionally be
115 propagated to the <outlet>.
116
117 There is an implicit log named "stderr" that is attached to file
118 descriptor 2.
119
120 === Special log names ===
121
122  * "stderr" : opened to file descriptor two during log initialization.
123
124  * "error" : destination for error messages.
125
126  * "debug" : destination for debugging output.
127
128  * "check" : When a check is altered in any way (including creation),
129    the identifying attributes, includeing the uuid are logged to this
130    facility.
131
132    'C' TIMESTAMP UUID TARGET MODULE NAME
133
134  * "status" : When a check status changes (either availability or
135    state) and neither the new state nor the old state are "unknown" it
136    is considered a state change for the check and the new availability
137    and new state are logged to this facility.
138
139    'S' TIMESTAMP UUID STATE AVAILABILITY DURATION STATUS_MESSAGE
140
141  * "metrics" : Each time a check is completed, the various metrics
142    that were observed by the check are logged to this facility.  The
143    VALUE is always a string or [[null]] (never binary encoded/packed).
144    The TYPE indicates the datatype the check intended when it was
145    observed.
146
147    'M' TIMESTAMP UUID NAME TYPE VALUE
148
149    NAME is the name of the metric and the encouraged format for this
150    is "name`subname`subsubname`etc"
151
152    TYPES:
153      * i: INT32
154      * I: UINT32
155      * l: INT64
156      * L: UINT64
157      * n: DOUBLE
158      * s: STRING
159
160 === Example ===
161
162   <logs>
163     <console>
164       <outlet name="stderr" />
165       <log name="error" />
166       <log name="debug" disabled="true" />
167     </console>
168     <log name="feed" type="jlog" path="/var/log/noitd.feed" />
169     <feeds>
170       <outlet name="feed" />
171       <log name="check" />
172       <log name="metrics" />
173       <log name="status">
174         <outlet name="error" />
175       </log>
176     </feeds>
177   </logs>
178
179  In the above example:
180
181  * a <console> metagroup is created for the purpose of inheriting the
182    "stderr" outlet.  The logs named "error" and "debug" are
183    instantiated and inherit the "stderr" outlet.  However, "debug" is
184    disabled, so no input the the "debug" log will be written anywhere.
185
186  * a log named "feed" is create of type "jlog" writing to the
187    "/var/log/noitd.feed" directory (jlogs paths are directories, where
188    as "file" paths are filenames).
189
190  * a <feeds> metagroup is created for the purpose of inheriting the
191    "feed" outlet.  The logs "check," "metrics," and "status" are
192    instantiated and will log via the "feed" outlet (all writing to the
193    same jlog).  Additionally, the "status" feed is given an additional
194    outlet named "error" so we will see inputs to status in both the
195    "feed" jlog and on the console ("stderr").
196
Note: See TracBrowser for help on using the browser.