Agenda: cacti-cli-commands.htm

File cacti-cli-commands.htm, 18.0 KB (added by admin, 5 years ago)
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml">
3<head>
4  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5  <meta http-equiv="Content-Style-Type" content="text/css" />
6  <meta name="generator" content="pandoc" />
7  <meta name="author" content="Cacti command line tools" />
8  <title>Network Management and Monitoring</title>
9  <style type="text/css">code{white-space: pre;}</style>
10  <link rel="stylesheet" href="../../style.css" type="text/css" />
11</head>
12<body>
13<div id="header">
14<h1 class="title">Network Management and Monitoring</h1>
15<h2 class="author">Cacti command line tools</h2>
16</div>
17<div id="TOC">
18<ul>
19<li><a href="#introduction"><span class="toc-section-number">1</span> Introduction</a><ul>
20<li><a href="#goals"><span class="toc-section-number">1.1</span> Goals</a></li>
21<li><a href="#notes"><span class="toc-section-number">1.2</span> Notes</a></li>
22</ul></li>
23<li><a href="#exercises"><span class="toc-section-number">2</span> Exercises</a></li>
24<li><a href="#adding-a-device"><span class="toc-section-number">3</span> 1. Adding a device</a></li>
25<li><a href="#adding-graphs"><span class="toc-section-number">4</span> 2. Adding graphs</a><ul>
26<li><a href="#find-the-graph-template-id"><span class="toc-section-number">4.1</span> Find the graph template id</a></li>
27<li><a href="#find-out-what-types-of-snmp-queries-are-possible"><span class="toc-section-number">4.2</span> Find out what types of SNMP queries are possible:</a></li>
28<li><a href="#find-the-valid-snmp-query-type"><span class="toc-section-number">4.3</span> Find the valid SNMP query type</a></li>
29<li><a href="#find-which-interfaces-to-graph-on-this-host"><span class="toc-section-number">4.4</span> Find which interfaces to graph on this host</a></li>
30<li><a href="#note"><span class="toc-section-number">4.5</span> NOTE:</a></li>
31</ul></li>
32<li><a href="#add-graph-items-to-the-tree"><span class="toc-section-number">5</span> 3. Add graph items to the tree</a><ul>
33<li><a href="#additional-commands"><span class="toc-section-number">5.1</span> Additional commands</a></li>
34<li><a href="#summary-and-more-sample-commands"><span class="toc-section-number">5.2</span> # Summary and more sample commands</a></li>
35</ul></li>
36</ul>
37</div>
38<h1 id="introduction"><a href="#introduction"><span class="header-section-number">1</span> Introduction</a></h1>
39<h2 id="goals"><a href="#goals"><span class="header-section-number">1.1</span> Goals</a></h2>
40<p>In this exercise you will learn some command-line scripts for adding devices, which can be used for scripting.</p>
41<h2 id="notes"><a href="#notes"><span class="header-section-number">1.2</span> Notes</a></h2>
42<ul>
43<li>Commands preceded with <code>$</code> imply that you should execute the command as a general user - not as root.</li>
44<li>Commands preceded with <code>#</code> imply that you should be working as root.</li>
45<li>Commands with more specific command lines (e.g. <code>rtrX&gt;</code> or <code>mysql&gt;</code>) imply that you are executing commands on remote equipment, or within another program.</li>
46</ul>
47<h1 id="exercises"><a href="#exercises"><span class="header-section-number">2</span> Exercises</a></h1>
48<p>As you have noticed, adding devices to Cacti via the user interface can take quite some time, as for each device you will have:</p>
49<ul>
50<li>add the device, filling out the description, hostname, SNMP community</li>
51<li>pick the interfaces or resources to be monitored (graphed)</li>
52<li>create the graph tree enty</li>
53<li>add the graphs to the graph tree.</li>
54</ul>
55<p>There are plugins to automate this, such as the aptly named &quot;autom8&quot;: <a href="http://docs.cacti.net/plugin:autom8">http://docs.cacti.net/plugin:autom8</a></p>
56<p>But if you wanted to add many devices in one pass, you would want to use something more efficient.</p>
57<p>Luckily, Cacti has command line tools for this:</p>
58<p><a href="http://www.cacti.net/downloads/docs/html/scripts.html">http://www.cacti.net/downloads/docs/html/scripts.html</a></p>
59<p>The commands provided are:</p>
60<pre><code>add_data_query.php
61add_device.php
62add_graphs.php
63add_graph_template.php
64add_perms.php
65add_tree.php</code></pre>
66<p>On Ubuntu, these are located under <code>/usr/share/cacti/cli</code></p>
67<p>The three commands we'll be focusing on are:</p>
68<ul>
69<li>add_device.php</li>
70<li>add_graphs.php</li>
71<li>add_tree.php</li>
72</ul>
73<p>They are individually documented here:</p>
74<ul>
75<li><a href="http://www.cacti.net/downloads/docs/html/cli_add_device.html">http://www.cacti.net/downloads/docs/html/cli_add_device.html</a></li>
76<li><a href="http://www.cacti.net/downloads/docs/html/cli_add_graphs.html">http://www.cacti.net/downloads/docs/html/cli_add_graphs.html</a></li>
77<li><a href="http://www.cacti.net/downloads/docs/html/cli_add_tree.html">http://www.cacti.net/downloads/docs/html/cli_add_tree.html</a></li>
78</ul>
79<p>The way it works, is that we will use the three commands in sequence, to:</p>
80<ul>
81<li>Add a device</li>
82<li>Create graphs for the device we've added</li>
83<li>Add these graphs to a tree</li>
84</ul>
85<p>Below is a walkthrough of adding a device and some graphs using these commands. Read through, and proceed to the exercise at the end.</p>
86<h1 id="adding-a-device"><a href="#adding-a-device"><span class="header-section-number">3</span> 1. Adding a device</a></h1>
87<pre><code>$ cd /usr/share/cacti/cli
88$ sudo ./add_device.php | less</code></pre>
89<p>You will see a lot of help output. You can page through it to look at all the options. So we know what we will put for:</p>
90<pre><code>--description   =&gt; the description of the host, say &quot;backbone router&quot; or
91                   &quot;rtrX.ws.nsrc.org&quot; - but that is up to you to decide
92--ip            =&gt; the ip or hostname - we recommend hostname! - of the device
93
94--version       =&gt; SNMP version (2)
95--comunity      =&gt; the SNMP community. By default, Cacti will try &#39;public&#39;,
96                   although you can pre-configure other communities in the
97                   Cacti user interface</code></pre>
98<p>We're missing two pieces of information:</p>
99<ul>
100<li>What availability method (PING or SNMP) to check if the device is &quot;up&quot;? From the options listed in the output of the command, we can see:</li>
101</ul>
102<pre><code>--avail        pingsnmp, [ping][none, snmp, pingsnmp]</code></pre>
103<p>We will use the &quot;snmp&quot; availability test.</p>
104<ul>
105<li><p>The Template: is it a Cisco, a Linux host, a generic SNMP device?</p>
106<p>For this, we use the <code>--list-host-templates</code> command, which will tell us which type of device Template is supported:</p></li>
107</ul>
108<pre><code>$ sudo ./add_device.php  --list-host-templates
109
110Valid Host Templates: (id, name)
1110   None
1121   Generic SNMP-enabled Host
1133   ucd/net SNMP Host
1144   Karlnet Wireless Bridge
1155   Cisco Router
1166   Netware 4/5 Server
1177   Windows 2000/XP Host
1188   Local Linux Machine</code></pre>
119<p>From the above, we can see that Cisco Router is template id number 5.</p>
120<p>Let's build our command line. If we are in group 7, we'd want to add, for example, router 7, which has IP address 10.0.7.254 and 10.10.0.227. Let's use IP 10.10.7.254 - if you have already created this device in Cacti, you may want to pick another device.</p>
121<pre><code>$ sudo ./add_device.php --description=&quot;rtr7.ws.nsrc.org&quot; --ip=10.10.7.254 \
122  --template=5 --avail=snmp --version=2 --community=NetManage </code></pre>
123<p>You should see output similar to this:</p>
124<pre><code>Adding rtr7.ws.nsrc.org (10.10.7.254) as &quot;Cisco Router&quot; using SNMP v2 with
125  community &quot;NetManage&quot; 
126Success - new device-id: (2)</code></pre>
127<p>Note the device-id &quot;2&quot;. This is Cacti's internal reference for this device. You don't need to write it down.</p>
128<p>Now, verify in the Web UI that the device has indeed been added:</p>
129<pre><code>Console -&gt; Management -&gt; Devices</code></pre>
130<h1 id="adding-graphs"><a href="#adding-graphs"><span class="header-section-number">4</span> 2. Adding graphs</a></h1>
131<p>This is the most complicated part of the operation, but once you understand the steps involved, it will be easier to repeat for other hosts.</p>
132<p>First, let's run the add_graphs.php commands without any options to see what it expects from us:</p>
133<pre><code>$ sudo ./add_graphs.php | less</code></pre>
134<p>Notice the options <code>--host-id</code>, <code>--graph-type</code>, <code>--graph-template-id</code>.</p>
135<p>We already know the host-id from the previous section - if you don't remember it, don't worry, we'll get to it below.</p>
136<p>Graph type (<code>--graph-type</code>) is is either cg or ds. 'cg' is used for absolute values such as gauge readings (CPU temperature, fan speed, ...), while 'ds' is used for interface counters etc. (Data Sources). We are using 'ds' type graphs for interfaces (<code>--graph-type=ds</code>)</p>
137<p>Also pay attention in particular to the &quot;List Options&quot; section, as we will be using this quite a bit to find out what SNMP data we want to query:</p>
138<p>List Options:</p>
139<pre><code>--list-hosts
140--list-graph-templates [--host-template-id=[ID]]
141--list-input-fields --graph-template-id=[ID]
142--list-snmp-queries
143--list-query-types  --snmp-query-id [ID]
144--list-snmp-fields  --host-id=[ID] [--snmp-query-id=[ID]]
145--list-snmp-values  --host-id=[ID] [--snmp-query-id=[ID]] --snmp-field=[Field]</code></pre>
146<p>A very useful command is the <code>--list-hosts</code> options, that we'll use to see which hosts are available, as we'll also need to get the host-id.</p>
147<p>Let's use this to fetch the host-id for the host you added in the previous section:</p>
148<pre><code>$ sudo ./add_graphs.php --list-hosts
149   
150Known Hosts: (id, hostname, template, description)
1511   127.0.0.1   8   Localhost
1522   10.10.7.254 5   rtr7.ws.nsrc.org</code></pre>
153<p>In this case, the host-id of rtr7 is '2'.</p>
154<p>Is this enough to build our command? Not yet. We still need to specify the following:</p>
155<pre><code>&quot;graph template id&quot; (--graph-template-id)
156&quot;snmp query id&quot; (--snmp-query-id)
157&quot;snmp field&quot; (--snmp-field)
158&quot;snmp value&quot; (--snmp-value)</code></pre>
159<h2 id="find-the-graph-template-id"><a href="#find-the-graph-template-id"><span class="header-section-number">4.1</span> Find the graph template id</a></h2>
160<p>To find out which graph templates are available, use the <code>--list-graph-templates</code> option:</p>
161<pre><code>$ sudo ./add_graphs.php --list-graph-templates</code></pre>
162<p>In the output, there are several options we could be interested in:</p>
163<pre><code>        2   Interface - Traffic (bits/sec)
164        18  Cisco - CPU Usage
165        22  Interface - Errors/Discards
166        23  Interface - Unicast Packets
167        24  Interface - Non-Unicast Packets
168        25  Interface - Traffic (bytes/sec)</code></pre>
169<p>We're really interested in creating bits/sec graphs at this point, so that's graph template no. 2</p>
170<h2 id="find-out-what-types-of-snmp-queries-are-possible"><a href="#find-out-what-types-of-snmp-queries-are-possible"><span class="header-section-number">4.2</span> Find out what types of SNMP queries are possible:</a></h2>
171<pre><code>$ sudo ./add_graphs.php --list-snmp-queries
172
173Known SNMP Queries:(id, name)
1741   SNMP - Interface Statistics
1752   ucd/net -  Get Monitored Partitions
1763   Karlnet - Wireless Bridge Statistics
1774   Netware - Get Available Volumes
1786   Unix - Get Mounted Partitions
1797   Netware - Get Processor Information
1808   SNMP - Get Mounted Partitions
1819   SNMP - Get Processor Information</code></pre>
182<p>Here, we are interested in the SNMP Interface statistics, therefore, <code>--snmp-query-id=1</code> is what we are looking for.</p>
183<h2 id="find-the-valid-snmp-query-type"><a href="#find-the-valid-snmp-query-type"><span class="header-section-number">4.3</span> Find the valid SNMP query type</a></h2>
184<p>Ok, but what kind of data do we want to graph? Find out using the query types possible for snmp-query-type 1 (SNMP - Interface Statistics):</p>
185<pre><code>$ sudo ./add_graphs.php --snmp-query-id=1 --list-query-types
186
187Known SNMP Query Types: (id, name)
1882   In/Out Errors/Discarded Packets
1893   In/Out Non-Unicast Packets
1904   In/Out Unicast Packets
1919   In/Out Bytes (64-bit Counters)
19213  In/Out Bits
19314  In/Out Bits (64-bit Counters)
19416  In/Out Bytes
19520  In/Out Bits with 95th Percentile
19621  In/Out Bits with Total Bandwidth
19722  In/Out Bytes with Total Bandwidth</code></pre>
198<p>Let's graph Ib/Out Bits (64-bit Counters) - that is #14. This is option <code>--snmp-query-type-id</code></p>
199<h2 id="find-which-interfaces-to-graph-on-this-host"><a href="#find-which-interfaces-to-graph-on-this-host"><span class="header-section-number">4.4</span> Find which interfaces to graph on this host</a></h2>
200<p>We need to tell Cacti <em>which</em> interfaces we will be creating graphs for on our device, using the two options of the add_graphs.php command <code>--snmp-field</code> and <code>--snmp-value</code></p>
201<pre><code>$ sudo ./add_graphs.php --host-id=2 --list-snmp-fields
202
203Known SNMP Fields for host-id 2: (name)
204ifAlias
205ifDescr
206ifHighSpeed
207ifHwAddr
208ifIndex
209ifIP
210ifName
211ifOperStatus
212ifSpeed
213ifType</code></pre>
214<p>We're only really interested in interfaces of type ethernet, therefore we'll use the &quot;ifType&quot; SNMP field to narrow down our search.</p>
215<p>To find out how to specify the &quot;ethernet&quot; type...:</p>
216<pre><code>$ sudo ./add_graphs.php --host-id=2 --snmp-field=ifType --list-snmp-values
217       
218Known values for ifType for host 3: (name)
219ethernetCsmacd(6)
220other(1)</code></pre>
221<p>ethernet is 'ethernetCsmacd(6)'</p>
222<p>Wow!</p>
223<p>The final command:</p>
224<pre><code>$ sudo ./add_graphs.php --host-id=2 --snmp-query-id=1 --snmp-query-type-id=14 \
225  --snmp-field=ifType --snmp-value=&#39;ethernetCsmacd(6)&#39; --graph-template-id=2 \
226  --graph-type=ds</code></pre>
227<p>You should see something similar to this:</p>
228<pre><code>    Graph Added - graph-id: (5) - data-source-ids: (8, 8)
229    Graph Added - graph-id: (6) - data-source-ids: (9, 9)</code></pre>
230<p>... why two graphs? One for each interface if this is your Cisco router.</p>
231<p>Check in the Web UI that the graphs have been create (Devices -&gt; select your host -&gt; Graph List)</p>
232<h2 id="note"><a href="#note"><span class="header-section-number">4.5</span> NOTE:</a></h2>
233<p>We could have picked another criteria to decide which interfaces to graph. For example &quot;Only graph interfaces that are 'up'&quot;. To find out how, look at the examples at the end of this lab.</p>
234<h1 id="add-graph-items-to-the-tree"><a href="#add-graph-items-to-the-tree"><span class="header-section-number">5</span> 3. Add graph items to the tree</a></h1>
235<p>The last step is to add these graphs to the Graph Tree.</p>
236<p>Check the possible options for this command:</p>
237<pre><code>$ sudo ./add_tree.php | less</code></pre>
238<p>Note the following options:</p>
239<pre><code>--type=[tree|node]
240--node-type=[header|host|graph]
241--tree-id=[ID]</code></pre>
242<p>First, let's use the add_tree.php command to see if we have any trees created in our Cacti installation:</p>
243<pre><code>$ sudo ./add_tree.php --list-trees
244
245Known Trees:
246id  sort method         name
2471   Manual Ordering (No Sorting)    Default Tree</code></pre>
248<p>In the above example, we have one tree: Default.</p>
249<p>If you need to create a new tree, save some typing and create it directly in the Web UI, then run the <code>--list-trees</code> command again:</p>
250<pre><code>$ sudo ./add_tree.php --list-trees
251
252Known Trees:
253id  sort method         name
2541   Manual Ordering (No Sorting)    Default Tree
2552   Manual Ordering (No Sorting)    NETMGMT routers</code></pre>
256<p>Note: We could have created the tree using add_tree.php. (How?)</p>
257<p>Let's add all graphs for our device id 2 from earlier - we know that the device id is 2, the tree id is 2, we want to add a Graph node (not a subtree), and we want all graphs for the device (type = node), not just a single graph from that device.</p>
258<p>The final command:</p>
259<pre><code>$ sudo ./add_tree.php --host-id=2 --tree-id=2 --node-type=host --type=node</code></pre>
260<p>Added Node node-id: (8)</p>
261<p>Done! Check with the Web UI that the Graphs for the device have been placed in the tree.</p>
262<h2 id="additional-commands"><a href="#additional-commands"><span class="header-section-number">5.1</span> Additional commands</a></h2>
263<p>If you want to add interfaces that are 'Up' instead of just interfaces that are &quot;ethernet&quot;, replace &quot;ifType&quot; with &quot;ifOperStatus&quot; for <code>--snmp-field</code>, and replace <code>--snmp-value='ethernetCsmacd(6)'</code> with <code>--snmp-value=Up</code></p>
264<p>Example to add all OperUp interfaces:</p>
265<pre><code>./add_graphs.php --host-id=7 --graph-type=ds --graph-template-id=2 \
266    --snmp-query-id=1 --snmp-query-type-id=14 --snmp-field=ifOperStatus \
267    --snmp-value=Up</code></pre>
268<h2 id="summary-and-more-sample-commands"><a href="#summary-and-more-sample-commands"><span class="header-section-number">5.2</span> # Summary and more sample commands</a></h2>
269<pre><code>$ sudo ./add_graphs.php --list-hosts
270# choose your host ID from the list
271
272$ sudo ./add_graphs.php --list-graph-templates
273# 2 = Interface - Traffic (bits/sec)
274
275$ sudo ./add_graphs.php --list-snmp-queries
276# 1 = SNMP - Interface Statistics
277
278$ sudo ./add_graphs.php --list-query-types --snmp-query-id=1
279# 14 = In/Out Bits (64-bit Counters)
280
281$ sudo ./add_graphs.php --list-snmp-fields --host-id=2 --snmp-query-id=1
282# list includes ifType
283
284### Add all ifs of type ethernetCsmaCd (type 6) ###
285$ sudo ./add_graphs.php --list-snmp-values --host-id=2 --snmp-query-id=1 \
286  --snmp-field=ifType
287# Known values for ifType for host 2: (name)
288# ethernetCsmacd(6)
289# other(1)
290
291$ sudo ./add_graphs.php --host-id=2 --graph-type=ds --graph-template-id=2 \
292  --snmp-query-id=1 --snmp-query-type-id=14 --snmp-field=ifType \
293  --snmp-value=&#39;ethernetCsmacd(6)&#39;
294
295or:
296
297### Add all OperUp ifs: ###
298$ sudo ./add_graphs.php --list-snmp-values --host-id=2 --snmp-query-id=1 \
299  --snmp-field=ifOperStatus
300# Known values for ifOperStatus for host 2: (name)
301# Down
302# Up
303
304$ sudo ./add_graphs.php --host-id=2 --graph-type=ds --graph-template-id=2 \
305  --snmp-query-id=1 --snmp-query-type-id=14 --snmp-field=ifOperStatus \
306  --snmp-value=Up</code></pre>
307</body>
308</html>