.\" 
.\" Copyright (c) 2006, Stefan Walter
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without 
.\" modification, are permitted provided that the following conditions 
.\" are met:
.\" 
.\"     * Redistributions of source code must retain the above 
.\"       copyright notice, this list of conditions and the 
.\"       following disclaimer.
.\"     * Redistributions in binary form must reproduce the 
.\"       above copyright notice, this list of conditions and 
.\"       the following disclaimer in the documentation and/or 
.\"       other materials provided with the distribution.
.\"     * The names of contributors to this software may not be 
.\"       used to endorse or promote products derived from this 
.\"       software without specific prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
.\" COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 
.\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 
.\" THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 
.\" DAMAGE.
.\" 
.\"
.\" CONTRIBUTORS
.\"  Stef Walter <stef@memberwebs.com>
.\"
.Dd April, 2006
.Dt bsnmp-ping 8
.Os bsnmp-ping 
.Sh NAME
.Nm bsnmp-ping
.Nd an SNMP module which measures latency and reachability to hosts over a time period.
.Sh DESCRIPTION
.Nm
is a module for 
.Xr bsnmpd 1
which allows you to measure latency and reachability. It sends out ICMP packets
to the configured hosts. A history of received packets is maintained, and you can
query via SNMP how many dropped packets, maximum/minumum latency and other stats 
for that history period. 
.Pp
.Sh MIBS
The counters will be available as a table under the following MIB:
.Bd -literal -offset indent
 .1.3.6.1.4.1.12325.1.204
.Ed
.Pp 
Or if the appropriate MIB.txt files have been installed:
.Bd -literal -offset indent
 enterprises.fokus.begemot.ping
.Ed
.Pp
The following SNMP MIBs are available for use (where X is the counter index):
.Bl -tag -width Fl
.It Ar ping.pingCount
The number of hosts to ping.
.It Ar ping.pingEntry.pingIndex.X
The index of the host.
.It Ar ping.pingEntry.pingHost.X
The host (address) to which ICMP packets are being sent.
.It Ar ping.pingEntry.pingInterval.X
The interval (in TimeTicks, 100th of a second) between sent ICMP packets.
.It Ar ping.pingEntry.pingHistory.X
The time period (in pingInterval units, above) that history for received ICMP packets is maintained.
.It Ar ping.pingEntry.pingResponses.X
The number of responses received in the (pingHistory) time period.
.It Ar ping.pingEntry.pingDropped.X
The number of dropped packets in the (pingHistory) time period.
.It Ar ping.pingEntry.pingLatencyAvg.X
The average latency (ms) of ICMP responses in the time period.
.It Ar ping.pingEntry.pingLatencyMin.X
The minimum latency (ms) of ICMP responses in the time period.
.It Ar ping.pingEntry.pingLatencyMax.X
The maximum latency (ms) of ICMP responses in the time period.
.El
.Sh OPTIONS
To activate the 
.Nm
module you must load the module in 
.Pa /etc/snmpd.config
and configure the location for the UNIX socket and 
.Xr bsnmp-regex.conf 5 
.Pp
Use the pingHost, pingInterval, and pingHistory SNMP MIBs in the 
.pa /etc/snmpd.config
file to setup the hosts you'd like to ping.
.Sh EXAMPLES
The following example pings two hosts. The first gets pinged once per second, and 
keeps a history for 300 seconds. The second is pinged 5 times per second, and the 
history is kept for 30 seconds.
.Pp
The following would be added to 
.Pa /etc/snmpd.config:
.Bd -literal -offset indent
begemotSnmpdModulePath."ping" = "/usr/local/lib/snmp_ping.so"
%ping
pingHost.1 = "10.8.9.2"
pingInterval.1 = 100
pingHistory.1 = 300

pingHost.2 = "2.2.2.2"
pingInterval.1 = 20
pingHistory.1 = 150
.Ed
.Sh SEE ALSO
.Xr bsnmpd 1
.Sh AUTHOR
.An Stef Walter Aq stef@memberwebs.com