diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/BEGEMOT-MIB.txt | 59 | ||||
| -rw-r--r-- | doc/FOKUS-MIB.txt | 57 | ||||
| -rw-r--r-- | doc/JAILS-MIB.txt | 118 | ||||
| -rw-r--r-- | doc/Makefile.am | 12 | ||||
| -rw-r--r-- | doc/bsnmp-jails.8 | 105 | ||||
| -rwxr-xr-x | doc/man2html.pl | 230 |
6 files changed, 581 insertions, 0 deletions
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 <harti@freebsd.org> +-- +-- 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 <harti@freebsd.org> +-- +-- 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 <stef@memberwebs.com> +-- +-- 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 <stef@memberwebs.com> +.\" +.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 "<H1>Man Page: ${title}</H1>"; + print "<PRE>\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(<MAN>) { + # remove tailing white space + if (/^\s+$/) { + next if $space; + $space = 1; + } else { + $space = 0; + } + + $_ = &encode_data($_); + if($enable_include_links && + m,(<B>)?\#include(</B>)?\s+(<B>)?\<\;(.*\.h)\>\;(</B>)?,) { + $match = $4; ($regexp = $match) =~ s/\./\\\./; + s,$regexp,\<A HREF=\"$BASE/usr/include/$match\"\>$match\</A\>,; + } + /^\s/ && # skip headers + s,((<[IB]>)?[\w\_\.\-]+\s*(</[IB]>)?\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]+)/<A HREF="mailto:$1">$1<\/A>/gi; + } + + # detect URLs in manpages + if (m%tp://%) { + s,((ftp|http)://[^\s<>\)]+),<A HREF="$1">$1</A>,gi; + } + + if (/^<B>\S+/ && m%^<B>([^<]+)%) { + $i = $1; $j = &encode_url($i); + s%^<B>([^<]+)</B>%<B>$i</B>%; + push(@sect, $1); + } + print; + } + close(MAN); + + print "<H6> [ <a href='./'>back</a> | <a href='../../'>home</a> ]</h6>"; + print "</BODY>\n"; + print "</HTML>\n"; + + # Sleep 0.35 seconds to avoid DoS attacs + select undef, undef, undef, 0.35; +} + +# encode unknown data for use in <TITLE>...</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]</TITLE> +<link rev="made" href="mailto:wosch\@FreeBSD.ORG"> +<META name="robots" content="nofollow"> +<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type"> +<link rel="stylesheet" type="text/css" href="/swalter/style.css"> +</HEAD> +<BODY BGCOLOR="#FFFFFF" TEXT="#000000">\n\n}; +} + +sub mlnk { + local($matched) = @_; + return qq{<U>$matched</U>}; +} + +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{ +<p> +<A HREF="$BASE">Index Page and Help</A> +</BODY> +</HTML> +}; + + exit(0); +} |