From 92034c311a745284c6a5675fe42dc84af21bd2a6 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sun, 2 Mar 2008 18:22:41 +0000 Subject: Initial import --- doc/BEGEMOT-MIB.txt | 59 ++++++++++++++ doc/FOKUS-MIB.txt | 57 +++++++++++++ doc/JAILS-MIB.txt | 118 +++++++++++++++++++++++++++ doc/Makefile.am | 12 +++ doc/bsnmp-jails.8 | 105 ++++++++++++++++++++++++ doc/man2html.pl | 230 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 581 insertions(+) create mode 100644 doc/BEGEMOT-MIB.txt create mode 100644 doc/FOKUS-MIB.txt create mode 100644 doc/JAILS-MIB.txt create mode 100644 doc/Makefile.am create mode 100644 doc/bsnmp-jails.8 create mode 100755 doc/man2html.pl (limited to 'doc') diff --git a/doc/BEGEMOT-MIB.txt b/doc/BEGEMOT-MIB.txt new file mode 100644 index 0000000..9d99eab --- /dev/null +++ b/doc/BEGEMOT-MIB.txt @@ -0,0 +1,59 @@ +-- +-- Copyright (c) 2001-2003 +-- Fraunhofer Institute for Open Communication Systems (FhG Fokus). +-- All rights reserved. +-- +-- Author: Harti Brandt +-- +-- 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. +-- +-- $Begemot: bsnmp/snmpd/BEGEMOT-MIB.txt,v 1.5 2004/08/06 08:47:07 brandt Exp $ +-- +-- Begemot private definitions and root. +-- +BEGEMOT-MIB DEFINITIONS ::= BEGIN + +IMPORTS + MODULE-IDENTITY + FROM SNMPv2-SMI + fokus + FROM FOKUS-MIB; + +begemot MODULE-IDENTITY + LAST-UPDATED "200201300000Z" + ORGANIZATION "Fraunhofer FOKUS, CATS" + CONTACT-INFO + " Hartmut Brandt + + Postal: Fraunhofer Institute for Open Communication Systems + Kaiserin-Augusta-Allee 31 + 10589 Berlin + Germany + + Fax: +49 30 3463 7352 + + E-mail: harti@freebsd.org" + DESCRIPTION + "The root of the Begemot subtree of the fokus tree." + ::= { fokus 1 } + +END diff --git a/doc/FOKUS-MIB.txt b/doc/FOKUS-MIB.txt new file mode 100644 index 0000000..d4671e8 --- /dev/null +++ b/doc/FOKUS-MIB.txt @@ -0,0 +1,57 @@ +-- +-- Copyright (c) 2001-2003 +-- Fraunhofer Institute for Open Communication Systems (FhG Fokus). +-- All rights reserved. +-- +-- Author: Harti Brandt +-- +-- 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. +-- +-- $Begemot: bsnmp/snmpd/FOKUS-MIB.txt,v 1.5 2004/08/06 08:47:08 brandt Exp $ +-- +-- Begemot private definitions and fokus root. +-- +FOKUS-MIB DEFINITIONS ::= BEGIN + +IMPORTS + MODULE-IDENTITY, enterprises + FROM SNMPv2-SMI; + +fokus MODULE-IDENTITY + LAST-UPDATED "200202050000Z" + ORGANIZATION "Fraunhofer FOKUS, CATS" + CONTACT-INFO + " Hartmut Brandt + + Postal: Fraunhofer Institute for Open Communication Systems + Kaiserin-Augusta-Allee 31 + 10589 Berlin + Germany + + Fax: +49 30 3463 7352 + + E-mail: harti@freebsd.org" + DESCRIPTION + "The root of the Fokus enterprises tree." + ::= { enterprises 12325 } + +END diff --git a/doc/JAILS-MIB.txt b/doc/JAILS-MIB.txt new file mode 100644 index 0000000..90ed4a9 --- /dev/null +++ b/doc/JAILS-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; + +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-ACESS read-only + STATUS current + DESCRIPTION "Number of octets received by this jail." + ::= { jailEntry 10 } + +jailInPackets OBJECT-TYPE + SYNTAX Counter64 + MAX-ACESS read-only + STATUS current + DESCRIPTION "Number of packets received by this jail." + ::= { jailEntry 11 } + +jailOutOctets OBJECT-TYPE + SYNTAX Counter64 + MAX-ACESS read-only + STATUS current + DESCRIPTION "Number of octets sent by this jail." + ::= { jailEntry 12 } + +jailOutPackets OBJECT-TYPE + SYNTAX Counter64 + MAX-ACESS read-only + STATUS current + DESCRIPTION "Number of packets sent by this jail." + ::= { jailEntry 13 } + +END diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..9db5f8a --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,12 @@ + +man_MANS = bsnmp-jails.8 + +# Simple way to make docs +html: + perl man2html.pl bsnmp-jails.8 > bsnmp-jails.8.html + +EXTRA_DIST = $(man_MANS) \ + man2html.pl \ + BEGEMOT-MIB.txt \ + FOKUS-MIB.txt \ + JAILS-MIB.txt diff --git a/doc/bsnmp-jails.8 b/doc/bsnmp-jails.8 new file mode 100644 index 0000000..d3a73a6 --- /dev/null +++ b/doc/bsnmp-jails.8 @@ -0,0 +1,105 @@ +.\" +.\" Copyright (c) 2008, 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 +.\" +.Dd March, 2008 +.Dt bsnmp-jails 8 +.Os bsnmp-jails +.Sh NAME +.Nm bsnmp-jails +.Nd an SNMP module provides statistics regarding FreeBSD jails running on the system. +.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. +.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.jails +.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. +.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. +.Sh EXAMPLES +This example configures the module, and excludes traffic to/from the +10.0.0.0/8 network from the network monitoring. +.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" +.Ed +.Sh SEE ALSO +.Xr bsnmpd 1, +.Xr tcpdump 1 +.Sh AUTHOR +.An Stef Walter Aq stef@memberwebs.com + diff --git a/doc/man2html.pl b/doc/man2html.pl new file mode 100755 index 0000000..a6a7c3f --- /dev/null +++ b/doc/man2html.pl @@ -0,0 +1,230 @@ +#!/usr/bin/perl + +# TODO: We need to make this more resilient +# currently expects args without enforcing + +$FIL = $NAM = $SEC = @ARGV[0]; + +$NAM =~ s/^([^.]+)\..+$/$1/; +$SEC =~ s/^.+\.([^.]+)$/$1/; + +$command = "groff"; +@args = split(" ", "-Tascii -mdoc $FIL"); + +$enable_include_links = 0; + +man($NAM, $SEC); + +sub man { + local($name, $section) = @_; + local($_, $title, $head, *MAN); + local($html_name, $html_section, $prefix); + local(@manargs); + local($query) = $name; + + # $section =~ s/^([0-9ln]).*$/$1/; + $section =~ tr/A-Z/a-z/; + + $prefix = "Man "; + if ($alttitle) { + $prefix = ""; + $title = &encode_title($alttitle); + $head = &encode_data($alttitle); + } elsif ($section) { + $title = &encode_title("${name}($section)"); + $head = &encode_data("${name}($section)"); + } else { + $title = &encode_title("${name}"); + $head = &encode_data("${name}"); + } + + print &html_header("$title"); + print "

Man Page: ${title}

"; + print "
\n";
+
+    $html_name = &encode_data($name);
+    $html_section = &encode_data($section);
+
+    #print Dumper($sectionpath);
+    #print "yy $section yy $manpath\n";
+    if ($name =~ /^\s*$/) {
+        print "Empty input, no man page given.\n";
+        return;
+    }
+
+    if (index($name, '*') != -1) {
+        print "Invalid character input '*': $name\n";
+        return;
+    }
+
+    if ($section !~ /^[0-9ln]\w*$/ && $section ne '') {
+        print "Sorry, section `$section' is not valid\n";
+        return;
+    }
+
+    if (!$section) {
+        if ($sectionpath->{$manpath}) {
+            $section = "-S " . $sectionpath->{$manpath}{'path'};
+        } else {
+            $section =  '';
+        }
+    } else {
+        if ($sectionpath->{$manpath}{$section}) {
+            $section = "-S " . $sectionpath->{$manpath}{$section};
+        } else {
+            $section = "-S $section";
+        }
+    }
+
+    # print "X $command{'man'} @manargs -- x $name x\n";
+    &proc(*MAN, $command, @args) ||
+        &mydie ("$0: open of $command{'man'} command failed: $!\n");
+    if (eof(MAN)) {
+        # print "X $command{'man'} @manargs -- x $name x\n";
+        print "Sorry, no data found for `$html_name" .
+                ($html_section ? "($html_section)": '') . "'.\n";
+        return;
+    }
+
+    local($space) = 1;
+    local(@sect);
+    local($i, $j);
+    while() {
+        # remove tailing white space
+        if (/^\s+$/) {
+            next if $space;
+            $space = 1;
+        } else {
+            $space = 0;
+        }
+
+        $_ = &encode_data($_);
+        if($enable_include_links &&
+           m,()?\#include()?\s+()?\<\;(.*\.h)\>\;()?,) {
+            $match = $4; ($regexp = $match) =~ s/\./\\\./;
+            s,$regexp,\$match\,;
+        }
+        /^\s/ &&                         # skip headers
+            s,((<[IB]>)?[\w\_\.\-]+\s*()?\s*\(([1-9ln][a-zA-Z]*)\)),&mlnk($1),oige;
+
+        # detect E-Mail Addreses in manpages
+        if (/\@/) {
+            s/([a-z0-9_\-\.]+\@[a-z0-9\-\.]+\.[a-z]+)/$1<\/A>/gi;
+        }
+
+        # detect URLs in manpages
+        if (m%tp://%) {
+            s,((ftp|http)://[^\s<>\)]+),$1,gi;
+        }
+
+        if (/^\S+/ && m%^([^<]+)%) {
+            $i = $1; $j = &encode_url($i);
+            s%^([^<]+)%$i%;
+            push(@sect, $1);
+        }
+        print;
+    }
+    close(MAN);
+
+    print "
   [ back | home ]
";
+    print "\n";
+    print "\n";
+
+    # Sleep 0.35 seconds to avoid DoS attacs
+    select undef, undef, undef, 0.35;
+}
+
+# encode unknown data for use in ...</TITILE>
+sub encode_title {
+    # like encode_url but less strict (I couldn't find docs on this)
+    local($_) = @_;
+    s/([\000-\031\%\&\<\>\177-\377])/sprintf('%%%02x',ord($1))/eg;
+    $_;
+}
+
+# encode unknown data for use in a URL <A HREF="...">
+sub encode_url {
+    local($_) = @_;
+    # rfc1738 says that ";"|"/"|"?"|":"|"@"|"&"|"=" may be reserved.
+    # And % is the escape character so we escape it along with
+    # single-quote('), double-quote("), grave accent(`), less than(<),
+    # greater than(>), and non-US-ASCII characters (binary data),
+    # and white space.  Whew.
+    s/([\000-\032\;\/\?\:\@\&\=\%\'\"\`\<\>\177-\377 ])/sprintf('%%%02x',ord($1))/eg;
+    s/%20/+/g;
+    $_;
+}
+# encode unknown data for use inside markup attributes <MARKUP ATTR="...">
+sub encode_attribute {
+    # rfc1738 says to use entity references here
+    local($_) = @_;
+    s/([\000-\031\"\'\`\%\&\<\>\177-\377])/sprintf('\&#%03d;',ord($1))/eg;
+    $_;
+}
+# encode unknown text data for using as HTML,
+# treats ^H as overstrike ala nroff.
+sub encode_data {
+    local($_) = @_;
+    local($str);
+
+    # Escape &, < and >
+    s,\010[><&],,g;
+    s/\&/\&\;/g;
+    s/\</\<\;/g;
+    s/\>/\>\;/g;
+
+    s,((_\010.)+),($str = $1) =~ s/.\010//g; "<I>$str</I>";,ge;
+    s,(.\010)+,$1,g;
+
+    if (!s,((.\010.)+\s+(.\010.)+),($str = $1) =~ s/.\010//g; "<B>$str</B>";,ge) {
+        s,((.\010.)+),($str = $1) =~ s/.\010//g; "<B>$str</B>";,ge;
+    }
+
+    s,.\010,,g;
+
+    $_;
+}
+
+sub html_header {
+    return qq{<HTML>
+<HEAD>
+<TITLE>$_[0]
+
+
+
+
+
+\n\n};
+}
+
+sub mlnk {
+    local($matched) = @_;
+    return qq{$matched};
+}
+
+sub proc {
+    local(*FH, $prog, @args) = @_;
+    local($pid) = open(FH, "-|");
+    return undef unless defined($pid);
+    if ($pid == 0) {
+    exec $prog, @args;
+    &mydie("exec $prog failed\n");
+    }
+    1;
+}
+
+# CGI script must die with error status 0
+sub mydie {
+	local($message) = @_;
+	print &html_header("Error");
+	print $message;
+
+print qq{
+

+Index Page and Help
+
+
+};
+
+	exit(0);
+}
-- 
cgit v1.2.3