
$FreeBSD: ports/net-mgmt/apan/files/patch-README,v 1.1 2004/04/01 13:45:58 pav Exp $

--- README.orig	Fri Mar 26 12:44:00 2004
+++ README	Fri Mar 26 13:01:48 2004
@@ -61,7 +61,7 @@
 7)  Add apan.sh to checkcommands.cfg;
 	define command {
 	command_name                   apan
-	command_line                   /usr/local/nagios/apan/apan.sh $ARG1$ $HOSTNAME$ "$SERVICEDESC$" $TIMET$ $ARG2$ $ARG3$
+	command_line                   /%%NAGIOSPLUGINSDIR%%/apan.sh $ARG1$ $HOSTNAME$ "$SERVICEDESC$" $TIMET$ $ARG2$ $ARG3$
 	}
 
 8)  Add sevices to nagios;
@@ -73,12 +73,118 @@
 	normal_check_interval          5
 }
 
-9)  Add the host/service to apan.cfg
-	host1;Disk-usage;/usr/local/nagios/rrd/host1_Disk-usage.rrd;c|d;c-used:AREA c-free:STACK d-used:AREA d-free:STACK;Disk usage;Bytes;-l 1 -b 1024
+or  ping service
+
+	define service {
+	host_name                      sheriff,bandit,WC-router-holland
+	service_description            Ping
+	check_command                  apan!ping!100.0,20%!500.0,60%
+	name                           Ping
+	use                            generic-service
+	normal_check_interval          1
+}
+
+Note: 
+- The second argument in the check_command is the name of the plugin that 
+apan will use. Read more about each plugin in next section of the docs. 
+- The third and fourth argument is used by the plugins, mainly to specify 
+warning and critical levels. 
+
+9) Creating RRD's
+I am no expert on RRD-tool, so maybe these examples are not so optimized.. 
+For example: 
+ rrdtool create /usr/local/nagios/rrd/raket_Net-use.rrd -s 60  \
+ DS:IN:COUNTER:300:0:U DS:OUT:COUNTER:300:U:U RRA:AVERAGE:0.5:1:50400 \
+ RRA:AVERAGE:0.5:60:43800
+
+Creates an RRD with two datasets named IN and OUT. The datasets are counters 
+supposed to store the number of network packages sent and received on a 
+network-interface. Samplerate is one minute and RRA's are set up to store 
+minut-average for 35 days and hour-average for 5 years. 
+
+To store Pig round-trip times you can use the same syntax, but change the 
+DS-type to 'GAUGE'; 
+rrdtool create /usr/local/nagios/rrd/bandit-ping.rrd -s 60 \
+DS:ping:GAUGE:300:0:U RRA:AVERAGE:0.5:1:50400 RRA:AVERAGE:0.5:60:43800
+
+The thing you probably want to look more at is the samplerate and heartbeat 
+values. Read more about RRD-tool at 
+
+http://people.ee.ethz.ch/~oetiker/webtools/rrdtool
+
+10) Configuring Apan
+
+Now its time for the hard step, the config-file apan.cfg. For each service
+you want apan to handle you must add a line in apan.cfg. The line is made
+up of 8 fields separated by ';'.
+
+The fields are: 
+
+Host name ; Service name ; RRD-file ; argument-1|argument-2|..argument-n ;
+DS-name-1:plot-function-1 DS-name-2:plot-function-2
+DS-name-n:plot-function-n ; Comment ; Y-unit ; Extra command
+
+In more detail: 
+
+Host name
+The name of the host, should be exactly the same name as in Nagios. 
+
+Service name
+The name of the service, should be exactly the same name as in Nagios. 
+
+RRD-file
+Full name of the RRD-file including the full path. 
+
+argument-1|argument-2|..argument-n 
+Arguments to be used by the plugin. The plugin will be called one time for
+each argument. Arguments can contain any character exept '|'.
+
+DS-name-1:plot-function-1 DS-name-2:plot-function-2 DS-name-n:plot-function-n
+DS-name is the name of the dataset that corresponds to the argument in the
+previous field. Plot-function is the format that rrdtool will use to plot
+the corresponding dataset when the graphs are constructed.
+
+Comment
+An additional informativ string that is displayed on the we-page with the
+graphs.
+
+Y-unit
+The unit displayed on the Y-axis in the graphs. 
+
+Extra command
+Here you can define extra command-line arguments that will be used by
+rrdtool when the graps are created.
+
+OK, that's the theoretical part, maybe some examples could help? 
+
+barbar;apan-disk;/usr/local/nagios/rrd/barbar_disk.rrd;/;-:LINE2;Disk-usage;%
+
+This line defines the service 'apan-disk' for host 'barbar'. The RRD,
+/usr/local/nagios/rrd/barbar_disk.rrd, have one DS named '-'. The plugin
+is called once with the argument '/'. When a graph is plotted, LINE2 (a
+medium-thick line) is used for drawing and the Y-axis is labeled '%'.
+
+sdl-www-01;Network-10;/usr/local/nagios/rrd/sdl-www-01_Network-10.rrd;public:.1.3.6.1.2.1.2.2.1.10.16777220|public:.1.3.6.1.2.1.2.2.1.16.16777220;10_IN:LINE2 
+10_OUT:LINE2;Network throughput;Bytes/sek;
+
+In this definition, the RRD have two datasets named '10_IN' and '10_OUT'.
+The plugin is called twice with the arguments
+'public:.1.3.6.1.2.1.2.2.1.10.16777220' and
+'public:.1.3.6.1.2.1.2.2.1.16.16777220' (The SNMP oid's for sent and
+received network packages).
+
+adsrv;Disk-usage;/usr/local/nagios/rrd/adsrv_disk.rrd;c;c-used:AREA c-free:STACK;Disk usage;Bytes;-l 1 -b 1024
+
+Here, the RRD have the datasets 'c-used' and 'c-free'. The plugin is
+called once wit the argument 'c'. When we generate a graph for this data,
+'c-used' will become a filled area with 'c-free' stacked upon it. When the
+y-axis is scaled, 1024 will be used as base-value and it will always start
+from 0 (-l 1 -b 1024 in the 'Extra command'-field).
+
+Simple?? For more information on the arguments, DS-values, etc - look at
+the plugin-documentation for the specific plugin used.
+
 
-10)  Create a RRD-file;
-rrdtool create /usr/local/nagios/rrd/host1_Disk-usage.rrd -s 60 DS:c-used:GAUGE:900:0:U DS:c-free:GAUGE:900:0:U DS:d-used:GAUGE:900:0:U DS:d-free:GAUGE:900:0:U RRA:AVERAGE:0.5:1:50400 RRA:AVERAGE:0.5:60:43800
-    Make sure that the Nagios-user have write-permissions on the file.
 
 11) Add a link to the graphs as an extended service info;
 	define serviceextinfo{  
@@ -90,6 +196,17 @@
 }
 
 12) Start Nagios!
+
+13) Debugging
+
+To enable debugging output from Apan, set the variables DEBUG to 1 and the
+variable DEBUGFILE to point to a file in apan.defs; Debugging output from
+the cgi's ic controlled by CGIDEBUG and CGIDEBUGFILE
+
+DEBUG=1
+DEBUGFILE=/tmp/apan.debug
+CGIDEBUG=1
+CGIDEBUGFILE=/tmp/apancgi.debug
 
 
 
