root/src/README.txt

Revision 2061e31486f948b64c509cf31ce47b4ad863a8c9, 7.4 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 7 years ago)

further describe the inheritance

  • 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 === Explicit Inheritance ===
78
79 Sometimes it is useful to define a configuration table key/value set
80 for reuse, but the strict parent-child inheritance model is awkward.
81 Under these circumstances, the explicit inheritance often solves the
82 issue at hand.  With explicit inheritance, a configuration can inherit
83 from another named node elsewhere in the configuration.
84
85 The <config /> stanzas can be identified, as is typical in XML, with
86 the "id" attribute: <config id="sample" />.  Additionally, any config
87 may explicitly specify that it inherits from a named config by
88 specifying the "inherit" attribute.
89
90 Any <config />, A, which has the "inherit" attribute will first
91 inherit from its most direct parent, then supplement/replace those
92 key/values with the configuration whose "id" attribute matches the
93 "inherit" attribute of A, and finally supplement/replace those
94 key/values with key/values directly beneath A.  The entire tree is
95 searched for a node whose "id" matches A's "inherit" attribute.
96
97 ==== Example ====
98
99   <config name="A">
100     <key1>a</key1>
101     <key2>b</key2>
102     <key3>c</key3>
103     <config name="C" inherit="bob">
104       <key1>AAA</key1>
105       <key4>DDD</key4>
106     </config>
107   </config>
108   <x>
109     <y>
110       <z>
111         <config name="B" id="bob">
112           <key2>bobB</key2>
113           <key5>bobE</key5>
114         </config>
115       </z>
116     </y>
117   </x>
118
119 The config named "A" contains:
120   key1: a
121   key2: b
122   key3: c
123
124 The config named "C" contains:
125   key1: AAA
126   key2: bobB
127   key3: c
128   key4: DDD
129   key5: bobE
130
131 It should be noted hat all config's include the one named "B" above
132 follows this same inheritance model.
133
134 == Seciton <eventer>: ==
135
136 This section provides configuration directives to the eventing
137 subsystem.  Think of the eventer as the engine that drives all I/O,
138 jobs, and timed events.  To choose the eventer, the "implementation"
139 attribute is used in the eventer node.  For example, to select the
140 kqueue eventer (for Mac OS X or modern BSDs):
141
142   <eventer implementation="kqueue" />
143
144 == Section <logs>: ==
145
146 The logs section contains <log> elements at arbitrary depths.  A log
147 requires several attributes to be useful:
148
149  * "name" this must me unique.  Several names have meaning within the
150    product.  If you match that name, you control how that information
151    is logged.
152
153  * "type" this specified ths underlying log writing implementation.
154    Valid options are "file" (the default if unspecified), "jlog" which
155    is the a binary 'auto-rotating', consumable, multi-subscriber log
156    format.
157
158  * "path" the path to the log (interpreted by the "type"
159    implementation).
160
161  * "disabled" (boolean: <true|false>, default false) that dictates
162    whether the log implmenation will actually write anything.  If set
163    to true, the log will be silences and will not propagate input to
164    any attached outlets.
165
166 Within a <log> element, zero, one or many <outlet> elements may be
167 present.  The outlet element must contain a "name" attribute (this
168 attribute is not inherited) that matches a *previously* declared <log>
169 by its "name" attribute.  Foreach <outlet> tag, a sink is created so
170 that any input sent to the containing <log> will additionally be
171 propagated to the <outlet>.
172
173 There is an implicit log named "stderr" that is attached to file
174 descriptor 2.
175
176 === Special log names ===
177
178  * "stderr" : opened to file descriptor two during log initialization.
179
180  * "error" : destination for error messages.
181
182  * "debug" : destination for debugging output.
183
184  * "check" : When a check is altered in any way (including creation),
185    the identifying attributes, includeing the uuid are logged to this
186    facility.
187
188    'C' TIMESTAMP UUID TARGET MODULE NAME
189
190  * "status" : When a check status changes (either availability or
191    state) and neither the new state nor the old state are "unknown" it
192    is considered a state change for the check and the new availability
193    and new state are logged to this facility.
194
195    'S' TIMESTAMP UUID STATE AVAILABILITY DURATION STATUS_MESSAGE
196
197  * "metrics" : Each time a check is completed, the various metrics
198    that were observed by the check are logged to this facility.  The
199    VALUE is always a string or [[null]] (never binary encoded/packed).
200    The TYPE indicates the datatype the check intended when it was
201    observed.
202
203    'M' TIMESTAMP UUID NAME TYPE VALUE
204
205    NAME is the name of the metric and the encouraged format for this
206    is "name`subname`subsubname`etc"
207
208    TYPES:
209      * i: INT32
210      * I: UINT32
211      * l: INT64
212      * L: UINT64
213      * n: DOUBLE
214      * s: STRING
215
216 === Example ===
217
218   <logs>
219     <console>
220       <outlet name="stderr" />
221       <log name="error" />
222       <log name="debug" disabled="true" />
223     </console>
224     <log name="feed" type="jlog" path="/var/log/noitd.feed" />
225     <feeds>
226       <outlet name="feed" />
227       <log name="check" />
228       <log name="metrics" />
229       <log name="status">
230         <outlet name="error" />
231       </log>
232     </feeds>
233   </logs>
234
235  In the above example:
236
237  * a <console> metagroup is created for the purpose of inheriting the
238    "stderr" outlet.  The logs named "error" and "debug" are
239    instantiated and inherit the "stderr" outlet.  However, "debug" is
240    disabled, so no input the the "debug" log will be written anywhere.
241
242  * a log named "feed" is create of type "jlog" writing to the
243    "/var/log/noitd.feed" directory (jlogs paths are directories, where
244    as "file" paths are filenames).
245
246  * a <feeds> metagroup is created for the purpose of inheriting the
247    "feed" outlet.  The logs "check," "metrics," and "status" are
248    instantiated and will log via the "feed" outlet (all writing to the
249    same jlog).  Additionally, the "status" feed is given an additional
250    outlet named "error" so we will see inputs to status in both the
251    "feed" jlog and on the console ("stderr").
252
Note: See TracBrowser for help on using the browser.