From c0b5c5b1e62c9f6baf51963e374aba862ee21eaa Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Fri, 7 Mar 2008 02:06:47 +0000 Subject: Add proper documentation --- doc/JAILS-MIB.txt | 118 ------------------------------------------------------ doc/PCAP-MIB.txt | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/bsnmp-pcap.8 | 79 ++++++++++++++++++++---------------- 3 files changed, 162 insertions(+), 153 deletions(-) delete mode 100644 doc/JAILS-MIB.txt create mode 100644 doc/PCAP-MIB.txt diff --git a/doc/JAILS-MIB.txt b/doc/JAILS-MIB.txt deleted file mode 100644 index 258180b..0000000 --- a/doc/JAILS-MIB.txt +++ /dev/null @@ -1,118 +0,0 @@ --- --- Copyright (c) 2008 --- Stefan Walter --- --- Redistribution and use in source and binary forms, with or without --- modification, are permitted provided that the following conditions --- are met: --- 1. Redistributions of source code must retain the above copyright --- notice, this list of conditions and the following disclaimer. --- 2. 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. --- --- THIS SOFTWARE IS PROVIDED BY AUTHOR 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 AUTHOR 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. --- -PING-MIB DEFINITIONS ::= BEGIN - -IMPORTS - MODULE-IDENTITY, OBJECT-TYPE, Counter64, Integer32, TimeTicks, Unsigned32 - FROM SNMPv2-SMI - begemot - FROM BEGEMOT-MIB; - -jails MODULE-IDENTITY - LAST-UPDATED "200903010000Z" - ORGANIZATION "Stef Walter" - CONTACT-INFO "stef@memberwebs.com" - DESCRIPTION "The MIB for the bsnmp-jail module." - - ::= { begemot 1111 } - --- -------------------------------------------------------------------------- - -jailCount OBJECT-TYPE - SYNTAX Integer32 - MAX-ACCESS read-only - STATUS current - DESCRIPTION "The number jails running on the system." - ::= { jails 1 } - -jailTable OBJECT-TYPE - SYNTAX SEQUENCE OF JailEntry - MAX-ACCESS not-accessible - STATUS current - DESCRIPTION "A list of entries representing jails running on the system. The number of entries is given by the value of jailCount." - ::= { jails 2 } - -jailEntry OBJECT-TYPE - SYNTAX JailEntry - MAX-ACCESS not-accessible - STATUS current - DESCRIPTION "An entry containing information about a running jail." - INDEX { jailIndex } - ::= { jailTable 1 } - -JailEntry ::= - SEQUENCE { - jailIndex Integer32, - jailHost OCTET STRING, - jailInOctets Counter64, - jailInPackets Counter64, - jailOutOctets Counter64, - jailOutPackets Counter64, - } - -jailIndex OBJECT-TYPE - SYNTAX Integer32 - MAX-ACCESS read-only - STATUS current - DESCRIPTION "Index of this jailEntry." - ::= { jailEntry 0 } - -jailHost OBJECT-TYPE - SYNTAX OCTET STRING - MAX-ACCESS read-only - STATUS current - DESCRIPTION "The host name of this jail." - ::= { jailEntry 1 } - -jailInOctets OBJECT-TYPE - SYNTAX Counter64 - MAX-ACCESS read-only - STATUS current - DESCRIPTION "Number of octets received by this jail." - ::= { jailEntry 10 } - -jailInPackets OBJECT-TYPE - SYNTAX Counter64 - MAX-ACCESS read-only - STATUS current - DESCRIPTION "Number of packets received by this jail." - ::= { jailEntry 11 } - -jailOutOctets OBJECT-TYPE - SYNTAX Counter64 - MAX-ACCESS read-only - STATUS current - DESCRIPTION "Number of octets sent by this jail." - ::= { jailEntry 12 } - -jailOutPackets OBJECT-TYPE - SYNTAX Counter64 - MAX-ACCESS read-only - STATUS current - DESCRIPTION "Number of packets sent by this jail." - ::= { jailEntry 13 } - -END diff --git a/doc/PCAP-MIB.txt b/doc/PCAP-MIB.txt new file mode 100644 index 0000000..a490802 --- /dev/null +++ b/doc/PCAP-MIB.txt @@ -0,0 +1,118 @@ +-- +-- Copyright (c) 2008 +-- Stefan Walter +-- +-- Redistribution and use in source and binary forms, with or without +-- modification, are permitted provided that the following conditions +-- are met: +-- 1. Redistributions of source code must retain the above copyright +-- notice, this list of conditions and the following disclaimer. +-- 2. 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. +-- +-- THIS SOFTWARE IS PROVIDED BY AUTHOR 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 AUTHOR 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. +-- +PING-MIB DEFINITIONS ::= BEGIN + +IMPORTS + MODULE-IDENTITY, OBJECT-TYPE, Counter64, Integer32, TimeTicks, Unsigned32 + FROM SNMPv2-SMI + begemot + FROM BEGEMOT-MIB; + +pcap MODULE-IDENTITY + LAST-UPDATED "200903010000Z" + ORGANIZATION "Stef Walter" + CONTACT-INFO "stef@memberwebs.com" + DESCRIPTION "The MIB for the bsnmp-pcap module." + + ::= { begemot 1112 } + +-- -------------------------------------------------------------------------- + +pcapCount OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION "The number network monitors." + ::= { pcap 1 } + +pcapTable OBJECT-TYPE + SYNTAX SEQUENCE OF PcapEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION "A list of entries representing network monitors. The number of entries is given by the value of jailCount." + ::= { pcap 2 } + +pcapEntry OBJECT-TYPE + SYNTAX PcapEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION "An entry containing information about a network monitor." + INDEX { pcapIndex } + ::= { pcapTable 1 } + +PcapEntry ::= + SEQUENCE { + pcapIndex Integer32, + pcapDescr OCTET STRING, + pcapDevice OCTET STRING, + pcapFilter OCTET STRING, + pcapOctets Counter64, + pcapPackets Counter64, + } + +pcapIndex OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION "Index of this pcapEntry." + ::= { pcapEntry 0 } + +pcapDescr OBJECT-TYPE + SYNTAX OCTET STRING + MAX-ACCESS read-only + STATUS current + DESCRIPTION "A readable description of this network monitor." + ::= { pcapEntry 1 } + +pcapDescr OBJECT-TYPE + SYNTAX OCTET STRING + MAX-ACCESS read-only + STATUS current + DESCRIPTION "The device network traffic is being monitored on." + ::= { pcapEntry 2 } + +pcapDescr OBJECT-TYPE + SYNTAX OCTET STRING + MAX-ACCESS read-only + STATUS current + DESCRIPTION "The (tcpdump style) filter for traffic to monitor." + ::= { pcapEntry 3 } + +pcapOctets OBJECT-TYPE + SYNTAX Counter64 + MAX-ACCESS read-only + STATUS current + DESCRIPTION "Number of octets seen by the network monitor." + ::= { pcapEntry 10 } + +pcapPackets OBJECT-TYPE + SYNTAX Counter64 + MAX-ACCESS read-only + STATUS current + DESCRIPTION "Number of packets seen by the network monitor." + ::= { pcapEntry 11 } + +END diff --git a/doc/bsnmp-pcap.8 b/doc/bsnmp-pcap.8 index d3a73a6..ded4948 100644 --- a/doc/bsnmp-pcap.8 +++ b/doc/bsnmp-pcap.8 @@ -34,71 +34,80 @@ .\" CONTRIBUTORS .\" Stef Walter .\" -.Dd March, 2008 -.Dt bsnmp-jails 8 -.Os bsnmp-jails +.Dd April, 2006 +.Dt bsnmp-pcap 8 +.Os bsnmp-pcap .Sh NAME -.Nm bsnmp-jails -.Nd an SNMP module provides statistics regarding FreeBSD jails running on the system. +.Nm bsnmp-pcap +.Nd an SNMP module which captures network traffic and reports the number of +packets captured, and the throughput. .Sh DESCRIPTION .Nm is a module for .Xr bsnmpd 1 -which monitors network and other statistics for FreeBSD jails running on the system. -These statistics are gathered by the module. +which allows you to measure arbitrary network traffic. It uses the +.Xr pcap 3 +library (ie: think tcpdump) to filter traffic and then allows you to measure +the throughput in packets or octets. +.Pp +Multiple flows of traffic can be measured by the module. .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 + .1.3.6.1.4.1.12325.1.1112 .Ed .Pp Or if the appropriate MIB.txt files have been installed: .Bd -literal -offset indent - enterprises.fokus.begemot.jails + enterprises.fokus.begemot.pcap .Ed .Pp The following SNMP MIBs are available for use (where X is the counter index): .Bl -tag -width Fl -.It Ar jails.jailCount -The number of jails running on the system. -.It Ar jails.jailTable.jailEntry.jailIndex.X -The index of the jail in the table. -.It Ar jails.jailTable.jailEntry.jailHost.X -The hostname of the jail. -.It Ar jails.jailTable.jailEntry.jailInOctets.X -The number of octets received by the jail over the network. -.It Ar jails.jailTable.jailEntry.jailInPackets.X -The number of packets received by the jail over the network. -.It Ar jails.jailTable.jailEntry.jailOutOctets.X -The number of octets sent by the jail over the network. -.It Ar jails.jailTable.jailEntry.jailOutPackets.X -The number of packets sent by the jail over the network. -.It Ar jails.jailNetworkFilter -A tcpdump style filter for the network traffic. Only matched traffic -is counted in the jail statistics. +.It Ar pcap.pcapCount +The number of network monitors present. +.It Ar pcap.pcapTable.pcapEntry.pcapIndex.X +The index of the network monitor. +.It Ar pcap.pcapTable.pcapEntry.pcapDescr.X +A human readable description of the network monitor (may be an empty string). +.It Ar pcap.pcapTable.pcapEntry.pcapDevice.X +The network device that traffic is being monitored on. +.It Ar pcap.pcapTable.pcapEntry.pcapFilter.X +The filter used to select certain network packets for monitoring. Uses the +.Xr tcpdump 1 +syntax. +.It Ar pcap.pcapTable.pcapEntry.pcapOctets.X +The number of octets seen by the monitor. +.It Ar pcap.pcapTable.pcapEntry.pcapPackets.X +The number of packets seen by the monitor. .El .Sh OPTIONS To activate the .Nm module you must load the module in .Pa /etc/snmpd.config -.Pp -You can use the jailNetworkFilter SNMP MIB to configure which traffic -to count in the jail network statistics. +and use the pingDevice and pingFilter SNMP MIBs in the same file +to configure the traffic that you'd like to monitor. .Sh EXAMPLES -This example configures the module, and excludes traffic to/from the -10.0.0.0/8 network from the network monitoring. +The following example has two monitors. The first monitors all TCP traffic on +port 80. The second monitors all broadcast traffic. .Pp The following would be added to .Pa /etc/snmpd.config: .Bd -literal -offset indent -begemotSnmpdModulePath."jails" = "/usr/local/lib/snmp_jails.so" -%jails -jailNetworkFilter = "not net 10.0.0.0/8" +begemotSnmpdModulePath."pcap" = "/usr/local/lib/snmp_pcap.so" +%ping +pcapDescr.1 = "Websites" +pcapDevice.1 = "em0" +pcapFilter.1 = "tcp port 80" + +pcapDescr.1 = "Broadcast" +pcapDevice.1 = "em0" +pcapFilter.1 = "broadcast" .Ed .Sh SEE ALSO -.Xr bsnmpd 1, +.Xr bsnmpd 1 , .Xr tcpdump 1 .Sh AUTHOR .An Stef Walter Aq stef@memberwebs.com -- cgit v1.2.3