root/docs/operation/cli/cli.xml

Revision 23dea7e00df87480acb58bb3398283c2bb227949, 20.4 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 <section>
3   <title>Interactive Console Command Line Operation</title>
4   <para>
5       This section serves to document the basic methods of operation
6       available through the interactive console's command line interface. 
7       It is currently in rough draft status.
8   </para>
9
10   <section>
11     <title>General Operational Principles</title>
12     <para>
13       The command line interface to the system available through the
14       interactive console operates in a fashion similar to Cisco's <trademark>IOS</trademark>,
15       in that there are various "levels" or "sets"/"sub-sets" of commands
16       within the interface.  Operations and operands may be tab-completed
17       or abbreviated to their un-ambiguous form as needed or desired
18       (analogous to "configure terminal" becoming "conf t" in common IOS
19       usage).  Command history and editing is available.
20     </para>
21   </section>
22
23   <section>
24     <title>Accessing the Interactive Console</title>
25     <para>
26       The interactive console is accessed by telneting to the configured
27       access port on the host running <command>noitd</command>.  By default this is
28       port 32322.  The applicable configuration parameter in the <filename>noitd.conf</filename>
29       XML file is the port attribute of the "listener" element, e.g.:
30       <programlisting><![CDATA[
31       <listener address="*" port="32322">
32         ]]></programlisting> Please see the configuration section of
33       the manual for more information.
34     </para>
35   </section>
36
37   <section>
38     <title>Basic Command List</title>
39     <para>An example session of interaction showing the use of help and a few
40       operating modes is illustrative:
41       <screen>
42       noit# help
43       = Topics =
44       ==&gt; 'module'
45
46       = Commands =
47       ==&gt; 'apply'
48       ==&gt; 'configure'
49       ==&gt; 'exit'
50       ==&gt; 'no'
51       ==&gt; 'reload'
52       ==&gt; 'restart'
53       ==&gt; 'show'
54       ==&gt; 'shutdown'
55       ==&gt; 'watch'
56       ==&gt; 'write'
57       noit# help module
58       Help for 'module':
59       = Loaders and Modules =
60       lua
61       ping_icmp
62       smtp
63       ssh2
64       varnish
65       selfcheck
66       resmon
67       http
68       snmp
69       noit# configure {tab pressed twice}
70       apply     help      terminal
71       noit# conf t
72       noit(conf:/)# ls
73       == Section Settings ==
74       @lockfile: /var/run/noitd.lock
75       == Subsections ==
76       eventer
77       logs
78       modules
79       listeners
80       rest
81       checks
82       filtersets
83       config_templates
84       noit(conf:/)# help
85       -&gt; 'terminal'
86       = Topics =
87       ==&gt; 'module'
88
89       = Commands =
90       ==&gt; 'apply'
91       ==&gt; 'attribute'
92       ==&gt; 'cd'
93       ==&gt; 'check'
94       ==&gt; 'config'
95       ==&gt; 'exit'
96       ==&gt; 'filterset'
97       ==&gt; 'ls'
98       ==&gt; 'no'
99       ==&gt; 'section'
100       ==&gt; 'write'
101       noit(conf:/)# exit
102       noit# show
103       ==&gt; 'apply'
104       ==&gt; 'check'
105       ==&gt; 'checks'
106       ==&gt; 'eventer'
107       ==&gt; 'watches'
108       incomplete command.
109
110       </screen>
111
112       <variablelist>
113         <title>Command Descriptions</title>
114
115         <varlistentry>
116           <term>help</term>
117           <listitem>
118             <para><command>help</command> provides brief help information appropriate to a given context.</para>
119           </listitem>
120         </varlistentry>
121
122         <varlistentry>
123           <term>show</term>
124           <listitem>
125             <para><command>show</command> shows various aspects of the system.  See the "Showing System Information" section below for further detail.</para>
126           </listitem>
127         </varlistentry>
128
129         <varlistentry>
130           <term>watch</term>
131           <listitem>
132             <para><command>watch</command> is much like show except it re-displays the given information periodically.  See the "Showing System Information" section below for further detail.</para>
133           </listitem>
134         </varlistentry>
135        
136         <varlistentry>
137           <term>exit</term>
138           <listitem>
139             <para><command>exit</command> leaves the current "level" of session (e.g. returns to regular interactive session if used within a configuration sub-"level" or exits the current interactive session entirely and closes the connection if used within the regular interaction "level").</para>
140           </listitem>
141         </varlistentry>
142
143         <varlistentry>
144           <term>configure</term>
145           <listitem>
146             <para><command>configure</command> causes the session to enter configuration mode if used with the <command>terminal</command> argument or with the <command>apply</command> argument allows for multiple configurations to be specified at once in an automated fashion (see below for coverage of <command>apply</command> and the "Configuring the System" section for more information about run-time configuration in general).</para>
147           </listitem>
148         </varlistentry>
149
150         <varlistentry>
151           <term>write</term>
152           <listitem>
153             <para><command>write</command> writes the current operating configuration to: the permanent configuration store (<filename>noitd.conf</filename> by default, in the location specified either at startup with -c or in the default compile-time system directory) with <command>file</command> argument (<command>memory</command> is an alias), or to the current interactive display with the <command>terminal</command> argument.</para>
154           </listitem>
155         </varlistentry>
156
157         <varlistentry>
158           <term>reload</term>
159           <listitem>
160             <para><command>reload</command> causes <command>noitd</command> to reload configuration information from the permanent configuration store (<filename>noitd.conf</filename> by default, in the location specified either at startup with -c or in the default compile-time system directory).</para>
161           </listitem>
162         </varlistentry>
163
164         <varlistentry>
165             <term>restart</term>
166             <listitem>
167               <para><command>restart</command> causes <command>noitd</command> to restart, re-reading all configuration from the permanent configuration store in the process. As part of restarting, the current interactive session is terminated.</para>
168             </listitem>
169         </varlistentry>
170
171         <varlistentry>
172             <term>shutdown</term>
173             <listitem>
174               <para><command>shutdown</command> causes <command>noitd</command> to shut down entirely.</para>
175             </listitem>
176         </varlistentry>
177
178         <varlistentry>
179             <term>apply</term>
180             <listitem>
181               <para><command>apply {variable name} {range specifier} {command}</command> works much like a <command>for {name} in {list}; do {command, optionally using $name}; done</command> loop in the <command>bash</command> shell, in that it iterates over the given range, setting the variable name to each value in turn and executing the given command with $variablename set and available at each execution. A simple example is given below of executing an ssh2 check three times using apply:</para>
182               <screen>
183                 noit# apply i 1..3 show check 002d58ff-20ff-4db0-9420-782fc1748dc4
184                 ==== 002d58ff-20ff-4db0-9420-782fc1748dc4 ====
185                 name: ssh2 [from module]
186                 module: ssh2
187                 target: 127.0.0.1
188                 period: 60000
189                 timeout: 4000
190                 oncheck: [undef]
191                 filterset: default [inherited from @filterset]
192                 disable: [undef]
193                 currently: idle
194                 last run: 31.104 seconds ago
195                 availability/state: available/good
196                 status: 59698f91c167393deb952564fe316dca
197                 metrics:
198                 duration[I] = 192
199                 fingerprint[s] = 59698f91c167393deb952564fe316dca
200                 ==== 002d58ff-20ff-4db0-9420-782fc1748dc4 ====
201                 name: ssh2 [from module]
202                 module: ssh2
203                 target: 127.0.0.1
204                 period: 60000
205                 timeout: 4000
206                 oncheck: [undef]
207                 filterset: default [inherited from @filterset]
208                 disable: [undef]
209                 currently: idle
210                 last run: 31.104 seconds ago
211                 availability/state: available/good
212                 status: 59698f91c167393deb952564fe316dca
213                 metrics:
214                 duration[I] = 192
215                 fingerprint[s] = 59698f91c167393deb952564fe316dca
216                 ==== 002d58ff-20ff-4db0-9420-782fc1748dc4 ====
217                 name: ssh2 [from module]
218                 module: ssh2
219                 target: 127.0.0.1
220                 period: 60000
221                 timeout: 4000
222                 oncheck: [undef]
223                 filterset: default [inherited from @filterset]
224                 disable: [undef]
225                 currently: idle
226                 last run: 31.104 seconds ago
227                 availability/state: available/good
228                 status: 59698f91c167393deb952564fe316dca
229                 metrics:
230                 duration[I] = 192
231                 fingerprint[s] = 59698f91c167393deb952564fe316dca
232               </screen>
233             </listitem>
234         </varlistentry>
235
236         <varlistentry>
237           <term>no</term>
238           <listitem>
239             <para><command>no</command> works much like "no" in <trademark>IOS</trademark>, negating or nullifying another command.  e.g. <command>no watch {check id} {interval}</command> to disable a given watch (see below for further details).</para>
240           </listitem>
241         </varlistentry>
242       </variablelist>
243     </para>
244   </section>
245
246   <section>
247     <title>Showing System Information</title>
248     <para>The two main commands for showing system information are <command>show</command> and <command>watch</command>.  <command>show</command> is useful for one-off queries of information, and <command>watch</command> is useful for periodically redisplaying the same information (e.g. to see snapshots of activity while some other process is affecting the monitored system/information).</para>
249     <section>
250       <title>show</title>
251       <para><command>show</command> show accepts a number of arguments:</para>
252       <variablelist>
253         <varlistentry>
254           <term>watches</term>
255           <listitem>
256             <para><command>show watches</command> displays a list of all active watches currently being serviced by <command>noitd</command>.</para>
257           </listitem>
258         </varlistentry>
259
260         <varlistentry>
261           <term>checks</term>
262           <listitem>
263             <para><command>show checks</command> displays a list of checks that <command>noitd</command> is currently servicing.  Example output is illuminative:</para>
264               <screen>
265                 noit# show checks
266                 1b4e28ba-2fa1-11d2-883f-b9b761bde3fb 127.0.0.1`ping_icmp
267                 cnt=5,avail=100,min=0.0000,max=0.0000,avg=0.0000
268                 f7cea020-f19d-11dd-85a6-cb6d3a2207dc 127.0.0.1`selfcheck
269                 ok
270                 002d58ff-20ff-4db0-9420-782fc1748dc4 127.0.0.1`ssh2
271                 59698f91c167393deb952564fe316dca
272               </screen>
273               <para>Each check's primary identifier is a hexadecimal GUID.  This may be tab-completed in common use from the longest unique string, much like commands. In the example above, for instance, "002" would be sufficient to tab complete a reference to the check 002d58ff-20ff-4db0-9420-782fc1748dc4. Each check is further identified as accessing a given IP/host and contains some description of what the check is doing as configured when the check was configured (see the "Configuring the System" section below, and/or <filename>noitd.conf</filename>). The second line for each check provides check-specific further information or status.</para>
274           </listitem>
275         </varlistentry>
276
277         <varlistentry>
278           <term>check</term>
279           <listitem>
280             <para><command>show check {check id}</command>. See discussion above for referencing a particular check by id.  This provides more in-depth information about a specific check.  For example, using the check list mentioned above:</para>
281               <screen>
282                 noit# show check 1b4e28ba-2fa1-11d2-883f-b9b761bde3fb
283                 ==== 1b4e28ba-2fa1-11d2-883f-b9b761bde3fb ====
284                 name: ping_icmp [from module]
285                 module: ping_icmp
286                 target: 127.0.0.1
287                 period: 15000
288                 timeout: 14000
289                 oncheck: [undef]
290                 filterset: default [inherited from @filterset]
291                 disable: [undef]
292                 currently: running
293                 last run: 9.377 seconds ago
294                 availability/state: available/good
295                 status: cnt=5,avail=100,min=0.0000,max=0.0001,avg=0.0000
296                 metrics:
297                 available[n] = 1.000000000000e+02
298                 *count[i] = 5
299                 average[n] = 4.359999984445e-05
300                 *maximum[n] = 5.400000009104e-05
301                 *minimum[n] = 2.800000038405e-05
302               </screen>
303           </listitem>
304         </varlistentry>
305       </variablelist>
306     </section>
307
308     <section>
309       <title>watch</title>
310     </section>
311     <para><command>watch {check id} {interval}</command> redisplays information for a given check at a configurable interval. Interval is given in units of milliseconds.  If interval is omitted, presently, there is a bug where the check begins to output at its configured interval directly to the cli, but does not appear as a watch in <command>show watches</command> and <command>no watch {id}</command> has no effect.</para>
312     <para>The currently active watches may be listed with <command>show watches</command>, and an active watch may be terminated with by issuing the command <command>no watch {check id} {interval}</command> where check id and interval are the ones used for the initial creation of the watch.</para>
313   </section>
314
315   <section>
316     <title>Configuring the System</title>
317     <para>The focus of this section is configuring <command>noitd</command>'s behavior at run-time via the interactive console.  For documentation of <filename>noitd.conf</filename> itself, see <link linkend="configuration">the main chapter on system configuration</link>.  As a general note, to store run-time configuration to the permanent configuration store, see the <command>write file</command> command above.</para>
318     <section>
319       <title>Configure Terminal ("conf t") Mode</title>
320       <para>To enter the interactive configuration mode, first telnet to <command>noitd</command>'s telnet port and issue the "configure terminal" command, which may be abbreviated as "conf t" if desired. (Please see above information about default port, port configuration location, etc.)</para>
321       <para>Configure terminal mode presents a different array of options than regular mode, which are summarized below.  (Some common commands have been ommitted as their function is identical within conf-t mode as within normal interactive mode, e.g. <command>exit</command>.)</para>
322       <variablelist>
323         <varlistentry>
324             <term>cd</term>
325             <listitem>
326               <para><command>cd {location, e.g. ".." or "checks"}</command> changes the point where the interactive configuration session is within the tree-like organizational structure of the configuration space in a fashion similar to <command>cd</command> within a filesystem directory tree.  (See note below.)</para>
327             </listitem>
328         </varlistentry>
329
330         <varlistentry>
331             <term>section</term>
332             <listitem>
333                 <para><command>section {location}</command> operates similarly to <command>cd</command>, except that it will create the new location if it does not exist.</para>
334             </listitem>
335         </varlistentry>
336
337         <varlistentry>
338             <term>ls</term>
339             <listitem>
340               <para><command>ls</command> lists the configured entities at a given point within the tree-like organizational structure of the configuration space in a fashion similar to <command>ls</command> within a filesystem directory tree.  (See note below.) </para>
341             </listitem>
342         </varlistentry>
343
344         <varlistentry>
345             <term>status</term>
346             <listitem>
347               <para><command>status</command> displays the fine-grained details about a particular leaf-node/entity within the configuration space.</para>
348             </listitem>
349         </varlistentry>
350
351         <varlistentry>
352           <term>check</term>
353           <listitem>
354             <para><command>check {check id}</command> enters the configuration space for a particular leaf-node of the general configuration tree, i.e. the exact configuration for a particular check within the system. <command>check new {params}</command> may be used to set up a new check within the system, where params are dependent on what is required for a check using whichever module.  For example, <command>check new target 127.0.0.1 module http period 60000 timeout 10000</command> sets up a new http check on localhost running every minute and timing out after ten seconds.  By default the new check will be named "target`module", and after entry of the above command you will be placed into the configuration space for the new check as though you had run <command>check {the new id}</command> upon it.  Of note is that the new check is disabled by default (see <command>status</command> output), you must run <command>no attribute disable</command> to enable it.</para>
355           </listitem>
356         </varlistentry>
357
358         <varlistentry>
359             <term>attribute</term>
360             <listitem>
361               <para><command>attribute</command> enables you to alter the fine-grained details about a particular leaf-node/entity within the configuration space; e.g. "no attr disable" to enable a check, or "attr port 2222" on an ssh2 check to have it check port 2222 instead of the default 22.</para>
362             </listitem>
363         </varlistentry>
364
365         <varlistentry>
366             <term>filterset</term>
367             <listitem>
368               <para><command>filterset</command> is applicable only in the /filterset "directory" and has to do with the maintenance of filters, which are (briefly) exclusion patterns that filter out collected metrics from being reported upstream to <command>stratcon</command> (the noit daemon will still collect all of the data, but only the un-filtered metrics will propagate).</para>
369             </listitem>
370         </varlistentry>
371       </variablelist>
372       <para>Configure terminal mode has a general tree-like organizational structure mimicing the xml in <filename>noitd.conf</filename>, hence commands like <command>cd</command> and <command>ls</command>. Within some leaf nodes of the tree (for instance, check entities' representations) <command>status</command> should be substituted for <command>ls</command> as the latter operates on entities rather than attributes of entities (which would be displayed by <command>status</command>).</para>
373       <para>An example configuration session is shown below to illustrate some of the above:</para>
374       <screen>
375         noit# conf t
376         noit(conf:/)# cd checks
377         noit(conf:/checks)# ls
378         == Section Settings ==
379         @max_initial_stutter: 30000
380         @filterset: default
381         @transient_min_period: 1000
382         @transient_period_granularity: 500
383         == Subsections ==
384         foo
385         == Checks ==
386         check[@uuid="f7cea020-f19d-11dd-85a6-cb6d3a2207dc"] 127.0.0.1`selfcheck`selfcheck
387         check[@uuid="1b4e28ba-2fa1-11d2-883f-b9b761bde3fb"] 127.0.0.1`ping_icmp`ping_icmp
388         check[@uuid="002d58ff-20ff-4db0-9420-782fc1748dc4"] 127.0.0.1`ssh2`ssh2
389         check[@uuid="70a3633f-1629-4417-a7db-d48b9558c48e"] 127.0.0.1`http`http
390         noit(conf:/checks)# check 70a3633f-1629-4417-a7db-d48b9558c48e
391         noit(conf:127.0.0.1`http)# status
392         ==== 70a3633f-1629-4417-a7db-d48b9558c48e ====
393         name: http [from module]
394         module: http
395         target: 127.0.0.1
396         period: 60000
397         timeout: 10000
398         oncheck: [undef]
399         filterset: default [inherited from @filterset]
400         disable: [undef]
401         currently: idle
402         last run: 46.432 seconds ago
403         availability/state: available/good
404         status: code=200,rt=0.001s,bytes=39
405         metrics:
406         tt_connect[I] = 0
407         bytes[i] = 39
408         code[s] = 200
409         tt_firstbyte[I] = 1
410         duration[I] = 1
411         noit(conf:127.0.0.1`http)# exit
412         noit(conf:/checks)# exit
413         noit#
414       </screen>
415     </section>
416   </section>
417 </section>
418 <!--
419 vim:ts=2:sw=2:et:
420 -->
Note: See TracBrowser for help on using the browser.