|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 03-May-2022 | - |
| cgi/ | H | 03-May-2022 | - | 1,921 | 825 |
| debian/ | H | 11-Jun-2013 | - | 141 | 97 |
| etc/ | H | 03-May-2022 | - | 4,343 | 3,091 |
| examples/ | H | 11-Jun-2013 | - | 2,336 | 2,083 |
| lib/ | H | 03-May-2022 | - | 87 | 40 |
| share/ | H | 03-May-2022 | - | 170 | 161 |
| t/ | H | 11-Jun-2013 | - | 11,543 | 9,927 |
| utils/ | H | 03-May-2022 | - | 470 | 253 |
| website/ | H | 03-May-2022 | - | 9 | 5 |
| AUTHORS | H A D | 11-Jun-2013 | 1.6 KiB | 48 | 40 |
| CHANGELOG | H A D | 13-Sep-2014 | 20.3 KiB | 461 | 400 |
| INSTALL | H A D | 11-Apr-2014 | 6.1 KiB | 183 | 130 |
| MANIFEST | H A D | 11-Jun-2013 | 1.3 KiB | 76 | 75 |
| META.yml | H A D | 11-Jun-2013 | 862 | 33 | 32 |
| Makefile.PL | H A D | 11-Jun-2013 | 4.1 KiB | 107 | 97 |
| README | H A D | 11-Jun-2013 | 56.6 KiB | 1,579 | 1,139 |
| README.pod | H A D | 11-Jun-2013 | 54.3 KiB | 1,787 | 1,179 |
| TODO | H A D | 11-Jun-2013 | 2.6 KiB | 64 | 51 |
| install.pl | H A D | 13-Sep-2014 | 59.3 KiB | 1,890 | 1,419 |
| nagiosgraph.spec | H A D | 11-Jun-2013 | 6.8 KiB | 195 | 165 |
README
1Nagiosgraph
2
3 Nagiosgraph is an add-on to Nagios. Nagios monitors one or more services
4 on each host. nagiosgraph extracts information from the Nagios output,
5 processes it, then inserts it into one or more round-robin database (RRD)
6 files. CGI scripts display data from the RRD files as web pages. The CGI
7 output can be embedded directly into Nagios so that graphs show up like
8 other trend reports.
9
10 Installation is a three-step process. First install the nagiosgraph files,
11 then configure Nagios for data collection, and finally customize the
12 graphs and links as needed. Installation can be done manually by copying
13 files and modifying configuration files, or automatically using the
14 install.pl script.
15
16 The INSTALL file contains basic installation instructions.
17
18 This README file contains detailed instructions for installing, upgrading,
19 customizing, troubleshooting, and managing performance data.
20
21 Answers to frequently asked questions are at:
22
23 <https://sourceforge.net/apps/mediawiki/nagiosgraph>
24
25 For help, visit the forum at:
26
27 <http://sourceforge.net/projects/nagiosgraph/forums/forum/394748>
28
29Copyright and License
30
31 License: OSI Artistic License 2.0
32 http://www.opensource.org/licenses/artistic-license-2.0
33
34 Author: (c) 2005 Soren Dossing
35 Author: (c) 2008 Alan Brenner, Ithaka Harbors
36 Author: (c) 2010 Matthew Wall
37
38 Nagios is a registered trademark of Ethan Galstad.
39
40Contents
41
42 Principles of Operation
43 Installation Preliminaries
44 Prerequisites
45 Layout and Location
46 Installation Methods
47 Manual Installation
48 Install Script
49 Installation Using Packages
50 Installing nagiosgraph Files
51 Upgrade Notes
52 Configuring Data Processing
53 Batch Processing
54 Immediate Processing
55 Configuring Graphing and Display
56 Graph Icons and Links in Nagios
57 For Nagios 2.6 and Earlier
58 For Nagios 2.9 and Nagios 3
59 Graphs in Nagios Mouseovers
60 Graphs in Nagios Frames
61 Customizing the Graphs
62 Adding Service Types
63 Managing Data and RRD Files
64 Managing RRD Parameters
65 Configuring Access Controls
66 Troubleshooting
67 Internationalization
68 Enumeration of Files
69 Sample Installation Layouts
70 Sample Web Server Configuration
71 Platform Specific Notes
72 Nagios Embedded PERL (ePN)
73 CentOS 5 and Nagiosgraph 0.9
74 MacOSX 10.5 and Nagios 2.12
75 Fedora Core 6 and HTTP output parsing
76 Notes For Developers
77 Project Testing/Code Summary
78
79Principles of Operation
80
81 nagiosgraph is a simple interface between Nagios and RRD files.
82
83 nagiosgraph operates in two modes. One is to collect performance data from
84 Nagios servicechecks, and the other is to display graphs of the
85 performance data collected.
86
87 All the data collected are stored in RRD files using rrdtool. A file
88 called 'map' defines how to identify the data from Nagios and how to store
89 them in the RRD files. Nagios passes all the service data to a nagiosgraph
90 script called 'insert.pl'. This script uses the file 'map' to determine
91 how to name the data and into which RRD files to insert the data. The map
92 file also processes the data, for example by changing units or applying
93 scaling factors.
94
95 The 'map' file is actually perl code, that is eval'ed by 'insert.pl'. The
96 map file contains a general rule that will capture the performance data
97 from most plugins. However, it may be necessary to add entries to match
98 the output of some Nagios plugins. Several examples of servicechecks are
99 included in the distributed map file. Knowing perl regular expression is
100 helpful, but the examples supplied should cover most types of performance
101 data.
102
103 For graphing, nagiosgraph includes cgi scripts. 'show.cgi' looks up
104 performance data for a single host and service, and generates line charts
105 accordingly. Other scripts display all hosts for a specific service, all
106 services for a specific host, or arbitrary groups of hosts and services.
107 These run out-of-the-box with minimal configuration, or they can be
108 customized, using a configuration file or interactively.
109
110 Graphs can be integrated into Nagios using Nagios' extended information
111 for services and hosts. By specifying nagiosgraph cgi scripts in the
112 Nagios configuration, individual graphs and collections of graphs can be
113 linked directly to hosts and services in Nagios web pages.
114
115 By default, all available data for a servicecheck will be displayed in the
116 same graph. With extra configuration, either embedded in the url,
117 specified in a configuration file, or using controls in a web page, it is
118 possible to display less data or to split values into multiple graphs.
119 There is also a general method for specifying arbitrary RRD graph options
120 such as line style, color, and scaling for individual hosts or services.
121
122Installation Preliminaries
123
124 Before installing, ensure that the prerequisite software has been
125 installed then decide upon a layout and location.
126
127 Prerequisites
128
129 Nagiosgraph will not function without a working Nagios installation, so
130 first ensure that Nagios works. Version 3.2 or later is recommended, but
131 older versions will also work.
132
133 Nagiosgraph requires rrdtool. Version 1.4 or later is recommended, but
134 older versions will also work.
135
136 Nagiosgraph requires the CGI and RRDs perl modules. The RRDs perl module
137 is part of rrdtool but is often distributed as a separate package. The GD
138 perl module is optional, but recommended. The Nagios::Object perl module
139 is optional, but useful for automatic configuration of showgroup.cgi.
140
141 Debian/Ubuntu:
142
143 apt-get install libcgi-pm-perl librrds-perl
144 apt-get install libgd-gd2-perl libnagios-object-perl
145
146 Redhat/Fedora/CentOS:
147
148 yum install perl-rrdtool perl-GD
149
150 SUSE:
151
152 rrdtool, perl-GD
153
154 Solaris:
155
156 rrdtool, gd
157
158 FreeBSD:
159
160 rrdtool, gd
161
162 OpenBSD:
163
164 p5-RRD, p5-GD
165
166 The install.pl script includes an option to check for pre-requisites:
167
168 install.pl --check-prereq
169
170 Layout and Location
171
172 There are two standard layouts: separate or overlay. The separated layout
173 has nagiosgraph and Nagios in separate directories. The overlay places
174 nagiosgraph components with Nagios components.
175
176 Nagios and nagiosgraph can be installed in just about any location, for
177 example /opt or /usr/local.
178
179 Redhat (Fedora, CentOS), SUSE, and Debian (Ubuntu) systems have their own
180 layouts. If you installed Nagios from a package, you can overlay
181 nagiosgraph or you can install nagiosgraph to its own standalone location.
182
183 When installing from source, the standalone layout is highly recommended
184 since it makes updates much easier.
185
186 Decide upon a location and layout before you start the installation.
187 Examples are in the Sample Installation Layouts section.
188
189 Installation Methods
190
191 There are a few ways to install nagiosgraph: manual, script, and package.
192 On most systems the installation requires root permissions, so either do
193 the installation as root or preface commands with sudo.
194
195 Manual Installation
196
197 Copy and edit files directly. Follow the recipe in the INSTALL file, or
198 the instructions in these sections of this file:
199
200 * "Installing nagiosgraph Files" - nagiosgraph installation
201
202 * "Configuring Data Processing" - Nagios configuration
203
204 * "Configuring Graphing and Display" - Apache and Nagios configuration
205
206 Install Script
207
208 Run the install.pl script. It will prompt you for the parameters it needs,
209 then it will copy and configure nagiosgraph files. It will also prompt you
210 to modify apache and Nagios configuration files.
211
212 install.pl --prefix=/usr/local/nagiosgraph
213 install.pl --help
214
215 Installation Using Packages
216
217 The nagiosgraph packages assume that Nagios and apache were installed from
218 packages. Do not use a nagiosgraph package if you installed Nagios or
219 apache from source!
220
221 Debian, Ubuntu
222
223 dpkg -i nagiosgraph-x.y.z.deb
224
225 Redhat, Fedora, CentOS, SUSE
226
227 rpm -i nagiosgraph-x.y.z.rpm
228
229Installing nagiosgraph Files
230
231 These instructions assume a standalone layout, with Nagios at
232 /usr/local/nagios and nagiosgraph at /usr/local/nagiosgraph
233
234 1. Create destination directories:
235
236 mkdir /usr/local/nagiosgraph
237 mkdir /usr/local/nagiosgraph/bin
238 mkdir /usr/local/nagiosgraph/cgi-bin
239 mkdir /usr/local/nagiosgraph/etc
240 mkdir /usr/local/nagiosgraph/share
241
242 2. Extract nagiosgraph into a temporary location:
243
244 cd /tmp
245 tar xzvf nagiosgraph-x.y.z.tgz
246
247 3. Copy the contents of etc into your preferred configuration location:
248
249 cp etc/* /usr/local/nagiosgraph/etc
250
251 4. Edit the perl scripts in the cgi and lib directories, modifying the
252 "use lib" line to point to the directory from the previous step.
253
254 vi cgi/*.cgi lib/insert.pl
255
256 5. Copy insert.pl to a location from which it can be executed:
257
258 cp lib/insert.pl /usr/local/nagiosgraph/bin
259
260 6. Copy CGI scripts to a script directory served by the web server:
261
262 cp cgi/*.cgi /usr/local/nagiosgraph/cgi-bin
263
264 7. Copy CSS and JavaScript files to a directory served by the web server:
265
266 cp share/nagiosgraph.css /usr/local/nagiosgraph/share
267 cp share/nagiosgraph.js /usr/local/nagiosgraph/share
268
269 8. Edit nagiosgraph.conf. Set at least the following:
270
271 logfile = /var/log/nagiosgraph.log
272 cgilogfile = /var/log/nagiosgraph-cgi.log
273 perflog = /var/nagios/perfdata.log
274 rrddir = /var/nagios/rrd
275 mapfile = /usr/local/nagiosgraph/etc/map
276 nagiosgraphcgiurl = /nagiosgraph/cgi-bin
277 javascript = /nagiosgraph/nagiosgraph.js
278 stylesheet = /nagiosgraph/nagiosgraph.css
279
280 9. Set permissions of "rrddir" (as defined in nagiosgraph.conf) so that
281 the *nagios* user can write to it and the *www* user can read it:
282
283 mkdir /var/nagios/rrd
284 chown nagios /var/nagios/rrd
285 chmod 755 /var/nagios/rrd
286
287 10. Set permissions of "logfile" so that the *nagios* user can write to
288 it:
289
290 touch /var/log/nagiosgraph.log
291 chown nagios /var/log/nagiosgraph.log
292 chmod 644 /var/log/nagiosgraph.log
293
294 11. Set permissions of "cgilogfile" so that the *www* user can write to
295 it:
296
297 touch /var/log/nagiosgraph-cgi.log
298 chown www /var/log/nagiosgraph-cgi.log
299 chmod 644 /var/log/nagiosgraph-cgi.log
300
301 12. Ensure that the *nagios* user can create and delete perfdata files:
302
303 chown nagios /var/nagios
304 chmod 755 /var/nagios
305
306Upgrade Notes
307
308 * Follow the steps for a new installation, but keep your customizations.
309 Your changes should be limited to the map file (map), configuration
310 files (nagiosgraph.conf and other .conf files), and the stylesheet
311 (nagiosgraph.css).
312
313 * Use diff, or a similar tool, to update your nagiosgraph.conf with any
314 new fields from etc/nagiosgraph.conf
315
316 * Use diff, or a similar tool, to update your nagiosgraph.css with
317 changes from share/nagiosgraph.css.
318
319 * You may want to look at etc/map or the files in the examples directory
320 to see if there are any map rules or CSS useful to your configuration.
321
322 * If you change from immediate processing to batch processing, be sure
323 to comment out service_perfdata_command in the Nagios configuration.
324
325 * Be sure to install the nagiosgraph.js and nagiosgraph.css files,
326 especially if you are upgrading from nagiosgraph older than 1.2.
327
328 * If you are upgrading from nagiosgraph 1.4.1 or earlier, move your
329 service and database/datasource labels from nagiosgraph.conf to
330 labels.conf.
331
332 * If you are upgrading from nagiosgraph 1.4.3 or earlier and you were
333 using nagios3 for the authzmethod, you must replace authz_nagios_cfg
334 and authz_cgi_cfg with authzfile. All of the Nagios authorization
335 parameters should be in the Nagios CGI configuration file (typically
336 cgi.cfg).
337
338 * If you are upgrading from nagiosgraph 1.4.3 or earlier, you might want
339 to add the generic map rule to the end of your map file. This rule
340 will catch performance data from any additional plugins you add. Using
341 the generic rule results in RRD files with the following structure,
342 one file per named performance data element, with one or more data
343 sources:
344
345 host0/service___label (data[,warn][,crit][,min][,max])
346
347 * If you are upgrading from nagiosgraph 1.4.3 or earlier, you should
348 make any ignore map rules explicit. For example, in the map file
349 change this:
350
351 /output:CHECK_NRPE: Socket timeout/
352 and return;
353
354 to this:
355
356 /output:CHECK_NRPE: Socket timeout/
357 and return ('ignore');
358
359Configuring Data Processing
360
361 Before nagiosgraph can graph anything it must first collect data. There
362 are two ways to process data - batch and immediate. Batch processing is
363 usually appropriate for most Nagios deployments. Immediate processing
364 typically requires more CPU and I/O.
365
366 In batch processing, performance data are appended to a file, then Nagios
367 invokes insert.pl at a regular interval to update the RRD files.
368
369 In immediate processing, Nagios invokes insert.pl immediately after each
370 service check, thus updating the corresponding RRD files.
371
372 Batch Processing
373
374 1. In the Nagios configuration file (nagios.cfg) set:
375
376 process_performance_data=1
377 service_perfdata_file=/var/nagios/perfdata.log
378 service_perfdata_file_template=$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$
379 service_perfdata_file_mode=a
380 service_perfdata_file_processing_interval=30
381 service_perfdata_file_processing_command=process-service-perfdata
382
383 Make sure that service_perfdata_command is either commented out or not
384 defined.
385
386 Make sure that location of service_perfdata_file matches that of
387 perflog defined in nagiosgraph.conf.
388
389 2. In the Nagios commands file (commands.cfg) define the
390 process-service-perfdata command:
391
392 define command {
393 command_name process-service-perfdata
394 command_line /usr/local/nagiosgraph/bin/insert.pl
395 }
396
397 Make sure there is only one definition for process-service-perfdata.
398
399 Older versions of Nagios used checkcommands.cfg or misccommands.cfg.
400
401 3. Check the Nagios configuration
402
403 /usr/local/nagios/bin/nagios -v /usr/local/nagios/etc/nagios.cfg
404
405 4. Restart Nagios
406
407 /etc/init.d/nagios restart
408
409 Immediate Processing
410
411 1. In nagios.cfg:
412
413 process_performance_data=1
414 service_perfdata_command=process-service-perfdata
415
416 Make sure that service_perfdata_file_processing_command is either
417 commented out or not defined.
418
419 2. In commands.cfg:
420
421 define command{
422 command_name process-service-perfdata
423 command_line /usr/local/nagiosgraph/bin/insert.pl "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
424 }
425
426 3. Check the Nagios configuration
427
428 /usr/local/nagios/bin/nagios -v /usr/local/nagios/etc/nagios.cfg
429
430 4. Restart Nagios
431
432 /etc/init.d/nagios restart
433
434Configuring Graphing and Display
435
436 First configure the web server to run the nagiosgraph CGI scripts. For
437 example, with Apache do something like this in the Apache configuration:
438
439 ScriptAlias /nagiosgraph/cgi-bin /usr/local/nagiosgraph/cgi-bin
440 <Directory "/usr/local/nagiosgraph/cgi-bin">
441 Options ExecCGI
442 AllowOverride None
443 Order allow,deny
444 Allow from all
445 </Directory>
446 Alias /nagiosgraph "/usr/local/nagiosgraph/share"
447 <Directory "/usr/local/nagiosgraph/share">
448 Options None
449 AllowOverride None
450 Order allow,deny
451 Allow from all
452 </Directory>
453
454 Restart the web server:
455
456 /etc/init.d/apache2 restart
457
458 Verify that nagiosgraph is working by running showconfig.cgi
459
460 http://server/nagiosgraph/cgi-bin/showconfig.cgi
461
462 Try graphing some data by running show.cgi
463
464 http://server/nagiosgraph/cgi-bin/show.cgi
465
466 This should display a web page with a list of your hosts and services.
467 Note that it might take a few minutes for data to collect, so at first the
468 list of hosts and services might be sparse and the graphs might be empty.
469
470 There are a few ways to embed graphs into Nagios. In the service and host
471 listings, Nagios will display graph icons that, when clicked, will open a
472 new web page with graphs. These icons are typically per-host (linked to
473 the showhost.cgi script) or per-host-service (linked to the show.cgi
474 script). Nagios will display graph data when the mouse is moved over the
475 graph icon for each host/service. Finally, graphs can be displayed
476 directly in the Nagios frames. The following sections explain how to do
477 each of these.
478
479 Graph Icons and Links in Nagios
480
481 Links to graphs can be embedded in Nagios status pages using the notes or
482 actions fields. The specifics depend on the Nagios version as well as how
483 you have configured your host and service definitions. Nagios 2 uses the
484 serviceextinfo and hostextinfo construct. In Nagios 3 the nagiosgraph
485 additions go directly in the host and service definitions.
486
487 To display a graph icon instead of the Nagios action icon, replace
488 nagios/images/action.gif with graph.gif from the nagiosgraph distribution.
489
490 In its default configuration, Nagios will create a new window for each
491 action or notes link. To display graphs in the Nagios frame instead of a
492 new window, set action_url_target=main in the Nagios cgi.cfg file.
493
494 For Nagios 2.6 and Earlier
495
496 If you have these lines in nagios.cfg, un-comment the 2 cfg_file= lines:
497
498 # Extended host/service info definitions are now stored along with
499 # other object definitions:
500 # cfg_file=/etc/nagios/hostextinfo.cfg
501 # cfg_file=/etc/nagios/serviceextinfo.cfg
502
503 Otherwise, define in cgi.cfg the following:
504
505 xedtemplate_config_file=/usr/local/nagios/etc/serviceextinfo.cfg
506
507 Edit/Create hostextinfo.cfg
508
509 define hostextinfo {
510 host_name your-host
511 action_url /nagiosgraph/cgi-bin/showhost.cgi?host=$HOSTNAME$
512 }
513
514 This must be the host you will use in serviceextinfo.cfg
515
516 Edit/Create serviceextinfo.cfg
517
518 define serviceextinfo {
519 service_description DNS
520 hostgroup servers
521 notes_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
522 icon_image graph.gif
523 icon_image_alt View graphs
524 }
525
526 For Nagios 2.9 and Nagios 3
527
528 Use the action_url for any existing host or service definition. For
529 example,
530
531 define service {
532 name NTP
533 use local-service
534 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
535 ...
536 }
537
538 define host {
539 host_name web-server
540 action_url /nagiosgraph/cgi-bin/showhost.cgi?host=$HOSTNAME$
541 ...
542 }
543
544 To apply graph links to multiple services, define a template such as this:
545
546 define service {
547 name graphed-service
548 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
549 register 0
550 }
551
552 Then use it in services like this:
553
554 define service {
555 name NTP
556 use local-service,graphed-service
557 ...
558 }
559
560 Graphs in Nagios Mouseovers
561
562 To display graphs as mouseovers for each host and/or service, do the
563 following:
564
565 1. Edit the file share/nagiosgraph.ssi to contain the URL to the
566 nagiosgraph javascript file (e.g. /nagiosgraph/nagiosgraph.js)
567
568 2. If you have not customized the Nagios SSI, copy share/nagiosgraph.ssi
569 to the Nagios ssi directory, and rename it so that Nagios will insert
570 it into each page. For example:
571
572 cp share/nagiosgraph.ssi /usr/local/nagios/share/ssi/common-header.ssi
573
574 If you have customized Nagios SSI, add the contents of
575 share/nagiosgraph.ssi to your customized SSI header file.
576
577 3. Configure services to display graphs on mouseovers by adding some
578 JavaScript to action_url or notes_url. For example:
579
580 define service {
581 name NTP
582 use local-service
583 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$' onMouseOver='showGraphPopup(this)' onMouseOut='hideGraphPopup()' rel='/nagiosgraph/cgi-bin/showgraph.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
584 ...
585 }
586
587 This example displays a week of data in a popup with no legend:
588
589 define service {
590 name NTP
591 use local-service
592 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$' onMouseOver='showGraphPopup(this)' onMouseOut='hideGraphPopup()' rel='/nagiosgraph/cgi-bin/showgraph.cgi?host=$HOSTNAME$&service=$SERVICEDESC$&period=week&rrdopts=-w+450+-j
593 ...
594 }
595
596 You must restart Nagios for changes to service/host defintions to take
597 effect.
598
599 If a service includes multiple data sources, use the datasetdb file
600 (specified in nagiosgraph.conf) to indicate which data sources should be
601 displayed by default for each service, or specify the data source(s)
602 explicity in each action_url.
603
604 Graphs in Nagios Frames
605
606 To embed nagiosgraph graphs directly into Nagios, do the following:
607
608 Modify side.php (e.g. /usr/local/nagios/share/side.php) by inserting
609 bullets under the 'Trends' heading:
610
611 <li><a href="<?php echo $cfg["cgi_base_url"];?>/trends.cgi" target="<?php echo $link_target;?>">Trends</a>
612 <ul>
613 <li><a href="<?php echo $cfg["cgi_base_url"];?>/show.cgi" target="<?php echo $link_target;?>">Graphs</a></li>
614 <li><a href="<?php echo $cfg["cgi_base_url"];?>/showhost.cgi" target="<?php echo $link_target;?>">Graphs by Host</a></li>
615 <li><a href="<?php echo $cfg["cgi_base_url"];?>/showservice.cgi" target="<?php echo $link_target;?>">Graphs by Service</a></li>
616 <li><a href="<?php echo $cfg["cgi_base_url"];?>/showgroup.cgi" target="<?php echo $link_target;?>">Graphs by Group</a></li>
617 </ul>
618 </li>
619
620 If you keep the nagiosgraph cgi scripts in a location different than the
621 Nagios cgi scripts, then use 'ng_cgi_base_url' rather than 'cgi_base_url'
622 and make an entry in config.inc.php such as this:
623
624 $cfg['cgi_base_url']='/nagios/cgi-bin';
625 $cfg['ng_cgi_base_url']='/nagiosgraph/cgi-bin';
626
627 Some Nagios installations have side.html instead of side.php:
628
629 <li><a href="/nagios/cgi-bin/trends.cgi" target="main">Trends</a>
630 <ul>
631 <li><a href="/nagiosgraph/cgi-bin/show.cgi" target="main">Graphs</a></li>
632 <li><a href="/nagiosgraph/cgi-bin/showhost.cgi" target="main">Graphs by Host</a></li>
633 <li><a href="/nagiosgraph/cgi-bin/showservice.cgi" target="main">Graphs by Service</a></li>
634 <li><a href="/nagiosgraph/cgi-bin/showgroup.cgi" target="main">Graphs by Group</a></li>
635 </ul>
636 </li>
637
638Customizing the Graphs
639
640 The look and feel of nagiosgraph is controlled by the cascading style
641 sheets defined in nagiosgraph.css. The examples directory contains a
642 stylesheet file with sample style sheets for fixing the controls to the
643 page, floating the controls above the graphs, or hiding the controls
644 altogether.
645
646 Graphs can be customized individually by specifying CGI arguments, or they
647 can be customized overall by specifying values in the configuration files.
648 Some parameters apply to each page, others apply to each service, and
649 others apply to each data source.
650
651 The following CGI arguments are recognized by show.cgi, showhost.cgi,
652 showservice.cgi, and showgroup.cgi:
653
654 hidengtitle Do not display the nagiosgraph title in the page.
655
656 geom=WxH Set the dimensions of all graphs to W pixels wide and H
657 pixels tall.
658
659 showtitle Display a title next to each graph.
660
661 showdesc Display a description of data sources next to each graph.
662
663 showgraphtitle Display a title in each graph.
664
665 graphonly Display only graph data, not axes, grid, or legend.
666
667 hidelegend Do not display the legend in each graph.
668
669 fixedscale Set the Y-axis to be in the same scale as the performance
670 data. This is useful to prevent a variety of vertical
671 scales when autoscaling results in different vertical
672 scaling for each graph.
673
674 The following options are available via configuration files:
675
676 rrdopts Use the rrdopts option to specify custom RRD graphing
677 options. These can be specified for all graphs using
678 rrdopts, or per-service using the rrdoptsfile.
679
680 lineformat Use lineformat to control the line thickness and line
681 color for individual data sources. The alpha channel is
682 respected if a recent version of rrdtool is installed.
683
684 plotas, plotasLINE1, plotasLINE2, plotasLINE3, plotasAREA, plotasTICK
685 Use plotas to control the line thickness/style for
686 individual data sources.
687
688 stack Create stacked area graphs using the stack directive for
689 individual data sources, the STACK directive in
690 lineformat, or by adjusting the alpha channel in specified
691 colors.
692
693 Some services emit multiple data sources with big differences in
694 magnitude. Others emit data with different units. In such cases, split the
695 data into seperate graphs by specifying one or more data sources. For
696 example, for the NTP service, jitter and offset are typically in the same
697 range, while stratum is orders of magnitude larger. So we specify two
698 different graphs:
699
700 show.cgi?host=HOST&service=NTP&db=ntp,jitter&db=ntp,offset
701 show.cgi?host=HOST&service=NTP&db=ntp,stratum
702
703 This assumes that jitter, offset, and stratum are all stored in a single
704 RRD file using a map entry such as:
705
706 /output:NTP.*Offset ([-.0-9]+).*jitter ([-.0-9]+).*stratum (\d+)/
707 and push @s, [ 'ntp',
708 [ 'offset', GAUGE, $1 ],
709 [ 'jitter', GAUGE, $2/1000 ],
710 [ 'stratum', GAUGE, $3+1 ] ];
711
712 Data are identified by host, service, database, and data source. It is
713 possible to graph all sources from a single database, a single source from
714 a database, selected sources from a single database, or selected sources
715 from multiple databases. In each case, the host and service must match.
716 For example:
717
718 showgraph.cgi?host=HOST&service=SERVICE&db=loss
719 showgraph.cgi?hsot=HOST&service=SERVICE&db=loss,losspct
720 showgraph.cgi?host=HOST&service=SERVICE&db=ntp,jitter,offset
721 showgraph.cgi?host=HOST&service=SERVICE&db=loss,losspct&db=rta,rta
722
723 These options apply to showgraph.cgi, show.cgi, and showservice.cgi and in
724 the configuration files hostdb.conf, groupdb.conf, and datasetdb.conf.
725
726 Use URLs as canned queries. For example, define a 'temperatures' group in
727 the groupdb.conf file that combines temperature data from multiple hosts
728 and service types, then create a link to that group:
729
730 http://server/cgi-bin/showgroup.cgi?group=temperatures
731
732 See the configuration files for more options and examples.
733
734Adding Service Types
735
736 Service types are added by creating rules in the 'map' file. The map file
737 determines how data from Nagios will be stored. Each rule determines how
738 output and performance data should be recorded.
739
740 The map file contains regular expressions to identify service types and
741 define content in RRD files. All entries are written in perl, so editing,
742 adding or deleting entries requires some perl programming knowledge.
743 Knowledge of RRD is also helpful.
744
745 There has to be one entry for each type of service. The map file included
746 with nagiosgraph has several examples for cpu, memory, disk, network etc.
747 Most examples identify data from either Nagios output or Nagios perfdata
748 then define a number of RRD data sources. There is also a generic rule
749 that will capture output from any plugin that adheres to the Nagios
750 standards for plugin performance data.
751
752 insert.pl receives data from Nagios. It formats data into a string
753 consisting of four lines of text. This string might look like this:
754
755 hostname:host0
756 servicedesc:ping
757 output:PING OK - Packet loss = 0%, RTA = 0.00 ms
758 perfdata:
759
760 Or like this:
761
762 hostname:host0
763 servicedesc:CPU Load
764 output:OK - load average: 0.06, 0.12, 0.10
765 perfdata:load1=0;15;30;0 load5=0;10;25;0 load15=0;5;20;0
766
767 The official perfdata format is a space-delimited list of qualified
768 name-value pairs with this format:
769
770 name=value[units];[warn];[crit];[min];[max]
771
772 where units is one of:
773
774 - unitless
775 s,us,ms - time
776 % - percentage
777 B,KB,MB,GB,TB,PB - bytes
778 c - counter
779
780 However, the perfdata is not always set, and the format of perfdata varies
781 a great deal from plugin to plugin. So depending on type of service, the
782 most useful data can be in either the output or perfdata line.
783
784 For the ping example above, data can be extracted from the output line
785 with a regular expression like this:
786
787 /output:PING.*?(\d+)%.+?([.\d]+)\sms/
788
789 In this case, two values are extracted and available in $1 and $2. We can
790 then create a data structure describing the content of the database. The
791 general format is
792
793 [ db-name,
794 [ DS-name, TYPE, DS-value ],
795 [ DS-name, TYPE, DS-value ],
796 ...
797 ]
798
799 Where DS name is the name that will be assigned to a line showing on RRD
800 graphs. Each DS name must be no longer than 19 characters and must contain
801 only the characters A-Z, a-z, 0-9, or underscore. TYPE is either GAUGE or
802 DERIVE. the DS value is the data extracted in the regular expression. The
803 DS value can be an expression, for example to normalize to SI units.
804
805 Each database definition must be added to the @s array.
806
807 So the complete code to define and insert into an RRD file for the PING
808 example above, becomes:
809
810 /output:PING.*?(\d+)%.+?([.\d]+)\sms/
811 and push @s, [ ping,
812 [ losspct, GAUGE, $1 ],
813 [ rta, GAUGE, $2/1000 ] ];
814
815 In this case the database name is called 'ping' and the DS-names stored
816 are losspct and rta. The Nagios output reports round trip time in
817 milliseconds, so the value is divided by 1000 to convert to seconds. The
818 type for each DS is GAUGE.
819
820 Be careful about the database names and DS names. In the code example
821 above the names are barewords, which only works as long as the don't
822 conflict with perl functions or subroutines. For example the word 'sleep'
823 will not work without quoting.
824
825 A safer version of the above example is
826
827 /output:PING.*?(\d+)%.+?([.\d]+)\sms/
828 and push @s, [ 'ping',
829 [ 'losspct', 'GAUGE', $1 ],
830 [ 'rta', 'GAUGE', $2/1000 ] ];
831
832 After editing the map file, the syntax can be checked with
833
834 perl -c map
835
836 Again a word of caution. If the map file has syntax errors, nothing will
837 be inserted into RRD files until the file is fixed. So do not edit
838 production map files. Instead do something like this:
839
840 cp map map.edit
841 vi map.edit
842 perl -c map.edit
843 mv map.edit map
844
845 Use testentry.pl to test a rule before putting it into production. First
846 run the Nagios check command from the command line to see what is
847 returned. Copy this output and paste it into testentry.pl. Paste the rule
848 into testentry.pl. Run testentry.pl to see how the output will be handled.
849
850 Changes to the map file generally do not require a restart of Nagios.
851
852 It may take awhile for data from a map entry to show up in an RRD file.
853 This is partly due to the service check scheduling in Nagios, and partly
854 due to the perfdata buffering of service_perfdata_file_processing_interval
855
856 Increase debug level in nagiosgraph.conf to see what is happening. The
857 debug_insert parameter determines the log level for collecting data.
858 Output will go to the nagiosgraph log file. Keep an eye on the log file;
859 it can grow big. Perhaps rotate it, or decrease log level when everything
860 works.
861
862 Share your work. If you have a good map file entry for standard Nagios
863 plugins, then please post it on the forum.
864
865Managing Data and RRD Files
866
867 nagiosgraph saves data in RRD files in the rrddir directory (specified in
868 nagiosgraph.conf). By default, nagiosgraph uses a directory for each host,
869 and the RRD files are named based on the service description (from Nagios)
870 and the data names (from the map file). For example, the default
871 configuration for the PING service results in RRD files like this:
872
873 /var/nagiosgraph/rrd/host/PING___pingloss.rrd
874 /var/nagiosgraph/rrd/host/PING___pingrta.rrd
875
876 Older versions of nagiosgraph kept all RRD files in a single directory.
877 This is controlled by the dbseparator variable in nagiosgraph.conf.
878
879 Use the 'dump' and 'restore' options to rrdtool if you need to restructure
880 RRD files. You might want to split data from a single RRD file into
881 multiple files, or you might want to combine data from multiple RRD files
882 into a single file. Or you might simply want to change the name of a data
883 source. The dump option will emit data in XML format:
884
885 rrdtool dump service___db.rrd > service_db.xml
886
887 You can modify the XML with any text editor, then convert to RRD format:
888
889 rrdtool restore service_db.xml service___db-new.rrd
890
891 Unfortunately the RRD file schema is not dynamic. If an RRD file is
892 created with 2 data sources, more data sources cannot be added
893 automatically. For example, you start recording UPS temperature to an RRD
894 file using the following map rule:
895
896 /perfdata:temperature=([.\d]+)/
897 and push @s, [ 'temp',
898 [ 'temperature', GAUGE, $1 ] ];
899
900 Later you decide to include critical and warning temperatures using this
901 map rule:
902
903 /perfdata:temperature=([.\d]+);([.\d]+);([.\d]+)/
904 and push @s, [ 'temp',
905 [ 'temperature', GAUGE, $1 ],
906 [ 'warn', GAUGE, $2 ],
907 [ 'crit', GAUGE, $3 ] ];
908
909 The new rule will still record temperature, but critical and warning
910 values will be discarded, because they are not defined in the RRD file.
911 You must do a dump/edit/restore on the RRD file if you want to add
912 critical/warning while maintaining existing temperature data.
913 Alternatively you can simply delete the existing RRD file and let the new
914 map rule create the new RRD file.
915
916 What is the 'right' way to configure RRD files? Should all data from a
917 single service go into a single RRD file? Should each RRD file contain a
918 single set of data? Some best practices have evolved over the past 10
919 years, but as of this writing (febrary 2010) there is no single 'right'
920 way.
921
922 Some people prefer to put all data from a single service into a single RRD
923 file, even if the data have different units. For example, for the PING
924 service their RRD files look something like this:
925
926 PING___ping.rrd (losspct, losswarn, losscrit, rta, rtawarn, rtacrit)
927
928 Others prefer a separate file for each data source:
929
930 PING___losspct.rrd (losspct)
931 PING___losswarn.rrd (losswarn)
932 PING___losscrit.rrd (losscrit)
933 PING___rta.rrd (rta)
934 PING___rtawarn.rrd (rtawarn)
935 PING___rtacrit.rrd (rtacrit)
936
937 And others prefer something in between:
938
939 PING___loss.rrd (losspct, losswarn, losscrit)
940 PING___rta.rrd (rta, rtawarn, rtacrit)
941
942 It is a good idea to plan your configuration before you start recording
943 data. Although it is possible to reconfigure data after the RRD files are
944 full, doing so is somewhat tedious, especially for large numbers of
945 hosts/services.
946
947 The 1.4.4 release of nagiosgraph added a generic map rule that matches any
948 standard performance data. This rule puts the data into RRD files using
949 this structure:
950
951 host0/service___label.rrd (data[,warn][,crit][,min][,max])
952
953 For example, for service0 with 3 perfdata labels and service1 with 1
954 perfdata labels, the rule generates the following RRD files:
955
956 host0/service0___label0.rrd (data[,warn][,crit][,min][,max])
957 host0/service0___label1.rrd (data[,warn][,crit][,min][,max])
958 host0/service0___label2.rrd (data[,warn][,crit][,min][,max])
959 host0/service1___label0.rrd (data[,warn][,crit][,min][,max])
960
961 There are a few rrdtool parameters that affect size of the RRD files and
962 the resolution of data:
963
964 stepsize
965 resolution
966 heartbeat
967 step
968
969 These parameters are used only when an RRD file is created. By default
970 they are the same for all hosts and services, but they can be specified
971 for individual hosts, services, and or databases in the nagiosgraph
972 configuration file. To modify these values for an existing RRD file you
973 must do a dump/edit/restore. See the rrdtool documentation for details.
974
975Managing RRD Parameters
976
977 The most important parameters are stepsize, heartbeat, and sampling
978 interval. A typical sign that these parameters are not set correctly is
979 values of NaN in the RRD files, which manifests as gaps in the graphs or
980 empty graphs.
981
982 A good rule of thumb is to use a heartbeat that is twice the sampling
983 interval and a stepsize equal to the sampling interval.
984
985 In a default nagiosgraph configuration, the same parameters are applied to
986 all hosts and services. However, they can be specified for individual
987 hosts and services if necessary.
988
989 The stepsize, in seconds, defines the nominal amount of time between data
990 points. The default value is 300 (5 minutes). The heartbeat, in seconds,
991 defines the amount of time between updates before a data point should be
992 considered unknown. The default value is 600 (10 minutes). The resolution
993 defines how many data points should be kept. The step defines how data
994 points are consolidated. The xfiles factor defines how unknown data points
995 are considered when consolidating data. These parameters are specified in
996 the nagiosgraph configuration file.
997
998 The sampling interval is defined in Nagios (check_interval). This defines
999 how often a service will be checked.
1000
1001 These values are used only when an RRD file is created. To change the
1002 stepsize, heartbeat, or resolution of an existing RRD, one must dump the
1003 RRD file to XML, modify the data, then restore the RRD file. Or simply
1004 delete the RRD file and let nagiosgraph create a new one.
1005
1006Configuring Access Controls
1007
1008 nagiosgraph does authorization (authz), not authentication (authn). Access
1009 is granted or denied to users for specific services and hosts. There are
1010 two ways to configure authorization: using Nagios configuration files or
1011 using a standalone nagiosgraph configuration file.
1012
1013 To use Nagios access controls, define the following in nagiosgraph.conf:
1014
1015 authzmethod=nagios3
1016 authzfile=/etc/nagios/cgi.cfg
1017
1018 nagiosgraph respects the following Nagios variables:
1019
1020 use_authentication
1021 default_user_name
1022 authorized_for_all_hosts
1023 authorized_for_all_services
1024
1025 To use nagiosgraph access controls, define the following in
1026 nagiosgraph.conf:
1027
1028 authzmethod=nagiosgraph
1029 authzfile=/usr/local/nagiosgraph/etc/access.conf
1030
1031 The nagiosgraph access control file uses the following syntax:
1032
1033 host,service=user[,user[,...]]
1034
1035 Wildcards are permitted to match hosts, services, or users. The
1036 exclamation character negates permissions for a user. For example:
1037
1038 *= # deny access to everyone for all hosts and services
1039 *=* # grant access to everyone for all hosts and services
1040 host1=guest # grant access to guest for all services on host1
1041 host1,ping=!guest # deny access to guest for ping on host1
1042 *,ping=guest # grant access to guest for ping on any host
1043 *.foo.com=guest # grant access to guest for any host in foo.com
1044
1045 Permissions are respected by all nagiosgraph CGI scripts, so you can
1046 safely distribute URLs for specific graphs or reports.
1047
1048Troubleshooting
1049
1050 First identify whether your problem is with data collection or data
1051 display.
1052
1053 Are perfdata being collected by Nagios? Run a Nagios plugin directly and
1054 make sure that it is working properly. For example:
1055
1056 check_ping -H host -w 100,10% -c 200,20%
1057
1058 Are permissions set correctly? The nagios user must be able to write to
1059 the rrd directory. The nagios user must be able to write to the
1060 nagiosgraph log file. The web server user must be able to write to the
1061 nagiosgraph cgi log file (which might be the same as the nagiosgraph log
1062 file for older nagiosgraph installations). If the web server user does not
1063 have permission to modify the log file, nagiosgraph cgi logging will end
1064 up in the web server error log.
1065
1066 Is nagiosgraph running? In nagiosgraph.conf, set debug_insert=5 then look
1067 at the nagiosgraph log file. You should see messages from insert.pl.
1068 Ensure that insert.pl is being called as expected, either periodically by
1069 Nagios or in a loop.
1070
1071 Are the RRD files being created? The nagios user must have write
1072 permission on the rrd directory.
1073
1074 Are the RRD files being modified? Check the RRD file timestamp.
1075
1076 Are data being saved into RRD files? With debug_insert=3, look in the
1077 nagiosgraph log file for errors or warnings from insert.pl. Problems with
1078 map rules should be reported in the log file. If necessary, increase the
1079 log level to debug_insert=5.
1080
1081 Are the RRD file contents sane? Use 'rrdtool dump filename.rrd'. It is
1082 normal for a new RRD file to be full of NaN. As the file is updated those
1083 should be replaced with proper values. Ensure that the data source names
1084 in the RRD file correspond to the names in the map rule.
1085
1086 Are there old or unused RRD files lying about? Older versions of
1087 nagiosgraph can be confused by multiple RRD files with the same data
1088 source for a single host. If you change the map rule for a service, you
1089 might want to move the old RRD files out of the rrd directory.
1090
1091 If graphs are not being displayed, start by graphing a single host and
1092 service with showgraph.cgi, for example
1093 showgraph.cgi?host=HOST&service=SERVICE. Set debug_showgraph=3 in
1094 nagiosgraph.conf, then look for output in the nagiosgraph log file or the
1095 web server error log.
1096
1097 Be aware of what you are asking nagiosgraph to display. Start with just a
1098 host and service, then get more specific. For example, each of these
1099 queries will result in a different graph:
1100
1101 show.cgi?host=HOST&service=PING
1102 show.cgi?host=HOST&service=PING&db=ping
1103 show.cgi?host=HOST&service=PING&db=ping,losspct,losswarn
1104
1105 To isolate problems in individual CGI scripts, use debug_show (show.cgi),
1106 debug_showhost (showhost.cgi), debug_showservice (showservice.cgi), or
1107 debug_showgroup (showgroup.cgi) as appropriate.
1108
1109 For installations with many hosts and services, use the host/service
1110 extensions when setting the log level (e.g. debug_showgraph_host = host)
1111 to make the log information easier to grok.
1112
1113Internationalization
1114
1115 Translations are in a single file, with one file per language. Strings for
1116 both the cgi and javascript are in the same file. The javascript
1117 translations and language detection are controlled by the cgi scripts.
1118
1119 In order to minimize dependencies and overhead, nagiosgraph uses its own
1120 system for internationalization. It has a syntax similar to gettext.
1121 Strings are defined in english within the perl and javascript code. There
1122 is no support for complex lexical structures - only string literals. The
1123 user interface to nagiosgraph is (so far) simple enough that this
1124 suffices.
1125
1126 To create a new translation, copy an existing translation file to a file
1127 with the appropriate extension. For example, nagiosgraph_es.conf is the
1128 file for generic spanish.
1129
1130 Error messages are not translated.
1131
1132 Language is detected from the HTTP_ACCEPT_LANGUAGE environment variable.
1133 The first language in this list is the language used. If a language is
1134 specified in the nagiosgraph configuration file, that language overrides
1135 anything in the environment.
1136
1137 The language can be specified as an argument to each cgi script, for
1138 example:
1139
1140 show.cgi?language=es
1141
1142 Language specified in this manner overrides any environment or
1143 configuration.
1144
1145Enumeration of Files
1146
1147 CHANGELOG
1148 History of changes
1149
1150 INSTALL
1151 Example recipe for installing nagiosgraph
1152
1153 README
1154 This file
1155
1156 TODO
1157 A list of potential improvements to nagiosgraph
1158
1159 install.pl
1160 Installation script
1161
1162 lib/insert.pl
1163 Reads Nagios perfdata log and insert into RRD files
1164
1165 cgi/show.cgi
1166 Generates an html page for the host/service specified
1167
1168 cgi/showconfig.cgi
1169 Check the nagiosgraph configuration
1170
1171 cgi/showgraph.cgi
1172 Generates the actual graph image used by other scripts
1173
1174 cgi/showgroup.cgi
1175 Generates an html page for the group specified
1176
1177 cgi/showhost.cgi
1178 Generates an html page for the host specified, showing all available
1179 services on the host
1180
1181 cgi/showservice.cgi
1182 Generates an html page for the service specified, showing all hosts
1183 with that service
1184
1185 cgi/testcolor.cgi
1186 Preview of colors for keywords in each color scheme
1187
1188 etc/access.conf
1189 Access control file
1190
1191 etc/datasetdb.conf
1192 Optional configuration for data sets
1193
1194 etc/nagiosgraph.conf
1195 Primary configuration file for nagiosgraph
1196
1197 etc/nagiosgraph_*
1198 Translations
1199
1200 etc/groupdb.conf
1201 Configuration specific to showgroup.cgi
1202
1203 etc/hostdb.conf
1204 Configuration specific to showhost.cgi
1205
1206 etc/servdb.conf
1207 Configuration specific to showservice.cgi
1208
1209 etc/rrdopts.conf
1210 Per-service options to rrdgraph
1211
1212 etc/map
1213 Regular expression to identify services and specification for how to
1214 create RRD files
1215
1216 etc/ngshared.pm
1217 Shared library of common perl subroutines
1218
1219 examples/*
1220 Configuration examples
1221
1222 share/graph.gif
1223 An icon for use in Nagios
1224
1225 share/nagiosgraph.css
1226 CSS stylesheet
1227
1228 share/nagiosgraph.js
1229 All of the JavaScript used by nagiosgraph
1230
1231 share/nagiosgraph.ssi
1232 HTML for Nagios pages to enable graphs on mouseover
1233
1234 t/* perl test scripts
1235
1236 utils/testentry.pl
1237 A script for testing new map file entries
1238
1239 utils/flat2hier.pl
1240 Script for converting RRD data from flat to hierarchy
1241
1242Sample Installation Layouts
1243
1244 Here are samples of nagiosgraph/nagios installation layouts.
1245
1246 separate, installed to /opt:
1247
1248 /opt/nagios/bin/
1249 /opt/nagios/etc/
1250 /opt/nagios/include/
1251 /opt/nagios/libexec/
1252 /opt/nagios/perl/
1253 /opt/nagios/sbin/
1254 /opt/nagios/share/
1255
1256 /opt/nagiosgraph/bin/insert.pl
1257 /opt/nagiosgraph/cgi-bin/show.cgi
1258 /opt/nagiosgraph/cgi-bin/showgraph.cgi
1259 /opt/nagiosgraph/etc/ngshared.pm
1260 /opt/nagiosgraph/etc/nagiosgraph.conf
1261 /opt/nagiosgraph/share/nagiosgraph.css
1262 /opt/nagiosgraph/share/nagiosgraph.js
1263
1264 overlay, installed to /usr/local/nagios:
1265
1266 /usr/local/nagios/libexec/insert.pl
1267 /usr/local/nagios/sbin/show.cgi
1268 /usr/local/nagios/sbin/showgraph.cgi
1269 /usr/local/nagios/etc/ngshared.pm
1270 /usr/local/nagios/etc/nagiosgraph.conf
1271 /usr/local/nagios/share/nagiosgraph.css
1272 /usr/local/nagios/share/nagiosgraph.js
1273
1274 Debian
1275
1276 /usr/lib/nagiosgraph/insert.pl
1277 /usr/lib/cgi-bin/nagiosgraph/show.cgi
1278 /usr/lib/cgi-bin/nagiosgraph/showgraph.cgi
1279 /etc/nagiosgraph/ngshared.pm
1280 /etc/nagiosgraph/nagiosgraph.conf
1281 /usr/share/nagiosgraph/htdocs/nagiosgraph.css
1282 /usr/share/nagiosgraph/htdocs/nagiosgraph.js
1283
1284 Redhat
1285
1286 /usr/libexec/nagiosgraph/insert.pl
1287 /usr/lib/nagiosgraph/cgi-bin/show.cgi
1288 /usr/lib/nagiosgraph/cgi-bin/showgraph.cgi
1289 /etc/nagiosgraph/ngshared.pm
1290 /etc/nagiosgraph/nagiosgraph.conf
1291 /usr/share/nagiosgraph/htdocs/nagiosgraph.css
1292 /usr/share/nagiosgraph/htdocs/nagiosgraph.js
1293
1294Sample Web Server Configuration
1295
1296 Here are snippets from a typical (but basic) Apache server configuration.
1297
1298 ScriptAlias /nagiosgraph/cgi-bin/ "/opt/nagiosgraph/cgi/"
1299 <Directory "/opt/nagiosgraph/cgi">
1300 Options ExecCGI
1301 AllowOverride None
1302 Order allow,deny
1303 Allow from all
1304 </Directory>
1305 Alias /nagiosgraph "/opt/nagiosgraph/share"
1306 <Directory "/opt/nagiosgraph/share">
1307 Options None
1308 AllowOverride None
1309 Order allow,deny
1310 Allow from all
1311 </Directory>
1312
1313 ScriptAlias /nagios/cgi-bin "/opt/nagios/sbin"
1314 <Directory "/opt/nagios/sbin">
1315 Options ExecCGI
1316 AllowOverride None
1317 Order allow,deny
1318 Allow from all
1319 </Directory>
1320 Alias /nagios "/opt/nagios/share"
1321 <Directory "/opt/nagios/share">
1322 Options None
1323 AllowOverride None
1324 Order allow,deny
1325 Allow from all
1326 </Directory>
1327
1328Platform Specific Notes
1329
1330 Nagios Embedded PERL (ePN)
1331
1332 The Nagios embedded PERL interpreter (ePN) does not understand every PERL
1333 idiom. In particular, it has problems with perldoc. If you get errors such
1334 as:
1335
1336 ePN failed to compile /usr/lib/cgi-bin/nagios3/insert.pl: "Missing right
1337 curly or square bracket at (eval 1) line 45, at end of line syntax error
1338 at (eval 1) line 52, at EOF" at /usr/lib/nagios3/p1.pl line 250
1339
1340 then you must explicitly invoke PERL for insert.pl. For example, for batch
1341 processing use this:
1342
1343 command_line /usr/bin/perl /usr/local/nagios/libexec/insert.pl
1344
1345 or for immediate processing use this:
1346
1347 command_line /usr/bin/perl /usr/local/nagios/libexec/insert.pl "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
1348
1349 CentOS 5 and Nagiosgraph 0.9
1350
1351 wget 'http://dag.wieers.com/rpm/packages/rrdtool/rrdtool-1.2.18-1.el5.rf.i386.rpm'
1352 wget 'http://dag.wieers.com/rpm/packages/rrdtool/perl-rrdtool-1.2.18-1.el5.rf.i386.rpm'
1353 wget 'http://dag.wieers.com/rpm/packages/rrdtool/rrdtool-devel-1.2.18-1.el5.rf.i386.rpm'
1354 wget 'http://mesh.dl.sourceforge.net/sourceforge/nagiosgraph/nagiosgraph-0.9.0.tgz'
1355 yum install -y libart_lgpl.i386
1356 rpm -hiv *rrdtool*.rpm
1357
1358 tar xzvf nagiosgraph-0.9.0.tgz
1359 cd nagiosgraph-0.9.0
1360 mkdir /usr/local/nagios/nagiosgraph
1361 cp -r . /usr/local/nagios/nagiosgraph/
1362 mkdir /usr/local/nagios/nagiosgraph/rrd
1363 chmod go+rX /usr/local/nagios/nagiosgraph
1364 chown nagios /usr/local/nagios/nagiosgraph/rrd
1365 mkdir -p /var/spool/nagios
1366 touch /var/log/nagiosgraph.log /var/spool/nagios/perfdata.log
1367 chown nagios.apache /var/log/nagiosgraph.log /var/spool/nagios/perfdata.log
1368 chmod 664 /var/log/nagiosgraph.log
1369 chmod 644 /var/spool/nagios/perfdata.log
1370
1371 ln -s /usr/local/nagios/nagiosgraph/nagiosgraph.conf /usr/local/etc/nagiosgraph.conf
1372
1373 cp nagiosgraph.css /usr/local/nagios/share/stylesheets
1374
1375 MacOSX 10.5 and Nagios 2.12
1376
1377 Use the lib/insert.sh wrapper to ensure that perl is invoked properly.
1378
1379 define command {
1380 command_name process-service-perfdata
1381 command_line /usr/local/nagios/libexec/insert.sh "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
1382 }
1383
1384 Fedora Core 6 and HTTP output parsing
1385
1386 The entry in the map file for HTTP does not work for Fedora core 6 with
1387 Nagios 2.6 and later. This is what did work.
1388
1389 # Service type: unix-www
1390 # ouput:OK - HTTP/1.1 302 Found - 0.002 second response time |time=0.001920s;;;0.000000 size=126B;;;0
1391 /output:.*?HTTP.*?([.0-9]+) sec/
1392 and push @s, [ http,
1393 [ rt, GAUGE, $1 ] ];
1394
1395Notes For Developers
1396
1397 The makefile rules control pretty much everything. To create the makefile,
1398
1399 perl Makefile.PL
1400
1401 Basic targets are the same as any MakeMaker perl module.
1402
1403 make
1404 make test
1405 make install
1406 make clean
1407 make realclean
1408
1409 There are rules to build a source distribution, Debian, and Redhat
1410 packages.
1411
1412 make dist creates nagiosgraph-x.y.z.tar.gz
1413 make deb-package creates nagsiograph-x.y.z.deb
1414 make rpm-package creates nagiosgraph-x.y.z.rpm
1415
1416 If you would like to contribute to nagiosgraph, there are a few things you
1417 should do to make your life and the lives of the other nagiosgraph
1418 developers easier.
1419
1420 * Please respect these design goals:
1421
1422 1. do not break existing installations
1423
1424 2. minimize dependencies
1425
1426 3. keep it simple
1427
1428 * perlcritic
1429
1430 Run perlcritic and fix all warnings before you commit. Be brutal:
1431
1432 perlcritic -1 cgi/*.cgi
1433 perlcritic -1 etc/*.pm
1434
1435 or use the make rule to run them all:
1436
1437 make critic
1438
1439 * unit tests
1440
1441 Run the unit tests before modifying existing functionality. Write unit
1442 tests before you add code.
1443
1444 make test
1445
1446 * test coverage
1447
1448 To generate code coverage reports, install Devel::Cover then run
1449 tests:
1450
1451 make test-coverage
1452
1453 This will generate a cover_db directory with code coverage metrics.
1454
1455 * profiling
1456
1457 Use the perl profiler to see which parts of the code are taking most
1458 time. Run the cgi script with DProf enabled, specifying args on the
1459 command line.
1460
1461 perl -d:DProf cgi/show.cgi
1462 perl -d:DProf cgi/showgraph.cgi host=HOST service=SERVICE
1463
1464 Then view the profiling results.
1465
1466 dprofpp
1467
1468 The bottlenecks are RRDs::graph (showgraph.cgi) and RRDs::info
1469 (show.cgi). RRDs::info is invoked on each file in the rrd directory
1470 tree. On a 1.4GHz G4 PPC, getting info on 500 files takes about 0.2
1471 seconds.
1472
1473 * internationalization (i18n)
1474
1475 To get a list of all translated string constants, do the following:
1476
1477 grep '_(' cgi/*.cgi etc/*.pm | sed -e 's/.*_(\([^)]*\).*/\1/' | sort -u
1478 grep '_(' share/*.js | sed -e 's/.*_(\([^)]*\).*/\1/' | sort -u
1479
1480 nagiosgraph uses a bare bones, home-grown, standalone implementation
1481 of i18n. If you add strings to the user interface or error handling,
1482 please follow the pattern used for other strings in the code. All
1483 translations reside in a single file, with one file per language. Each
1484 file is used by the cgi (directly) and the javascript (via the cgi).
1485
1486 * configurations
1487
1488 Be consistent in configuration files and documentation about where the
1489 nagiosgraph files are installed, regardless of what you use. Use the
1490 standalone layout, with Nagios installed at /usr/local/nagios and
1491 nagiosgraph installed at /usr/local/nagiosgraph
1492
1493 * perldoc
1494
1495 You can preview the perldoc by doing the following:
1496
1497 perldoc install.pl
1498 perldoc cgi/show.cgi
1499 perldoc etc/ngshared.pm
1500
1501Project Testing/Code Summary
1502
1503 Here are some project statistics as of 14feb12:
1504
1505 Number of unit tests: 1307
1506
1507 Test coverage:
1508
1509 stmt bran cond sub pod time total
1510 etc/ngshared.pm 82.5 77.3 67.4 91.6 0.0 100.0 77.0
1511
1512 Platforms on which unit tests have been run:
1513
1514 os arch perl
1515 -------------------------------
1516 debian 5 ppc 5.10.0
1517 debian 6 i386,x64 5.10.1
1518
1519 Platforms on which installation has been tested:
1520
1521 os arch method nagios
1522 -------------------------------------------------------------------------
1523 debian 5 ppc manual 3.2.0, 3.2.1, 3.2.2, 3.2.3
1524 debian 5 i386 deb 3.0.6
1525 ubuntu 10.04 i386,x64 deb, installer 3.2.0
1526 fedora 14 i386,x64 rpm, installer 3.2.3
1527 centos 5.5 i386 rpm, installer 3.2.3
1528 opensuse 11.3 i386 rpm, installer 3.2.1
1529 redhat 6 i386,x64 rpm, installer 3.2.3
1530
1531 The codebase looks like this:
1532
1533 lines words bytes
1534 267 948 6974 cgi/export.cgi
1535 182 623 4987 cgi/show.cgi
1536 515 1447 12093 cgi/showconfig.cgi
1537 206 669 5245 cgi/showgraph.cgi
1538 194 709 5063 cgi/showgroup.cgi
1539 188 643 4986 cgi/showhost.cgi
1540 189 667 5021 cgi/showservice.cgi
1541 172 727 5344 cgi/testcolor.cgi
1542 3233 13606 113742 etc/ngshared.pm
1543 72 329 2162 lib/insert.pl
1544 5218 20368 165617 total
1545
1546 177 353 2791 share/nagiosgraph.css
1547 1473 5251 42421 share/nagiosgraph.js
1548 1 3 75 share/nagiosgraph.ssi
1549 1651 5607 45287 total
1550
1551 37 120 1087 t/01required_modules.t
1552 4139 11033 123394 t/02ngshared.t
1553 173 462 6351 t/03defaults.t
1554 161 509 4222 t/04show.t
1555 803 1983 25545 t/05permissions.t
1556 2270 3342 45556 t/06rules.t
1557 1529 2885 32559 t/07perfdata.t
1558 2111 4229 47498 t/09plugins.t
1559 232 620 7383 t/10backward.t
1560 31 84 1002 t/97pod.t
1561 20 73 608 t/98podcoverage.t
1562 18 71 591 t/99kwalitee.t
1563 11524 25411 295796 total
1564
1565 32 163 879 etc/access.conf
1566 23 92 873 etc/datasetdb.conf
1567 63 249 2279 etc/groupdb.conf
1568 42 164 1446 etc/hostdb.conf
1569 92 255 1828 etc/labels.conf
1570 384 2291 15329 etc/nagiosgraph.conf
1571 52 81 793 etc/nagiosgraph_de.conf
1572 52 92 865 etc/nagiosgraph_es.conf
1573 52 102 935 etc/nagiosgraph_fr.conf
1574 20 119 660 etc/rrdopts.conf
1575 16 78 480 etc/servdb.conf
1576 256 1448 9863 etc/map
1577 1084 5134 36230 total
1578
1579
README.pod
1=pod
2
3=for comment
4$Id$
5Note: indent all fixed-width paragraphs four spaces.
6
7=for html
8<style>
9h1,h2,h3,h4 {font-family: sans-serif;}
10h1 {font-size:1.3em; padding-top:0.25em;}
11h2 {font-size:1.1em; padding-top:0.1em;}
12h3 {font-size:1em; padding-top:0.1em;}
13h4 {font-size:1em; font-style:italic; padding-top:0.1em;}
14hr {width:0;}
15dt {font-family: sans-serif; font-size:0.85em;}
16dd {font-size:0.85em;}
17.index {
18 font-family: sans-serif;
19 font-size: 0.8em;
20 float: right;
21 border: 1px solid #aaaaaa;
22 background: #eeeeee;
23 margin-left: 30px;
24 margin-right: 10px;
25 padding-right: 20px;}
26</style>
27
28
29=head1 Nagiosgraph
30
31Nagiosgraph is an add-on to Nagios. Nagios monitors one or more services on
32each host. nagiosgraph extracts information from the Nagios output, processes
33it, then inserts it into one or more round-robin database (RRD) files. CGI
34scripts display data from the RRD files as web pages. The CGI output can be
35embedded directly into Nagios so that graphs show up like other trend reports.
36
37Installation is a three-step process. First install the nagiosgraph files,
38then configure Nagios for data collection, and finally customize the graphs
39and links as needed. Installation can be done manually by copying files and
40modifying configuration files, or automatically using the install.pl script.
41
42The INSTALL file contains basic installation instructions.
43
44This README file contains detailed instructions for installing, upgrading,
45customizing, troubleshooting, and managing performance data.
46
47Answers to frequently asked questions are at:
48
49=over 2
50
51L<https://sourceforge.net/apps/mediawiki/nagiosgraph>
52
53=back
54
55For help, visit the forum at:
56
57=over 2
58
59L<http://sourceforge.net/projects/nagiosgraph/forums/forum/394748>
60
61=back
62
63
64
65=head1 Copyright and License
66
67 License: OSI Artistic License 2.0
68 http://www.opensource.org/licenses/artistic-license-2.0
69
70 Author: (c) 2005 Soren Dossing
71 Author: (c) 2008 Alan Brenner, Ithaka Harbors
72 Author: (c) 2010 Matthew Wall
73
74 Nagios is a registered trademark of Ethan Galstad.
75
76
77=head1 Principles of Operation
78
79nagiosgraph is a simple interface between Nagios and RRD files.
80
81nagiosgraph operates in two modes. One is to collect performance data
82from Nagios servicechecks, and the other is to display graphs of
83the performance data collected.
84
85All the data collected are stored in RRD files using rrdtool. A file
86called 'map' defines how to identify the data from Nagios and how to
87store them in the RRD files. Nagios passes all the service data to a
88nagiosgraph script called 'insert.pl'. This script uses the file 'map'
89to determine how to name the data and into which RRD files to insert
90the data. The map file also processes the data, for example by changing
91units or applying scaling factors.
92
93The 'map' file is actually perl code, that is eval'ed by 'insert.pl'.
94The map file contains a general rule that will capture the performance
95data from most plugins. However, it may be necessary to add entries to
96match the output of some Nagios plugins. Several examples of servicechecks
97are included in the distributed map file. Knowing perl regular expression
98is helpful, but the examples supplied should cover most types of
99performance data.
100
101For graphing, nagiosgraph includes cgi scripts. 'show.cgi' looks up
102performance data for a single host and service, and generates line
103charts accordingly. Other scripts display all hosts for a specific
104service, all services for a specific host, or arbitrary groups of hosts
105and services. These run out-of-the-box with minimal configuration, or
106they can be customized, using a configuration file or interactively.
107
108Graphs can be integrated into Nagios using Nagios' extended information
109for services and hosts. By specifying nagiosgraph cgi scripts in the
110Nagios configuration, individual graphs and collections of graphs can be
111linked directly to hosts and services in Nagios web pages.
112
113By default, all available data for a servicecheck will be displayed in
114the same graph. With extra configuration, either embedded in the url,
115specified in a configuration file, or using controls in a web page, it is
116possible to display less data or to split values into multiple graphs.
117There is also a general method for specifying arbitrary RRD graph
118options such as line style, color, and scaling for individual hosts or
119services.
120
121
122
123=head1 Installation Preliminaries
124
125Before installing, ensure that the prerequisite software has been installed
126then decide upon a layout and location.
127
128
129=head2 Prerequisites
130
131Nagiosgraph will not function without a working Nagios installation, so
132first ensure that Nagios works. Version 3.2 or later is recommended, but
133older versions will also work.
134
135Nagiosgraph requires rrdtool. Version 1.4 or later is recommended, but
136older versions will also work.
137
138Nagiosgraph requires the CGI and RRDs perl modules. The RRDs perl module
139is part of rrdtool but is often distributed as a separate package. The GD
140perl module is optional, but recommended. The Nagios::Object perl module is
141optional, but useful for automatic configuration of showgroup.cgi.
142
143Debian/Ubuntu:
144
145 apt-get install libcgi-pm-perl librrds-perl
146 apt-get install libgd-gd2-perl libnagios-object-perl
147
148Redhat/Fedora/CentOS:
149
150 yum install perl-rrdtool perl-GD
151
152SUSE:
153
154 rrdtool, perl-GD
155
156Solaris:
157
158 rrdtool, gd
159
160FreeBSD:
161
162 rrdtool, gd
163
164OpenBSD:
165
166 p5-RRD, p5-GD
167
168The install.pl script includes an option to check for pre-requisites:
169
170 install.pl --check-prereq
171
172
173=head2 Layout and Location
174
175There are two standard layouts: separate or overlay. The separated layout
176has nagiosgraph and Nagios in separate directories. The overlay places
177nagiosgraph components with Nagios components.
178
179Nagios and nagiosgraph can be installed in just about any location, for
180example /opt or /usr/local.
181
182Redhat (Fedora, CentOS), SUSE, and Debian (Ubuntu) systems have their own
183layouts. If you installed Nagios from a package, you can overlay nagiosgraph
184or you can install nagiosgraph to its own standalone location.
185
186When installing from source, the standalone layout is highly recommended
187since it makes updates much easier.
188
189Decide upon a location and layout before you start the installation.
190Examples are in the Sample Installation Layouts section.
191
192
193=head2 Installation Methods
194
195There are a few ways to install nagiosgraph: manual, script, and package.
196On most systems the installation requires root permissions, so either do
197the installation as root or preface commands with sudo.
198
199=head3 Manual Installation
200
201Copy and edit files directly. Follow the recipe in the INSTALL file, or
202the instructions in these sections of this file:
203
204=over
205
206=item *
207
208L</"Installing nagiosgraph Files"> - nagiosgraph installation
209
210=item *
211
212L</"Configuring Data Processing"> - Nagios configuration
213
214=item *
215
216L</"Configuring Graphing and Display"> - Apache and Nagios configuration
217
218=back
219
220=head3 Install Script
221
222Run the install.pl script. It will prompt you for the parameters it
223needs, then it will copy and configure nagiosgraph files. It will also
224prompt you to modify apache and Nagios configuration files.
225
226 install.pl --prefix=/usr/local/nagiosgraph
227 install.pl --help
228
229=head3 Installation Using Packages
230
231The nagiosgraph packages assume that Nagios and apache were installed
232from packages. Do not use a nagiosgraph package if you installed Nagios
233or apache from source!
234
235Debian, Ubuntu
236
237 dpkg -i nagiosgraph-x.y.z.deb
238
239Redhat, Fedora, CentOS, SUSE
240
241 rpm -i nagiosgraph-x.y.z.rpm
242
243
244
245=head1 Installing nagiosgraph Files
246
247These instructions assume a standalone layout, with Nagios at /usr/local/nagios
248and nagiosgraph at /usr/local/nagiosgraph
249
250=over
251
252=item 1.
253
254Create destination directories:
255
256 mkdir /usr/local/nagiosgraph
257 mkdir /usr/local/nagiosgraph/bin
258 mkdir /usr/local/nagiosgraph/cgi-bin
259 mkdir /usr/local/nagiosgraph/etc
260 mkdir /usr/local/nagiosgraph/share
261
262=item 2.
263
264Extract nagiosgraph into a temporary location:
265
266 cd /tmp
267 tar xzvf nagiosgraph-x.y.z.tgz
268
269=item 3.
270
271Copy the contents of etc into your preferred configuration location:
272
273 cp etc/* /usr/local/nagiosgraph/etc
274
275=item 4.
276
277Edit the perl scripts in the cgi and lib directories, modifying the
278"use lib" line to point to the directory from the previous step.
279
280 vi cgi/*.cgi lib/insert.pl
281
282=item 5.
283
284Copy insert.pl to a location from which it can be executed:
285
286 cp lib/insert.pl /usr/local/nagiosgraph/bin
287
288=item 6.
289
290Copy CGI scripts to a script directory served by the web server:
291
292 cp cgi/*.cgi /usr/local/nagiosgraph/cgi-bin
293
294=item 7.
295
296Copy CSS and JavaScript files to a directory served by the web server:
297
298 cp share/nagiosgraph.css /usr/local/nagiosgraph/share
299 cp share/nagiosgraph.js /usr/local/nagiosgraph/share
300
301=item 8.
302
303Edit nagiosgraph.conf. Set at least the following:
304
305 logfile = /var/log/nagiosgraph.log
306 cgilogfile = /var/log/nagiosgraph-cgi.log
307 perflog = /var/nagios/perfdata.log
308 rrddir = /var/nagios/rrd
309 mapfile = /usr/local/nagiosgraph/etc/map
310 nagiosgraphcgiurl = /nagiosgraph/cgi-bin
311 javascript = /nagiosgraph/nagiosgraph.js
312 stylesheet = /nagiosgraph/nagiosgraph.css
313
314=item 9.
315
316Set permissions of "rrddir" (as defined in nagiosgraph.conf) so that
317the *nagios* user can write to it and the *www* user can read it:
318
319 mkdir /var/nagios/rrd
320 chown nagios /var/nagios/rrd
321 chmod 755 /var/nagios/rrd
322
323=item 10.
324
325Set permissions of "logfile" so that the *nagios* user can write to it:
326
327 touch /var/log/nagiosgraph.log
328 chown nagios /var/log/nagiosgraph.log
329 chmod 644 /var/log/nagiosgraph.log
330
331=item 11.
332
333Set permissions of "cgilogfile" so that the *www* user can write to it:
334
335 touch /var/log/nagiosgraph-cgi.log
336 chown www /var/log/nagiosgraph-cgi.log
337 chmod 644 /var/log/nagiosgraph-cgi.log
338
339=item 12.
340
341Ensure that the *nagios* user can create and delete perfdata files:
342
343 chown nagios /var/nagios
344 chmod 755 /var/nagios
345
346=back
347
348
349=head1 Upgrade Notes
350
351
352=over
353
354=item *
355
356Follow the steps for a new installation, but keep your customizations.
357Your changes should be limited to the map file (map), configuration
358files (nagiosgraph.conf and other .conf files), and the stylesheet
359(nagiosgraph.css).
360
361=item *
362
363Use diff, or a similar tool, to update your nagiosgraph.conf with any new
364fields from etc/nagiosgraph.conf
365
366=item *
367
368Use diff, or a similar tool, to update your nagiosgraph.css with changes
369from share/nagiosgraph.css.
370
371=item *
372
373You may want to look at etc/map or the files in the examples directory
374to see if there are any map rules or CSS useful to your configuration.
375
376=item *
377
378If you change from immediate processing to batch processing, be sure to
379comment out service_perfdata_command in the Nagios configuration.
380
381=item *
382
383Be sure to install the nagiosgraph.js and nagiosgraph.css files, especially
384if you are upgrading from nagiosgraph older than 1.2.
385
386=item *
387
388If you are upgrading from nagiosgraph 1.4.1 or earlier, move your service
389and database/datasource labels from nagiosgraph.conf to labels.conf.
390
391=item *
392
393If you are upgrading from nagiosgraph 1.4.3 or earlier and you were using
394nagios3 for the authzmethod, you must replace authz_nagios_cfg and
395authz_cgi_cfg with authzfile. All of the Nagios authorization parameters
396should be in the Nagios CGI configuration file (typically cgi.cfg).
397
398=item *
399
400If you are upgrading from nagiosgraph 1.4.3 or earlier, you might want to
401add the generic map rule to the end of your map file. This rule will
402catch performance data from any additional plugins you add. Using the
403generic rule results in RRD files with the following structure, one file
404per named performance data element, with one or more data sources:
405
406 host0/service___label (data[,warn][,crit][,min][,max])
407
408=item *
409
410If you are upgrading from nagiosgraph 1.4.3 or earlier, you should make any
411ignore map rules explicit. For example, in the map file change this:
412
413 /output:CHECK_NRPE: Socket timeout/
414 and return;
415
416to this:
417
418 /output:CHECK_NRPE: Socket timeout/
419 and return ('ignore');
420
421=back
422
423
424=head1 Configuring Data Processing
425
426Before nagiosgraph can graph anything it must first collect data. There are
427two ways to process data - batch and immediate. Batch processing is usually
428appropriate for most Nagios deployments. Immediate processing typically
429requires more CPU and I/O.
430
431In batch processing, performance data are appended to a file, then Nagios
432invokes insert.pl at a regular interval to update the RRD files.
433
434In immediate processing, Nagios invokes insert.pl immediately after each
435service check, thus updating the corresponding RRD files.
436
437
438=head2 Batch Processing
439
440=over
441
442=item 1.
443
444In the Nagios configuration file (nagios.cfg) set:
445
446 process_performance_data=1
447 service_perfdata_file=/var/nagios/perfdata.log
448 service_perfdata_file_template=$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$
449 service_perfdata_file_mode=a
450 service_perfdata_file_processing_interval=30
451 service_perfdata_file_processing_command=process-service-perfdata
452
453Make sure that service_perfdata_command is either commented out
454or not defined.
455
456Make sure that location of service_perfdata_file matches that of perflog
457defined in nagiosgraph.conf.
458
459=item 2.
460
461In the Nagios commands file (commands.cfg) define
462the process-service-perfdata command:
463
464 define command {
465 command_name process-service-perfdata
466 command_line /usr/local/nagiosgraph/bin/insert.pl
467 }
468
469Make sure there is only one definition for process-service-perfdata.
470
471Older versions of Nagios used checkcommands.cfg or misccommands.cfg.
472
473=item 3.
474
475Check the Nagios configuration
476
477 /usr/local/nagios/bin/nagios -v /usr/local/nagios/etc/nagios.cfg
478
479=item 4.
480
481Restart Nagios
482
483 /etc/init.d/nagios restart
484
485=back
486
487
488=head2 Immediate Processing
489
490=over
491
492=item 1.
493
494In nagios.cfg:
495
496 process_performance_data=1
497 service_perfdata_command=process-service-perfdata
498
499Make sure that service_perfdata_file_processing_command is either
500commented out or not defined.
501
502=item 2.
503
504In commands.cfg:
505
506 define command{
507 command_name process-service-perfdata
508 command_line /usr/local/nagiosgraph/bin/insert.pl "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
509 }
510
511=item 3.
512
513Check the Nagios configuration
514
515 /usr/local/nagios/bin/nagios -v /usr/local/nagios/etc/nagios.cfg
516
517=item 4.
518
519Restart Nagios
520
521 /etc/init.d/nagios restart
522
523=back
524
525
526=head1 Configuring Graphing and Display
527
528First configure the web server to run the nagiosgraph CGI scripts. For
529example, with Apache do something like this in the Apache configuration:
530
531 ScriptAlias /nagiosgraph/cgi-bin /usr/local/nagiosgraph/cgi-bin
532 <Directory "/usr/local/nagiosgraph/cgi-bin">
533 Options ExecCGI
534 AllowOverride None
535 Order allow,deny
536 Allow from all
537 </Directory>
538 Alias /nagiosgraph "/usr/local/nagiosgraph/share"
539 <Directory "/usr/local/nagiosgraph/share">
540 Options None
541 AllowOverride None
542 Order allow,deny
543 Allow from all
544 </Directory>
545
546Restart the web server:
547
548 /etc/init.d/apache2 restart
549
550Verify that nagiosgraph is working by running showconfig.cgi
551
552 http://server/nagiosgraph/cgi-bin/showconfig.cgi
553
554Try graphing some data by running show.cgi
555
556 http://server/nagiosgraph/cgi-bin/show.cgi
557
558This should display a web page with a list of your hosts and services.
559Note that it might take a few minutes for data to collect, so at first the
560list of hosts and services might be sparse and the graphs might be empty.
561
562There are a few ways to embed graphs into Nagios. In the service and
563host listings, Nagios will display graph icons that, when clicked, will
564open a new web page with graphs. These icons are typically per-host
565(linked to the showhost.cgi script) or per-host-service (linked to the
566show.cgi script). Nagios will display graph data when the mouse is moved
567over the graph icon for each host/service. Finally, graphs can be displayed
568directly in the Nagios frames. The following sections explain how to do each
569of these.
570
571
572
573=head2 Graph Icons and Links in Nagios
574
575Links to graphs can be embedded in Nagios status pages using the notes or
576actions fields. The specifics depend on the Nagios version as well as how
577you have configured your host and service definitions. Nagios 2 uses the
578serviceextinfo and hostextinfo construct. In Nagios 3 the nagiosgraph
579additions go directly in the host and service definitions.
580
581To display a graph icon instead of the Nagios action icon, replace
582nagios/images/action.gif with graph.gif from the nagiosgraph distribution.
583
584In its default configuration, Nagios will create a new window for each
585action or notes link. To display graphs in the Nagios frame instead of
586a new window, set action_url_target=main in the Nagios cgi.cfg file.
587
588=head3 For Nagios 2.6 and Earlier
589
590If you have these lines in nagios.cfg, un-comment the 2 cfg_file= lines:
591
592 # Extended host/service info definitions are now stored along with
593 # other object definitions:
594 # cfg_file=/etc/nagios/hostextinfo.cfg
595 # cfg_file=/etc/nagios/serviceextinfo.cfg
596
597Otherwise, define in cgi.cfg the following:
598
599 xedtemplate_config_file=/usr/local/nagios/etc/serviceextinfo.cfg
600
601Edit/Create hostextinfo.cfg
602
603 define hostextinfo {
604 host_name your-host
605 action_url /nagiosgraph/cgi-bin/showhost.cgi?host=$HOSTNAME$
606 }
607
608This must be the host you will use in serviceextinfo.cfg
609
610Edit/Create serviceextinfo.cfg
611
612 define serviceextinfo {
613 service_description DNS
614 hostgroup servers
615 notes_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
616 icon_image graph.gif
617 icon_image_alt View graphs
618 }
619
620=head3 For Nagios 2.9 and Nagios 3
621
622Use the action_url for any existing host or service definition. For example,
623
624 define service {
625 name NTP
626 use local-service
627 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
628 ...
629 }
630
631 define host {
632 host_name web-server
633 action_url /nagiosgraph/cgi-bin/showhost.cgi?host=$HOSTNAME$
634 ...
635 }
636
637To apply graph links to multiple services, define a template such as this:
638
639 define service {
640 name graphed-service
641 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
642 register 0
643 }
644
645Then use it in services like this:
646
647 define service {
648 name NTP
649 use local-service,graphed-service
650 ...
651 }
652
653
654
655=head2 Graphs in Nagios Mouseovers
656
657To display graphs as mouseovers for each host and/or service, do the following:
658
659=over
660
661=item 1.
662
663Edit the file share/nagiosgraph.ssi to contain the URL to the nagiosgraph
664javascript file (e.g. /nagiosgraph/nagiosgraph.js)
665
666=item 2.
667
668If you have not customized the Nagios SSI, copy share/nagiosgraph.ssi to
669the Nagios ssi directory, and rename it so that Nagios will insert it into
670each page. For example:
671
672 cp share/nagiosgraph.ssi /usr/local/nagios/share/ssi/common-header.ssi
673
674If you have customized Nagios SSI, add the contents of
675share/nagiosgraph.ssi to your customized SSI header file.
676
677=item 3.
678
679Configure services to display graphs on mouseovers by adding some
680JavaScript to action_url or notes_url. For example:
681
682 define service {
683 name NTP
684 use local-service
685 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$' onMouseOver='showGraphPopup(this)' onMouseOut='hideGraphPopup()' rel='/nagiosgraph/cgi-bin/showgraph.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
686 ...
687 }
688
689This example displays a week of data in a popup with no legend:
690
691 define service {
692 name NTP
693 use local-service
694 action_url /nagiosgraph/cgi-bin/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$' onMouseOver='showGraphPopup(this)' onMouseOut='hideGraphPopup()' rel='/nagiosgraph/cgi-bin/showgraph.cgi?host=$HOSTNAME$&service=$SERVICEDESC$&period=week&rrdopts=-w+450+-j
695 ...
696 }
697
698=back
699
700You must restart Nagios for changes to service/host defintions to take effect.
701
702If a service includes multiple data sources, use the datasetdb file (specified
703in nagiosgraph.conf) to indicate which data sources should be displayed by
704default for each service, or specify the data source(s) explicity in each
705action_url.
706
707
708
709=head2 Graphs in Nagios Frames
710
711To embed nagiosgraph graphs directly into Nagios, do the following:
712
713Modify side.php (e.g. /usr/local/nagios/share/side.php) by inserting
714bullets under the 'Trends' heading:
715
716 <li><a href="<?php echo $cfg["cgi_base_url"];?>/trends.cgi" target="<?php echo $link_target;?>">Trends</a>
717 <ul>
718 <li><a href="<?php echo $cfg["cgi_base_url"];?>/show.cgi" target="<?php echo $link_target;?>">Graphs</a></li>
719 <li><a href="<?php echo $cfg["cgi_base_url"];?>/showhost.cgi" target="<?php echo $link_target;?>">Graphs by Host</a></li>
720 <li><a href="<?php echo $cfg["cgi_base_url"];?>/showservice.cgi" target="<?php echo $link_target;?>">Graphs by Service</a></li>
721 <li><a href="<?php echo $cfg["cgi_base_url"];?>/showgroup.cgi" target="<?php echo $link_target;?>">Graphs by Group</a></li>
722 </ul>
723 </li>
724
725If you keep the nagiosgraph cgi scripts in a location different than
726the Nagios cgi scripts, then use 'ng_cgi_base_url' rather than
727'cgi_base_url' and make an entry in config.inc.php such as this:
728
729 $cfg['cgi_base_url']='/nagios/cgi-bin';
730 $cfg['ng_cgi_base_url']='/nagiosgraph/cgi-bin';
731
732Some Nagios installations have side.html instead of side.php:
733
734 <li><a href="/nagios/cgi-bin/trends.cgi" target="main">Trends</a>
735 <ul>
736 <li><a href="/nagiosgraph/cgi-bin/show.cgi" target="main">Graphs</a></li>
737 <li><a href="/nagiosgraph/cgi-bin/showhost.cgi" target="main">Graphs by Host</a></li>
738 <li><a href="/nagiosgraph/cgi-bin/showservice.cgi" target="main">Graphs by Service</a></li>
739 <li><a href="/nagiosgraph/cgi-bin/showgroup.cgi" target="main">Graphs by Group</a></li>
740 </ul>
741 </li>
742
743
744
745=head1 Customizing the Graphs
746
747The look and feel of nagiosgraph is controlled by the cascading style sheets
748defined in nagiosgraph.css. The examples directory contains a stylesheet file
749with sample style sheets for fixing the controls to the page, floating the
750controls above the graphs, or hiding the controls altogether.
751
752Graphs can be customized individually by specifying CGI arguments, or they
753can be customized overall by specifying values in the configuration files.
754Some parameters apply to each page, others apply to each service, and others
755apply to each data source.
756
757The following CGI arguments are recognized by show.cgi, showhost.cgi,
758showservice.cgi, and showgroup.cgi:
759
760=over 16
761
762=item hidengtitle
763
764Do not display the nagiosgraph title in the page.
765
766=item geom=WxH
767
768Set the dimensions of all graphs to W pixels wide and H pixels tall.
769
770=item showtitle
771
772Display a title next to each graph.
773
774=item showdesc
775
776Display a description of data sources next to each graph.
777
778=item showgraphtitle
779
780Display a title in each graph.
781
782=item graphonly
783
784Display only graph data, not axes, grid, or legend.
785
786=item hidelegend
787
788Do not display the legend in each graph.
789
790=item fixedscale
791
792Set the Y-axis to be in the same scale as the performance data. This is useful
793to prevent a variety of vertical scales when autoscaling results in different
794vertical scaling for each graph.
795
796=back
797
798The following options are available via configuration files:
799
800=over 16
801
802=item rrdopts
803
804Use the rrdopts option to specify custom RRD graphing options. These can be
805specified for all graphs using rrdopts, or per-service using the rrdoptsfile.
806
807=item lineformat
808
809Use lineformat to control the line thickness and line color for individual data
810sources. The alpha channel is respected if a recent version of rrdtool is
811installed.
812
813=item plotas, plotasLINE1, plotasLINE2, plotasLINE3, plotasAREA, plotasTICK
814
815Use plotas to control the line thickness/style for individual data sources.
816
817=item stack
818
819Create stacked area graphs using the stack directive for individual data
820sources, the STACK directive in lineformat, or by adjusting the alpha
821channel in specified colors.
822
823=back
824
825Some services emit multiple data sources with big differences in magnitude.
826Others emit data with different units. In such cases, split the data
827into seperate graphs by specifying one or more data sources. For example,
828for the NTP service, jitter and offset are typically in the same range,
829while stratum is orders of magnitude larger. So we specify two
830different graphs:
831
832 show.cgi?host=HOST&service=NTP&db=ntp,jitter&db=ntp,offset
833 show.cgi?host=HOST&service=NTP&db=ntp,stratum
834
835This assumes that jitter, offset, and stratum are all stored in a
836single RRD file using a map entry such as:
837
838 /output:NTP.*Offset ([-.0-9]+).*jitter ([-.0-9]+).*stratum (\d+)/
839 and push @s, [ 'ntp',
840 [ 'offset', GAUGE, $1 ],
841 [ 'jitter', GAUGE, $2/1000 ],
842 [ 'stratum', GAUGE, $3+1 ] ];
843
844Data are identified by host, service, database, and data source. It is
845possible to graph all sources from a single database, a single source
846from a database, selected sources from a single database, or selected
847sources from multiple databases. In each case, the host and service
848must match. For example:
849
850 showgraph.cgi?host=HOST&service=SERVICE&db=loss
851 showgraph.cgi?hsot=HOST&service=SERVICE&db=loss,losspct
852 showgraph.cgi?host=HOST&service=SERVICE&db=ntp,jitter,offset
853 showgraph.cgi?host=HOST&service=SERVICE&db=loss,losspct&db=rta,rta
854
855These options apply to showgraph.cgi, show.cgi, and showservice.cgi and
856in the configuration files hostdb.conf, groupdb.conf, and datasetdb.conf.
857
858Use URLs as canned queries. For example, define a 'temperatures'
859group in the groupdb.conf file that combines temperature data from
860multiple hosts and service types, then create a link to that group:
861
862 http://server/cgi-bin/showgroup.cgi?group=temperatures
863
864See the configuration files for more options and examples.
865
866
867
868=head1 Adding Service Types
869
870Service types are added by creating rules in the 'map' file. The map file
871determines how data from Nagios will be stored. Each rule determines how
872output and performance data should be recorded.
873
874The map file contains regular expressions to identify service types
875and define content in RRD files. All entries are written in perl, so
876editing, adding or deleting entries requires some perl programming
877knowledge. Knowledge of RRD is also helpful.
878
879There has to be one entry for each type of service. The map file included
880with nagiosgraph has several examples for cpu, memory, disk, network etc.
881Most examples identify data from either Nagios output or Nagios perfdata
882then define a number of RRD data sources. There is also a generic rule
883that will capture output from any plugin that adheres to the Nagios standards
884for plugin performance data.
885
886insert.pl receives data from Nagios. It formats data into a string consisting
887of four lines of text. This string might look like this:
888
889 hostname:host0
890 servicedesc:ping
891 output:PING OK - Packet loss = 0%, RTA = 0.00 ms
892 perfdata:
893
894Or like this:
895
896 hostname:host0
897 servicedesc:CPU Load
898 output:OK - load average: 0.06, 0.12, 0.10
899 perfdata:load1=0;15;30;0 load5=0;10;25;0 load15=0;5;20;0
900
901The official perfdata format is a space-delimited list of qualified
902name-value pairs with this format:
903
904 name=value[units];[warn];[crit];[min];[max]
905
906where units is one of:
907
908 - unitless
909 s,us,ms - time
910 % - percentage
911 B,KB,MB,GB,TB,PB - bytes
912 c - counter
913
914However, the perfdata is not always set, and the format of perfdata varies
915a great deal from plugin to plugin. So depending on type of service, the
916most useful data can be in either the output or perfdata line.
917
918For the ping example above, data can be extracted from the output line
919with a regular expression like this:
920
921 /output:PING.*?(\d+)%.+?([.\d]+)\sms/
922
923In this case, two values are extracted and available in $1 and $2. We can
924then create a data structure describing the content of the database. The
925general format is
926
927 [ db-name,
928 [ DS-name, TYPE, DS-value ],
929 [ DS-name, TYPE, DS-value ],
930 ...
931 ]
932
933Where DS name is the name that will be assigned to a line showing on RRD
934graphs. Each DS name must be no longer than 19 characters and must contain
935only the characters A-Z, a-z, 0-9, or underscore. TYPE is either GAUGE or
936DERIVE. the DS value is the data extracted in the regular expression. The
937DS value can be an expression, for example to normalize to SI units.
938
939Each database definition must be added to the @s array.
940
941So the complete code to define and insert into an RRD file for the
942PING example above, becomes:
943
944 /output:PING.*?(\d+)%.+?([.\d]+)\sms/
945 and push @s, [ ping,
946 [ losspct, GAUGE, $1 ],
947 [ rta, GAUGE, $2/1000 ] ];
948
949In this case the database name is called 'ping' and the DS-names stored
950are losspct and rta. The Nagios output reports round trip time in
951milliseconds, so the value is divided by 1000 to convert to seconds.
952The type for each DS is GAUGE.
953
954Be careful about the database names and DS names. In the code example
955above the names are barewords, which only works as long as the don't
956conflict with perl functions or subroutines. For example the word 'sleep'
957will not work without quoting.
958
959A safer version of the above example is
960
961 /output:PING.*?(\d+)%.+?([.\d]+)\sms/
962 and push @s, [ 'ping',
963 [ 'losspct', 'GAUGE', $1 ],
964 [ 'rta', 'GAUGE', $2/1000 ] ];
965
966After editing the map file, the syntax can be checked with
967
968 perl -c map
969
970Again a word of caution. If the map file has syntax errors, nothing will be
971inserted into RRD files until the file is fixed. So do not edit production
972map files. Instead do something like this:
973
974 cp map map.edit
975 vi map.edit
976 perl -c map.edit
977 mv map.edit map
978
979Use testentry.pl to test a rule before putting it into production. First run
980the Nagios check command from the command line to see what is returned. Copy
981this output and paste it into testentry.pl. Paste the rule into testentry.pl.
982Run testentry.pl to see how the output will be handled.
983
984Changes to the map file generally do not require a restart of Nagios.
985
986It may take awhile for data from a map entry to show up in an RRD file.
987This is partly due to the service check scheduling in Nagios, and partly
988due to the perfdata buffering of service_perfdata_file_processing_interval
989
990Increase debug level in nagiosgraph.conf to see what is happening.
991The debug_insert parameter determines the log level for collecting data.
992Output will go to the nagiosgraph log file. Keep an eye on the log file;
993it can grow big. Perhaps rotate it, or decrease log level when everything
994works.
995
996Share your work. If you have a good map file entry for standard Nagios
997plugins, then please post it on the forum.
998
999
1000
1001=head1 Managing Data and RRD Files
1002
1003nagiosgraph saves data in RRD files in the rrddir directory (specified in
1004nagiosgraph.conf). By default, nagiosgraph uses a directory for each host,
1005and the RRD files are named based on the service description (from Nagios)
1006and the data names (from the map file). For example, the default
1007configuration for the PING service results in RRD files like this:
1008
1009 /var/nagiosgraph/rrd/host/PING___pingloss.rrd
1010 /var/nagiosgraph/rrd/host/PING___pingrta.rrd
1011
1012Older versions of nagiosgraph kept all RRD files in a single directory.
1013This is controlled by the dbseparator variable in nagiosgraph.conf.
1014
1015Use the 'dump' and 'restore' options to rrdtool if you need to restructure
1016RRD files. You might want to split data from a single RRD file into
1017multiple files, or you might want to combine data from multiple RRD files
1018into a single file. Or you might simply want to change the name of a
1019data source. The dump option will emit data in XML format:
1020
1021 rrdtool dump service___db.rrd > service_db.xml
1022
1023You can modify the XML with any text editor, then convert to RRD format:
1024
1025 rrdtool restore service_db.xml service___db-new.rrd
1026
1027Unfortunately the RRD file schema is not dynamic. If an RRD file is created
1028with 2 data sources, more data sources cannot be added automatically. For
1029example, you start recording UPS temperature to an RRD file using the
1030following map rule:
1031
1032 /perfdata:temperature=([.\d]+)/
1033 and push @s, [ 'temp',
1034 [ 'temperature', GAUGE, $1 ] ];
1035
1036Later you decide to include critical and warning temperatures using this
1037map rule:
1038
1039 /perfdata:temperature=([.\d]+);([.\d]+);([.\d]+)/
1040 and push @s, [ 'temp',
1041 [ 'temperature', GAUGE, $1 ],
1042 [ 'warn', GAUGE, $2 ],
1043 [ 'crit', GAUGE, $3 ] ];
1044
1045The new rule will still record temperature, but critical and warning values
1046will be discarded, because they are not defined in the RRD file. You must do
1047a dump/edit/restore on the RRD file if you want to add critical/warning while
1048maintaining existing temperature data. Alternatively you can simply delete
1049the existing RRD file and let the new map rule create the new RRD file.
1050
1051What is the 'right' way to configure RRD files? Should all data from a single
1052service go into a single RRD file? Should each RRD file contain a single set
1053of data? Some best practices have evolved over the past 10 years, but as of
1054this writing (febrary 2010) there is no single 'right' way.
1055
1056Some people prefer to put all data from a single service into a single RRD
1057file, even if the data have different units. For example, for the PING
1058service their RRD files look something like this:
1059
1060 PING___ping.rrd (losspct, losswarn, losscrit, rta, rtawarn, rtacrit)
1061
1062Others prefer a separate file for each data source:
1063
1064 PING___losspct.rrd (losspct)
1065 PING___losswarn.rrd (losswarn)
1066 PING___losscrit.rrd (losscrit)
1067 PING___rta.rrd (rta)
1068 PING___rtawarn.rrd (rtawarn)
1069 PING___rtacrit.rrd (rtacrit)
1070
1071And others prefer something in between:
1072
1073 PING___loss.rrd (losspct, losswarn, losscrit)
1074 PING___rta.rrd (rta, rtawarn, rtacrit)
1075
1076It is a good idea to plan your configuration before you start recording data.
1077Although it is possible to reconfigure data after the RRD files are full,
1078doing so is somewhat tedious, especially for large numbers of hosts/services.
1079
1080The 1.4.4 release of nagiosgraph added a generic map rule that matches any
1081standard performance data. This rule puts the data into RRD files using this
1082structure:
1083
1084 host0/service___label.rrd (data[,warn][,crit][,min][,max])
1085
1086For example, for service0 with 3 perfdata labels and service1 with 1 perfdata
1087labels, the rule generates the following RRD files:
1088
1089 host0/service0___label0.rrd (data[,warn][,crit][,min][,max])
1090 host0/service0___label1.rrd (data[,warn][,crit][,min][,max])
1091 host0/service0___label2.rrd (data[,warn][,crit][,min][,max])
1092 host0/service1___label0.rrd (data[,warn][,crit][,min][,max])
1093
1094There are a few rrdtool parameters that affect size of the RRD files and the
1095resolution of data:
1096
1097 stepsize
1098 resolution
1099 heartbeat
1100 step
1101
1102These parameters are used only when an RRD file is created. By default they
1103are the same for all hosts and services, but they can be specified for
1104individual hosts, services, and or databases in the nagiosgraph configuration
1105file. To modify these values for an existing RRD file you must do a
1106dump/edit/restore. See the rrdtool documentation for details.
1107
1108
1109
1110=head1 Managing RRD Parameters
1111
1112The most important parameters are stepsize, heartbeat, and sampling interval.
1113A typical sign that these parameters are not set correctly is values of NaN
1114in the RRD files, which manifests as gaps in the graphs or empty graphs.
1115
1116A good rule of thumb is to use a heartbeat that is twice the sampling interval
1117and a stepsize equal to the sampling interval.
1118
1119In a default nagiosgraph configuration, the same parameters are applied to all
1120hosts and services. However, they can be specified for individual hosts and
1121services if necessary.
1122
1123The stepsize, in seconds, defines the nominal amount of time between data
1124points. The default value is 300 (5 minutes). The heartbeat, in seconds,
1125defines the amount of time between updates before a data point should be
1126considered unknown. The default value is 600 (10 minutes). The resolution
1127defines how many data points should be kept. The step defines how data points
1128are consolidated. The xfiles factor defines how unknown data points are
1129considered when consolidating data. These parameters are specified in the
1130nagiosgraph configuration file.
1131
1132The sampling interval is defined in Nagios (check_interval). This defines
1133how often a service will be checked.
1134
1135These values are used only when an RRD file is created. To change the
1136stepsize, heartbeat, or resolution of an existing RRD, one must dump the
1137RRD file to XML, modify the data, then restore the RRD file. Or simply
1138delete the RRD file and let nagiosgraph create a new one.
1139
1140
1141
1142=head1 Configuring Access Controls
1143
1144nagiosgraph does authorization (authz), not authentication (authn). Access
1145is granted or denied to users for specific services and hosts. There
1146are two ways to configure authorization: using Nagios configuration files
1147or using a standalone nagiosgraph configuration file.
1148
1149To use Nagios access controls, define the following in nagiosgraph.conf:
1150
1151 authzmethod=nagios3
1152 authzfile=/etc/nagios/cgi.cfg
1153
1154nagiosgraph respects the following Nagios variables:
1155
1156 use_authentication
1157 default_user_name
1158 authorized_for_all_hosts
1159 authorized_for_all_services
1160
1161To use nagiosgraph access controls, define the following in nagiosgraph.conf:
1162
1163 authzmethod=nagiosgraph
1164 authzfile=/usr/local/nagiosgraph/etc/access.conf
1165
1166The nagiosgraph access control file uses the following syntax:
1167
1168 host,service=user[,user[,...]]
1169
1170Wildcards are permitted to match hosts, services, or users. The exclamation
1171character negates permissions for a user. For example:
1172
1173 *= # deny access to everyone for all hosts and services
1174 *=* # grant access to everyone for all hosts and services
1175 host1=guest # grant access to guest for all services on host1
1176 host1,ping=!guest # deny access to guest for ping on host1
1177 *,ping=guest # grant access to guest for ping on any host
1178 *.foo.com=guest # grant access to guest for any host in foo.com
1179
1180Permissions are respected by all nagiosgraph CGI scripts, so you can safely
1181distribute URLs for specific graphs or reports.
1182
1183
1184
1185=head1 Troubleshooting
1186
1187First identify whether your problem is with data collection or data display.
1188
1189Are perfdata being collected by Nagios? Run a Nagios plugin directly and
1190make sure that it is working properly. For example:
1191
1192 check_ping -H host -w 100,10% -c 200,20%
1193
1194Are permissions set correctly? The nagios user must be able to write to
1195the rrd directory. The nagios user must be able to write to the nagiosgraph
1196log file. The web server user must be able to write to the nagiosgraph cgi
1197log file (which might be the same as the nagiosgraph log file for older
1198nagiosgraph installations). If the web server user does not have permission
1199to modify the log file, nagiosgraph cgi logging will end up in the web server
1200error log.
1201
1202Is nagiosgraph running? In nagiosgraph.conf, set debug_insert=5 then look
1203at the nagiosgraph log file. You should see messages from insert.pl. Ensure
1204that insert.pl is being called as expected, either periodically by Nagios or
1205in a loop.
1206
1207Are the RRD files being created? The nagios user must have write permission
1208on the rrd directory.
1209
1210Are the RRD files being modified? Check the RRD file timestamp.
1211
1212Are data being saved into RRD files? With debug_insert=3, look in the
1213nagiosgraph log file for errors or warnings from insert.pl. Problems with
1214map rules should be reported in the log file. If necessary, increase the
1215log level to debug_insert=5.
1216
1217Are the RRD file contents sane? Use 'rrdtool dump filename.rrd'. It is
1218normal for a new RRD file to be full of NaN. As the file is updated those
1219should be replaced with proper values. Ensure that the data source names in
1220the RRD file correspond to the names in the map rule.
1221
1222Are there old or unused RRD files lying about? Older versions of nagiosgraph
1223can be confused by multiple RRD files with the same data source for a single
1224host. If you change the map rule for a service, you might want to move the
1225old RRD files out of the rrd directory.
1226
1227If graphs are not being displayed, start by graphing a single host and service
1228with showgraph.cgi, for example showgraph.cgi?host=HOST&service=SERVICE. Set
1229debug_showgraph=3 in nagiosgraph.conf, then look for output in the nagiosgraph
1230log file or the web server error log.
1231
1232Be aware of what you are asking nagiosgraph to display. Start with just a
1233host and service, then get more specific. For example, each of these queries
1234will result in a different graph:
1235
1236 show.cgi?host=HOST&service=PING
1237 show.cgi?host=HOST&service=PING&db=ping
1238 show.cgi?host=HOST&service=PING&db=ping,losspct,losswarn
1239
1240To isolate problems in individual CGI scripts, use debug_show (show.cgi),
1241debug_showhost (showhost.cgi), debug_showservice (showservice.cgi), or
1242debug_showgroup (showgroup.cgi) as appropriate.
1243
1244For installations with many hosts and services, use the host/service
1245extensions when setting the log level (e.g. debug_showgraph_host = host)
1246to make the log information easier to grok.
1247
1248
1249
1250=head1 Internationalization
1251
1252Translations are in a single file, with one file per language. Strings for
1253both the cgi and javascript are in the same file. The javascript translations
1254and language detection are controlled by the cgi scripts.
1255
1256In order to minimize dependencies and overhead, nagiosgraph uses its own
1257system for internationalization. It has a syntax similar to gettext.
1258Strings are defined in english within the perl and javascript code. There
1259is no support for complex lexical structures - only string literals. The
1260user interface to nagiosgraph is (so far) simple enough that this suffices.
1261
1262To create a new translation, copy an existing translation file to a file
1263with the appropriate extension. For example, nagiosgraph_es.conf is the
1264file for generic spanish.
1265
1266Error messages are not translated.
1267
1268Language is detected from the HTTP_ACCEPT_LANGUAGE environment variable. The
1269first language in this list is the language used. If a language is specified
1270in the nagiosgraph configuration file, that language overrides anything in
1271the environment.
1272
1273The language can be specified as an argument to each cgi script, for example:
1274
1275 show.cgi?language=es
1276
1277Language specified in this manner overrides any environment or configuration.
1278
1279
1280
1281=head1 Enumeration of Files
1282
1283=over
1284
1285=item CHANGELOG
1286
1287History of changes
1288
1289=item INSTALL
1290
1291Example recipe for installing nagiosgraph
1292
1293=item README
1294
1295This file
1296
1297=item TODO
1298
1299A list of potential improvements to nagiosgraph
1300
1301=item install.pl
1302
1303Installation script
1304
1305=item lib/insert.pl
1306
1307Reads Nagios perfdata log and insert into RRD files
1308
1309=item cgi/show.cgi
1310
1311Generates an html page for the host/service specified
1312
1313=item cgi/showconfig.cgi
1314
1315Check the nagiosgraph configuration
1316
1317=item cgi/showgraph.cgi
1318
1319Generates the actual graph image used by other scripts
1320
1321=item cgi/showgroup.cgi
1322
1323Generates an html page for the group specified
1324
1325=item cgi/showhost.cgi
1326
1327Generates an html page for the host specified, showing all available services on the host
1328
1329=item cgi/showservice.cgi
1330
1331Generates an html page for the service specified, showing all hosts with that service
1332
1333=item cgi/testcolor.cgi
1334
1335Preview of colors for keywords in each color scheme
1336
1337=item etc/access.conf
1338
1339Access control file
1340
1341=item etc/datasetdb.conf
1342
1343Optional configuration for data sets
1344
1345=item etc/nagiosgraph.conf
1346
1347Primary configuration file for nagiosgraph
1348
1349=item etc/nagiosgraph_*
1350
1351Translations
1352
1353=item etc/groupdb.conf
1354
1355Configuration specific to showgroup.cgi
1356
1357=item etc/hostdb.conf
1358
1359Configuration specific to showhost.cgi
1360
1361=item etc/servdb.conf
1362
1363Configuration specific to showservice.cgi
1364
1365=item etc/rrdopts.conf
1366
1367Per-service options to rrdgraph
1368
1369=item etc/map
1370
1371Regular expression to identify services and specification for how to create RRD files
1372
1373=item etc/ngshared.pm
1374
1375Shared library of common perl subroutines
1376
1377=item examples/*
1378
1379Configuration examples
1380
1381=item share/graph.gif
1382
1383An icon for use in Nagios
1384
1385=item share/nagiosgraph.css
1386
1387CSS stylesheet
1388
1389=item share/nagiosgraph.js
1390
1391All of the JavaScript used by nagiosgraph
1392
1393=item share/nagiosgraph.ssi
1394
1395HTML for Nagios pages to enable graphs on mouseover
1396
1397=item t/*
1398
1399perl test scripts
1400
1401=item utils/testentry.pl
1402
1403A script for testing new map file entries
1404
1405=item utils/flat2hier.pl
1406
1407Script for converting RRD data from flat to hierarchy
1408
1409=back
1410
1411
1412
1413=head1 Sample Installation Layouts
1414
1415Here are samples of nagiosgraph/nagios installation layouts.
1416
1417separate, installed to /opt:
1418
1419 /opt/nagios/bin/
1420 /opt/nagios/etc/
1421 /opt/nagios/include/
1422 /opt/nagios/libexec/
1423 /opt/nagios/perl/
1424 /opt/nagios/sbin/
1425 /opt/nagios/share/
1426
1427 /opt/nagiosgraph/bin/insert.pl
1428 /opt/nagiosgraph/cgi-bin/show.cgi
1429 /opt/nagiosgraph/cgi-bin/showgraph.cgi
1430 /opt/nagiosgraph/etc/ngshared.pm
1431 /opt/nagiosgraph/etc/nagiosgraph.conf
1432 /opt/nagiosgraph/share/nagiosgraph.css
1433 /opt/nagiosgraph/share/nagiosgraph.js
1434
1435overlay, installed to /usr/local/nagios:
1436
1437 /usr/local/nagios/libexec/insert.pl
1438 /usr/local/nagios/sbin/show.cgi
1439 /usr/local/nagios/sbin/showgraph.cgi
1440 /usr/local/nagios/etc/ngshared.pm
1441 /usr/local/nagios/etc/nagiosgraph.conf
1442 /usr/local/nagios/share/nagiosgraph.css
1443 /usr/local/nagios/share/nagiosgraph.js
1444
1445Debian
1446
1447 /usr/lib/nagiosgraph/insert.pl
1448 /usr/lib/cgi-bin/nagiosgraph/show.cgi
1449 /usr/lib/cgi-bin/nagiosgraph/showgraph.cgi
1450 /etc/nagiosgraph/ngshared.pm
1451 /etc/nagiosgraph/nagiosgraph.conf
1452 /usr/share/nagiosgraph/htdocs/nagiosgraph.css
1453 /usr/share/nagiosgraph/htdocs/nagiosgraph.js
1454
1455Redhat
1456
1457 /usr/libexec/nagiosgraph/insert.pl
1458 /usr/lib/nagiosgraph/cgi-bin/show.cgi
1459 /usr/lib/nagiosgraph/cgi-bin/showgraph.cgi
1460 /etc/nagiosgraph/ngshared.pm
1461 /etc/nagiosgraph/nagiosgraph.conf
1462 /usr/share/nagiosgraph/htdocs/nagiosgraph.css
1463 /usr/share/nagiosgraph/htdocs/nagiosgraph.js
1464
1465
1466=head1 Sample Web Server Configuration
1467
1468Here are snippets from a typical (but basic) Apache server configuration.
1469
1470 ScriptAlias /nagiosgraph/cgi-bin/ "/opt/nagiosgraph/cgi/"
1471 <Directory "/opt/nagiosgraph/cgi">
1472 Options ExecCGI
1473 AllowOverride None
1474 Order allow,deny
1475 Allow from all
1476 </Directory>
1477 Alias /nagiosgraph "/opt/nagiosgraph/share"
1478 <Directory "/opt/nagiosgraph/share">
1479 Options None
1480 AllowOverride None
1481 Order allow,deny
1482 Allow from all
1483 </Directory>
1484
1485 ScriptAlias /nagios/cgi-bin "/opt/nagios/sbin"
1486 <Directory "/opt/nagios/sbin">
1487 Options ExecCGI
1488 AllowOverride None
1489 Order allow,deny
1490 Allow from all
1491 </Directory>
1492 Alias /nagios "/opt/nagios/share"
1493 <Directory "/opt/nagios/share">
1494 Options None
1495 AllowOverride None
1496 Order allow,deny
1497 Allow from all
1498 </Directory>
1499
1500
1501=head1 Platform Specific Notes
1502
1503=head2 Nagios Embedded PERL (ePN)
1504
1505The Nagios embedded PERL interpreter (ePN) does not understand every PERL
1506idiom. In particular, it has problems with perldoc. If you get errors
1507such as:
1508
1509 ePN failed to compile /usr/lib/cgi-bin/nagios3/insert.pl: "Missing right
1510 curly or square bracket at (eval 1) line 45, at end of line syntax error
1511 at (eval 1) line 52, at EOF" at /usr/lib/nagios3/p1.pl line 250
1512
1513then you must explicitly invoke PERL for insert.pl. For example,
1514for batch processing use this:
1515
1516 command_line /usr/bin/perl /usr/local/nagios/libexec/insert.pl
1517
1518or for immediate processing use this:
1519
1520 command_line /usr/bin/perl /usr/local/nagios/libexec/insert.pl "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
1521
1522
1523
1524=head2 CentOS 5 and Nagiosgraph 0.9
1525
1526 wget 'http://dag.wieers.com/rpm/packages/rrdtool/rrdtool-1.2.18-1.el5.rf.i386.rpm'
1527 wget 'http://dag.wieers.com/rpm/packages/rrdtool/perl-rrdtool-1.2.18-1.el5.rf.i386.rpm'
1528 wget 'http://dag.wieers.com/rpm/packages/rrdtool/rrdtool-devel-1.2.18-1.el5.rf.i386.rpm'
1529 wget 'http://mesh.dl.sourceforge.net/sourceforge/nagiosgraph/nagiosgraph-0.9.0.tgz'
1530 yum install -y libart_lgpl.i386
1531 rpm -hiv *rrdtool*.rpm
1532
1533 tar xzvf nagiosgraph-0.9.0.tgz
1534 cd nagiosgraph-0.9.0
1535 mkdir /usr/local/nagios/nagiosgraph
1536 cp -r . /usr/local/nagios/nagiosgraph/
1537 mkdir /usr/local/nagios/nagiosgraph/rrd
1538 chmod go+rX /usr/local/nagios/nagiosgraph
1539 chown nagios /usr/local/nagios/nagiosgraph/rrd
1540 mkdir -p /var/spool/nagios
1541 touch /var/log/nagiosgraph.log /var/spool/nagios/perfdata.log
1542 chown nagios.apache /var/log/nagiosgraph.log /var/spool/nagios/perfdata.log
1543 chmod 664 /var/log/nagiosgraph.log
1544 chmod 644 /var/spool/nagios/perfdata.log
1545
1546 ln -s /usr/local/nagios/nagiosgraph/nagiosgraph.conf /usr/local/etc/nagiosgraph.conf
1547
1548 cp nagiosgraph.css /usr/local/nagios/share/stylesheets
1549
1550
1551=head2 MacOSX 10.5 and Nagios 2.12
1552
1553Use the lib/insert.sh wrapper to ensure that perl is invoked properly.
1554
1555 define command {
1556 command_name process-service-perfdata
1557 command_line /usr/local/nagios/libexec/insert.sh "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
1558 }
1559
1560
1561=head2 Fedora Core 6 and HTTP output parsing
1562
1563The entry in the map file for HTTP does not work for Fedora core 6
1564with Nagios 2.6 and later. This is what did work.
1565
1566 # Service type: unix-www
1567 # ouput:OK - HTTP/1.1 302 Found - 0.002 second response time |time=0.001920s;;;0.000000 size=126B;;;0
1568 /output:.*?HTTP.*?([.0-9]+) sec/
1569 and push @s, [ http,
1570 [ rt, GAUGE, $1 ] ];
1571
1572
1573=head1 Notes For Developers
1574
1575The makefile rules control pretty much everything. To create the makefile,
1576
1577 perl Makefile.PL
1578
1579Basic targets are the same as any MakeMaker perl module.
1580
1581 make
1582 make test
1583 make install
1584 make clean
1585 make realclean
1586
1587There are rules to build a source distribution, Debian, and Redhat packages.
1588
1589 make dist creates nagiosgraph-x.y.z.tar.gz
1590 make deb-package creates nagsiograph-x.y.z.deb
1591 make rpm-package creates nagiosgraph-x.y.z.rpm
1592
1593If you would like to contribute to nagiosgraph, there are a few things you
1594should do to make your life and the lives of the other nagiosgraph developers
1595easier.
1596
1597=over
1598
1599=item *
1600
1601Please respect these design goals:
1602
1603=over
1604
1605=item 1.
1606
1607do not break existing installations
1608
1609=item 2.
1610
1611minimize dependencies
1612
1613=item 3.
1614
1615keep it simple
1616
1617=back
1618
1619=item *
1620
1621perlcritic
1622
1623Run perlcritic and fix all warnings before you commit. Be brutal:
1624
1625 perlcritic -1 cgi/*.cgi
1626 perlcritic -1 etc/*.pm
1627
1628or use the make rule to run them all:
1629
1630 make critic
1631
1632=item *
1633
1634unit tests
1635
1636Run the unit tests before modifying existing functionality. Write unit
1637tests before you add code.
1638
1639 make test
1640
1641=item *
1642
1643test coverage
1644
1645To generate code coverage reports, install Devel::Cover then run tests:
1646
1647 make test-coverage
1648
1649This will generate a cover_db directory with code coverage metrics.
1650
1651=item *
1652
1653profiling
1654
1655Use the perl profiler to see which parts of the code are taking most time.
1656Run the cgi script with DProf enabled, specifying args on the command line.
1657
1658 perl -d:DProf cgi/show.cgi
1659 perl -d:DProf cgi/showgraph.cgi host=HOST service=SERVICE
1660
1661Then view the profiling results.
1662
1663 dprofpp
1664
1665The bottlenecks are RRDs::graph (showgraph.cgi) and RRDs::info (show.cgi).
1666RRDs::info is invoked on each file in the rrd directory tree. On a 1.4GHz
1667G4 PPC, getting info on 500 files takes about 0.2 seconds.
1668
1669=item *
1670
1671internationalization (i18n)
1672
1673To get a list of all translated string constants, do the following:
1674
1675 grep '_(' cgi/*.cgi etc/*.pm | sed -e 's/.*_(\([^)]*\).*/\1/' | sort -u
1676 grep '_(' share/*.js | sed -e 's/.*_(\([^)]*\).*/\1/' | sort -u
1677
1678nagiosgraph uses a bare bones, home-grown, standalone implementation of
1679i18n. If you add strings to the user interface or error handling, please
1680follow the pattern used for other strings in the code. All translations
1681reside in a single file, with one file per language. Each file is used
1682by the cgi (directly) and the javascript (via the cgi).
1683
1684=item *
1685
1686configurations
1687
1688Be consistent in configuration files and documentation about where the
1689nagiosgraph files are installed, regardless of what you use. Use the
1690standalone layout, with Nagios installed at /usr/local/nagios and
1691nagiosgraph installed at /usr/local/nagiosgraph
1692
1693=item *
1694
1695perldoc
1696
1697You can preview the perldoc by doing the following:
1698
1699 perldoc install.pl
1700 perldoc cgi/show.cgi
1701 perldoc etc/ngshared.pm
1702
1703=back
1704
1705
1706
1707=head1 Project Testing/Code Summary
1708
1709Here are some project statistics as of 14feb12:
1710
1711Number of unit tests: 1307
1712
1713Test coverage:
1714
1715 stmt bran cond sub pod time total
1716 etc/ngshared.pm 82.5 77.3 67.4 91.6 0.0 100.0 77.0
1717
1718Platforms on which unit tests have been run:
1719
1720 os arch perl
1721 -------------------------------
1722 debian 5 ppc 5.10.0
1723 debian 6 i386,x64 5.10.1
1724
1725Platforms on which installation has been tested:
1726
1727 os arch method nagios
1728 -------------------------------------------------------------------------
1729 debian 5 ppc manual 3.2.0, 3.2.1, 3.2.2, 3.2.3
1730 debian 5 i386 deb 3.0.6
1731 ubuntu 10.04 i386,x64 deb, installer 3.2.0
1732 fedora 14 i386,x64 rpm, installer 3.2.3
1733 centos 5.5 i386 rpm, installer 3.2.3
1734 opensuse 11.3 i386 rpm, installer 3.2.1
1735 redhat 6 i386,x64 rpm, installer 3.2.3
1736
1737The codebase looks like this:
1738
1739 lines words bytes
1740 267 948 6974 cgi/export.cgi
1741 182 623 4987 cgi/show.cgi
1742 515 1447 12093 cgi/showconfig.cgi
1743 206 669 5245 cgi/showgraph.cgi
1744 194 709 5063 cgi/showgroup.cgi
1745 188 643 4986 cgi/showhost.cgi
1746 189 667 5021 cgi/showservice.cgi
1747 172 727 5344 cgi/testcolor.cgi
1748 3233 13606 113742 etc/ngshared.pm
1749 72 329 2162 lib/insert.pl
1750 5218 20368 165617 total
1751
1752 177 353 2791 share/nagiosgraph.css
1753 1473 5251 42421 share/nagiosgraph.js
1754 1 3 75 share/nagiosgraph.ssi
1755 1651 5607 45287 total
1756
1757 37 120 1087 t/01required_modules.t
1758 4139 11033 123394 t/02ngshared.t
1759 173 462 6351 t/03defaults.t
1760 161 509 4222 t/04show.t
1761 803 1983 25545 t/05permissions.t
1762 2270 3342 45556 t/06rules.t
1763 1529 2885 32559 t/07perfdata.t
1764 2111 4229 47498 t/09plugins.t
1765 232 620 7383 t/10backward.t
1766 31 84 1002 t/97pod.t
1767 20 73 608 t/98podcoverage.t
1768 18 71 591 t/99kwalitee.t
1769 11524 25411 295796 total
1770
1771 32 163 879 etc/access.conf
1772 23 92 873 etc/datasetdb.conf
1773 63 249 2279 etc/groupdb.conf
1774 42 164 1446 etc/hostdb.conf
1775 92 255 1828 etc/labels.conf
1776 384 2291 15329 etc/nagiosgraph.conf
1777 52 81 793 etc/nagiosgraph_de.conf
1778 52 92 865 etc/nagiosgraph_es.conf
1779 52 102 935 etc/nagiosgraph_fr.conf
1780 20 119 660 etc/rrdopts.conf
1781 16 78 480 etc/servdb.conf
1782 256 1448 9863 etc/map
1783 1084 5134 36230 total
1784
1785=cut
1786
1787