This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: Apache/Throttle,  Next: Apache/Throttle/Log,  Prev: Apache/Template,  Up: Module List

Apache/Perl module for speed-based content negotiation
******************************************************

NAME
====

   Apache::Throttle - Apache/Perl module for speed-based content
negotiation

SYNOPSIS
========

     PerlTransHandler   Apache::Throttle

     # See the Apache::Throttle::Log manpage for options...
     PerlFixUpHandler   Apache::Throttle::Log

DESCRIPTION
===========

   Apache::Throttle is made up of two separate modules.

   Apache::Throttle is responsible for negotiating the content of certain
requests based on the speed of the connection.  It does this by checking
each request to see if it passes the following criteria:

   * it is a directory,

   * it does not end in a /,

   * and it contains a file named .throttle.

   If the request passes, Apache::Throttle will open the .throttle file
and read a number from it.  This is the time (in seconds) that the
requested file should take to send, ideally.  It then takes the sizes of
each of the files in the directory (ignoring any that start with a period)
and calculates the speed required to send the file to the client in under
the specified number of seconds.  Finally, it predicts the speed of the
current connection and maps the request to point to the largest file that
can still be sent in the ideal time.

   This implementation allows you to create a virtual copy of a file
simply by dropping the different versions of the file into a directory in
your HTML tree with same name that you want the file to have.  These files
can be named anything you want, although they should end in the same
extension for MIME-type mapping to work properly.  A script, `throttleimg'
in this node, is provided which automatically sets up this directory
structure from an existing GIF or JPEG image.

   Apache::Throttle::Log is responsible for measuring the speed that other
requests are transmitted at and calculating the average transmittion speed
for each connection.  This information is used by Apache::Throttle by
default, but it can also be accessed by other modules.  See *Note
Apache/Throttle/Log: Apache/Throttle/Log, for more information.

OPTIONS
=======

   This option can be set with the PerlSetVar operative in one of your
Apache configuration files.

ThrottleDebug
     Prints extra debugging information to the error log.

PredictSub
     Sets the subroutine called to predict a connection's speed.  This
     defaults to Apache::Throttle::Log::predict_speed.  If the package
     that the specified subroutine is in can be determined, it will be
     required automatically.

IDEAS
=====

   This doesn't only work with images.  It can also be used to send
different quality audio files, animations, etc.  You can even use a
directory named index.html if you want, with two different HTML pages for
high- and low-bandwidth users.  The possibilities are endless.  If you
think you've used this is a way no one has though of before, mail me.  I'd
love to hear about it.

AUTHOR
======

   Don Schwarz <dons@xnet.com>

SEE ALSO
========

   *Note Apache/Throttle/Log: Apache/Throttle/Log,, `throttleimg' in this
node, `mod_perl' in this node

COPYRIGHT
=========

   Copyright (c) 1998 Don Schwarz. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.


File: pm.info,  Node: Apache/Throttle/Log,  Next: Apache/TimedRedirect,  Prev: Apache/Throttle,  Up: Module List

Apache/Perl module to determine average speed
*********************************************

NAME
====

   Apache::Throttle::Log - Apache/Perl module to determine average speed

SYNOPSIS
========

     <Location /images>
       PerlSetVar       MaxUsers     100
       PerlSetVar       MinSize      100000
       PerlSetVar       MinDuration  0.1
       PerlSetVar       IDSub        Website::Session::session_id
       PerlTypeHandler  Apache::Throttle::Log
     </Location>

DESCRIPTION
===========

   Apache::Throttle::Log measures the speed that requests are transmitted
at and can calculate the average transmittion speed for a connection.

   It isn't particularly accurate yet, but seems to be close enough for
most applications.  If you know of a better way to measure the speed feel
free to send me suggestions, patches, etc.

OPTIONS
=======

   These options can be set with the PerlSetVar operative in one of your
Apache configuration files.

ThrottleDebug
     Prints extra debugging information to the error log.

MaxUsers
     Clear the speed hash when it reaches the specified number of users.
     I'm still looking for a better way of doing this.  If anyone has any
     suggestions, feel free to tell me.  This option is strongly
     recommended.

LogTypes
     Only log requests with a MIME-type that matches this regular
     expression.  This is useful for only logging "^image/" if you plan to
     serve images and the speeds for other large, compressable files are
     throwing off your averages.  It's probably much more efficient to
     keep all your images under one directory and just put a <Location>
     container around the handler definition though.

MinSize
     The minimum size in bytes that a request has to be for it to be
     logged.

MinDuration
     The minimum time in seconds that a request has to take for it to be
     logged.

StoreSpeeds
     The number of speeds to store for each connection.  These are averaged
     together to predict the speed of the next request.

ContinueChecking
     If this is set to a true value, Apache::Throttle::Log will continue
     logging requests from a user forever.  If unspecified or set false,
     however, it will only log as many requests as StoreSpeeds is set to,
     and then DECLINED requests from the same user.  This should be used
     when speeds are fairly constant and Apache::Throttle is putting a
     strain on your webserver.

IDSub
     This specifies the subroutine that Apache::Throttle::Log will get the
     hash key from.  The subroutine will be called with one argument: the
     Apache request object, and will be expected to return a scalar.  This
     scalar will be used as the hash key to store the connection
     information.  Defaults to the remote IP address for the request.

AUTHOR
======

   Don Schwarz <dons@xnet.com>

SEE ALSO
========

   *Note Apache/Throttle: Apache/Throttle,, `mod_perl' in this node

COPYRIGHT
=========

   Copyright (c) 1998 Don Schwarz. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.


File: pm.info,  Node: Apache/TimedRedirect,  Next: Apache/Traffic,  Prev: Apache/Throttle/Log,  Up: Module List

an Apache (mod_perl) TransHandler
*********************************

NAME
====

   Apache::TimedRedirect - an Apache (mod_perl) TransHandler

SYNOPSIS
========

     use Apache::TimedRedirect;

     requires TimePeriod be installed (go to nearest CPAN)
     requires Apache have mod_perl installed.

     httpd.conf entry...
     **** NOTE ***
     CANNOT be inside <LOCATION></LOCATION> tags
     PerlTransHandler Apache::TimedRedirect
     PerlSetVar B<redirecturl> http://www.somewhere.far/
     PerlSetVar B<timewindow> 'hr {6am-8pm}'
     PerlSetVar B<uriregex> foo|bar|do or maybe \..*(foo)>
     PerlSetVar B<log> 1
     PerlSetVar B<excludeip> 127.0.0.0

DESCRIPTION
===========

   Apache::TimedRedirect is a mod_perl TransHandler module that allows the
configuration of a timed redirect. In other words if someone enters a a
website  and the URI matches a regex AND it is within a certain time
period they will be redirected somewhere else.

   It was first created to 'politely' redirect visitors away from database
driven sections of a website while the databases were being refreshed.

PerlSetVar's
------------

   *redirecturl* - the place where visitors are sent if *timewindow* and
*uriregex* are true.

   *timewindow* - the time period(s) at which redirect should place. The
format is detailed in Time::Period manpage.

   *uriregex* a perl regex describing the URI constraints for redirection

   log log info via STDERR .

   *excludeip* host IP address (XXX.XXX.XXX.XXX) of a host that is allowed
to bypass redirection. This is a literal ip not a regex.

   Remember that this is embedding itself in the your Apache webserver so
you should test before committing to production. We have used it with
Apache 1.3.0, 1.2.5 with mod_perl 1.12 and 1.15 in medium traffic sites
(400k-500k hits weekly).

AUTHOR
======

   Peter G. Marshall, mitd@mitd.com Thanks to Patrick Ryan for
Time::Period that made this a snap.

   Copyright (c) 1998 Peter G. Marshall. All rights reserved.  This
program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself

SEE ALSO
========

   `perl(1)' in this node, `Time::Period(3)' in this node, `mod_perl(1)'
in this node


File: pm.info,  Node: Apache/Traffic,  Next: Apache/TransLDAP,  Prev: Apache/TimedRedirect,  Up: Module List

Tracks hits and bytes transferred on a per-user basis
*****************************************************

NAME
====

   Apache::Traffic - Tracks hits and bytes transferred on a per-user basis

SYNOPSIS
========

     # Place this in your Apache's httpd.conf file
     PerlLogHandler Apache::Traffic

DESCRIPTION
===========

   This module tracks the total number of hits and bytes transferred per
day by the Apache web server, on a per-user basis.  This allows for
real-time statistics without having to parse the log files.

   After installation, add this to your Apache's httpd.conf file and
restart the server:

     PerlLogHandler	Apache::Traffic

   The statistics are then available through the 'traffic' script, which
is included in this distribution.  See the section VIEWING STATISTICS for
more details.

PREREQUISITES
=============

   You need to have compiled mod_perl with the LogHandler hook in order to
use this module. Additionally, the following modules are required:

     o IPC::Shareable
     o IPC::SysV
     o DB_File
     o Date::Parse

   Your OS must also support SysV IPC (shared memory and semaphores).  If
this is not the case, this module will be useless to you.

INSTALLATION
============

   To install this module, move into the directory where this file is
located and type the following:

     perl Makefile.PL
     make
     make test
     make install

   This will install the module into the Perl library directory.

   Once installed, you will need to modify your web server's configuration
file so it knows to use Apache::Traffic during the logging phase:

     PerlLogHandler Apache::Traffic

   Restart your web server.

   As of this writing, there is a problem with IPC::Shareable which will
cause segmentation faults in httpd processes if Apache::Traffic is run
long enough (at least this is the case under Linux).  This distribution
contains a patch named 'share.patch', which will fix the problem.

   If Apache::Traffic does not appear to work correctly (look in your
server's error_log for problems), make sure the semaphore and shared
memory segments are not already allocated for another purpose.  If this is
the case, you can change the constants SHMKEY, SEMKEY, and DBPATH at the
top of the Apache::Traffic module, and reinstall.

HOW IT WORKS
============

   Each time a request is served, the Apache::Traffic log handler is
called which increments the byte and hit totals for the owner of the
resource.

   The owner of the resource is determined in the following way:

     o If the Perl variable Owner has been set for the directory, its
       value is used.  For example:

     <Directory /home/root/www/mark>
       PerlSetVar Owner mark
     </Directory>

     This would declare user mark as the owner of everything under
     the specified directory.  The value can be either the username
     or UID of the user.

     This value can also be a fake user (i.e. a username which is
     not present in the passwd file).  In this case, the username is
     stored (rather than the UID).

     o If the request is to a virtual host, the owner of the document
       root is used.

     o If neither of the above methods work, the owner of the file
       is used.

   The hit and byte total information is stored in shared memory to
minimize processing.  On the first request of each day, all previous data
in shared memory is automatically moved to permanent storage.  This means
that no more than one day's worth of information is ever stored in shared
memory, and prevents performance degradation as data accumulates.  This
separation of data is transparent from the end-user perspective.

   If you would rather not have the data moved into the dbm file, you can
set USE_DBM to 0 at the top of the Traffic.pm module and reinstall.

   Shared memory segments are not preserved through reboots.  If you
reboot your machine multiple times a day, Apache::Traffic will be of
questionable value to you.  I run Linux, so of course, I only reboot when
I've upgraded the OS. ;-)  This area may be improved in the future (at
least for orderly shutdowns).

VIEWING STATISTICS
==================

   A script named 'traffic' is included in this distribution, which allows
you to view the totals for a given user.  Note that this script will not
run properly until Apache::Traffic has recorded at least one page request.

   The basic syntax for the script is:

     traffic [options] [username]

   If username is not specified, the effective UID of the person running
the script is used.  By default, only data for the current day is
displayed.

   The following options are supported:

     -start=starting_date

     Specifies the starting date that you wish to see data for.  The
     date specifications can take any format supported by the
             Date::Parse module.  If -end is not specified, all data between
             -start and the current day is displayed.

     -end=ending_date

     Specifies the ending date that you wish to see data for.

     -days=num_days

     Specifies the number of days you want to see information for
             relative to the value of -start (or the current day if -start
             is not specified).  The value can be either positive
             or negative.

     -user=username

     Specifies the user you want to see data for.  Multiple
             -user specifications are allowed.  The users can also be
             specified as non-option arguments.  Both UIDs and usernames
             are allowed.

     -all

     Displays all data present within the given time period.
     
       -reverse

     If present, the information is sorted in descending order based
     on date.

     -units=unit

     Specifies the unit to display transfer totals in.  Acceptable
             values are 'Bytes', "Kilobytes', 'Megabytes', or 'Gigabytes'.
             Only the first character of the unit need be specified.  The
             default is Bytes.

     -summary

     If -summary is present, aggregate totals for the period
             being viewed are displayed, rather than daily totals.

     -n

     If the -n option is present, the report displays UIDs rather than
     converting them to usernames.  In the case of a "fake" user,
             the username will still be displayed (which is a way to tell
             is a user is fake or not).

     -remove

     If the -remove option is present, all data within the specified
             time period is permanently removed.  Only root is allowed to
     perform this operation (see the SECURITY NOTES section though).
             The operation must be confirmed prior to being carried out.

ACCESSING INFORMATION DIRECTLY
==============================

   If the supplied traffic script is not sufficient for your needs, you
may access the raw data directly.  The following functions are available
for import into your scripts.

     fetch([START], [END], [WANTUID], [ALL], [USER LIST])

     This function retrieves all data between START and END times,
             inclusive, for the users specified in USER LIST. Both START and
             END should be UTC timestamps.  The function automatically
             normalizes the timestamps to be on day boundaries.

     If WANTUID is true, usernames are not looked up.  If ALL is true,
             data for all users is returned and USER_LIST is ignored.
             If ALL is true, data for all users is returned and
             USER_LIST is ignored.

     On success, the function returns a complex hash reference, which
             contains the requested data:

     use Apache::Traffic qw( fetch remove error );

     $ref = fetch(time, time, 0, 0, 'maurice');
     foreach $day (%$ref) {
       foreach $user (%{ $ref->{$day} }) {
                         print scalar gmtime $day, " $user\n";
                         print "  BYTES: $ref->{$day}{$user}{bytes}\n";
                         print "   HITS: $ref->{$day}{$user}{hits}\n\n";
                       }
     }

     Note that the timestamps are stored internally in GM time,
             although START and END should be in local time.  We do this
             so we don't have to worry about daylight savings.

     The function returns undef on error, in which case you can call
     the error() function to determine what went wrong.

     remove([START], [END])

     This function removes all data between the START and END times,
     inclusive.

     The fuction returns true on success and undef on error, in which
     case you can call the error() function to determine what went
     wrong.

     error()

     Returns a string describing the last error condition encountered.

SECURITY NOTES
==============

   By default, the shared memory segments, semaphores, and DBM file are
created with permissions of 0644.  However, these resources must be owned
by whatever user the server runs as (normally user 'nobody').  This means
that your users could create CGI scripts to play with the data.  For this
reason, the information maintained by Apache::Traffic should not be relied
upon for auditing purposes, and is intended mainly for use in friendly
environments.

AUTHOR
======

   Copyright (C) 1997, Maurice Aubrey <maurice@hevanet.com>. All rights
reserved.

   This module is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.

SEE ALSO
========

   perl(1), mod_perl(3)


File: pm.info,  Node: Apache/TransLDAP,  Next: Apache/URI,  Prev: Apache/Traffic,  Up: Module List

An Apache+mod_perl Trans Handler
********************************

NAME
====

   Apache::TransLDAP - An Apache+mod_perl Trans Handler

SYNOPSIS
========

     PerlSetVar LDAPServer ldaphost.my.org   # Default: localhost
     PerlSetVar LDAPPort   389               # Default: 389
     PerlSetVar LDAPBase   o=My,c=US         # Default: Empty String
     PerlSetVar UIDAttr    uid               # Default: uid
     PerlSetVar URIAttr    labeledURI        # Default: labeledURI

     PerlTransHandler Apache::TransLDAP

DESCRIPTION
===========

   This module is designed to work with mod_perl and my Net::LDAPapi
module (http://www.wwa.com/~donley/).  Future versions will use PerLDAP.

   This is mostly an example of how a Trans handler can be implemented in
Perl.  Be sure to enable Trans handlers when configuring and installing
mod_perl.

   I welcome feedback on this module and any others I've developed.

AUTHOR
======

   Clayton Donley <donley@wwa.com> http://www.wwa.com/~donley/

COPYRIGHT
=========

   Copyright (c) 1998 Clayton Donley - All Rights Reserved

   This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


File: pm.info,  Node: Apache/URI,  Next: Apache/UploadSvr,  Prev: Apache/TransLDAP,  Up: Module List

URI component parsing and unparsing
***********************************

NAME
====

   Apache::URI - URI component parsing and unparsing

SYNOPSIS
========

     use Apache::URI ();
     my $uri = $r->parsed_uri;

     my $uri = Apache::URI->parse($r, "http://perl.apache.org/");

DESCRIPTION
===========

   This module provides an interface to the Apache *util_uri* module and
the *uri_components* structure.

METHODS
=======

Apache::parsed_uri
     Apache will have already parsed the requested uri components, which
     can be obtained via the *parsed_uri* method defined in the Apache
     class.  This method returns an object blessed into the *Apache::URI*
     class.

          my $uri = $r->parsed_uri;

parse
     This method will parse a URI string into uri components which are
     stashed in the *Apache::URI* object it returns.

          my $uri = Apache::URI->parse($r, "http://www.foo.com/path/file.html?query+string");

     This method is considerably faster than using URI::URL:

          timethese(5000, {
          	C => sub { Apache::URI->parse($r, $test_uri) },
          	Perl => sub { URI::URL->new($test_uri) },
          });

          Benchmark: timing 5000 iterations of C, Perl...
            C:  1 secs ( 0.62 usr  0.04 sys =  0.66 cpu)
            Perl:  6 secs ( 6.21 usr  0.08 sys =  6.29 cpu)

unparse
     This method will join the uri components back into a string version.

          my $string = $uri->unparse;

scheme
          my $scheme = $uri->scheme;

hostinfo
          my $hostinfo = $uri->hostinfo;

user
          my $user = $uri->user;

password
          my $password = $uri->password;

hostname
          my $hostname = $uri->hostname;

port
          my $port = $uri->port;

path
          my $path = $uri->path;

rpath
     Returns the path minus path_info.

          my $path = $uri->rpath;

query
          my $query = $uri->query;

fragment
          my $fragment = $uri->fragment;

AUTHOR
======

   Doug MacEachern

SEE ALSO
========

   perl(1).


File: pm.info,  Node: Apache/UploadSvr,  Next: Apache/UploadSvr/User,  Prev: Apache/URI,  Up: Module List

A Lightweight Publishing System for Apache
******************************************

NAME
====

   Apache::UploadSvr - A Lightweight Publishing System for Apache

SYNOPSIS
========

DESCRIPTION
===========

   This module implements a small publishing system for a web server with
authentication, simple security, preview, directory viewer and an interface
to delete files. The whole system is actually running software on
www.kulturbox.de at the time of publishing (i.e. Summer 1998).

   The author is looking for somebody to take this code over for
maintainance.

CONFIGURATION
=============

   httpd.conf:

     PerlSetVar Auth_DBI_data_source dbi:mSQL:authen
     PerlSetVar Auth_DBI_pwd_table   usertable
     PerlSetVar Auth_DBI_grp_table   grouptable
     PerlSetVar Auth_DBI_uid_field   user
     PerlSetVar Auth_DBI_grp_field   group
     PerlSetVar Auth_DBI_pwd_field   password
     PerlSetVar stageuri /STAGE
     PerlSetVar Apache_UploadSvr_Usermgr "Apache::UploadSvr::User"
     PerlSetVar Apache_UploadSvr_myuri /perl/user/up
     PerlSetVar Apache_UploadSvr_transdir /usr/local/apache/trans
     PerlSetVar Apache_UploadSvr_trashdir /usr/local/apache/trash

     <Files "...">
       PerlSetVar DirCache .dircache
       SetHandler perl-script
       PerlHandler Apache::UploadSvr::Directory
       AuthName stadtplandienst
       AuthType Basic
       PerlAuthenHandler Apache::AuthenDBI
       require valid-user
     </Files>

     <Location /perl/user/up>
       PerlHandler Apache::UploadSvr
     </Location>

   Change the permissions for the whole document tree to give the server
write access.

SECURITY
========

EXPORT
======

BUGS
====

COPYRIGHT
=========

   The application and accompanying modules are Copyright KULTURBOX,
Berlin.  It is free software and can be used, copied and redistributed at
the same terms as perl itself.

AUTHOR
======

   Andreas Koenig <koenig@kulturbox.de>


File: pm.info,  Node: Apache/UploadSvr/User,  Next: Apache/Usertrack,  Prev: Apache/UploadSvr,  Up: Module List

Identify users and permissions Apache::UploadSvr
************************************************

NAME
====

   Apache::UploadSvr::User - Identify users and permissions
Apache::UploadSvr

SYNOPSIS
========

   Apache::UploadSvr::User->new($mgr);

DESCRIPTION
===========

   This class implements a mapping between user-ID and user attributes.
The backend is provided by a mSQL-1 database with the following structure:

     CREATE TABLE usertable (
       user CHAR(12) NOT NULL PRIMARY KEY,
       email CHAR(64),
       firstname CHAR(32),
       lastname CHAR(32),
       fullname CHAR(64),
       salut CHAR(4),
       lastlogin CHAR(10),
       introduced CHAR(10),
       password CHAR(13),
       changedon CHAR(10),
       changedby CHAR(10)
     )

   user corresponds to the username with which the users identify in the
authentication stage. email is their email address where the transaction
tickets are delivered to. `lastname' is their family name.  <fullname> is
whatever the fullname is composed of in the local culture.  `salut' is the
salutation like `Herr' or `Mister'. `lastlogin' is the timestamp that is
updated with every request. `introduced' is the timestamp when the user
got registered (not used in this uploadserver).  password is the crypted
password in the default upload server. If the authentication handler uses
a different table, then this field is not needed. `changedon' and
`changedby' are not used in this application, they are only used as
interesting facts for the administrator.

     CREATE TABLE perms (
       user CHAR(12),
       permitted CHAR(32)
     )

   This table has a 1 to N mapping of users to directories they have write
access to.

   The constructor ->new takes as a single argument an Apache::UploadSvr
object and returns an object that has the above described fields as object
attributes. The attribute `permitted' is computed from the `perms' table
so that its value is an anonymous list of the directories the user has
write permission to. A typical structure of such an object would be:

     bless( {
       'introduced' => 875601758,
       'password' => 'rtthXtbR5tjit',
       'fullname' => 'Andreas J. König',
       'changedby' => 'andreas',
       'lastname' => 'König',
       'changedon' => 875601758,
       'email' => 'k',
       'firstname' => 'Andreas',
       'salut' => 'Herr',
       'lastlogin' => '0903739665',
       'permitted' => [
                        '/'
                      ],
       'user' => 'andreas'
     }, 'Apache::UploadSvr::User' )

   The method ->has_perms($obj) returns true if the current user has write
access to a file or dircetory. What counts here are database entries, not
file system permissions.

CONFIGURATION
=============

SECURITY
========

BUGS
====

AUTHOR
======

   Andreas Koenig <koenig@kulturbox.de>

COPYRIGHT, LICENSE
==================

   These programs or modules are Copyright (C) 1997-1998 Kulturbox,
Berlin, Germany.

   They are free software; you can redistribute them, use and/or modify
them under the same terms as Perl itself.


File: pm.info,  Node: Apache/Usertrack,  Next: Apache/Util,  Prev: Apache/UploadSvr/User,  Up: Module List

Emulate the mod_usertrack apache module
***************************************

NAME
====

   Apache::Usertrack - Emulate the mod_usertrack apache module

SYNOPSIS
========

     PerlFixupHandler Apache::Usertrack

     PerlSetVar Usertrack On

PREREQUISITES
=============

   This module uses the Time::HiRes module.

DESCRIPTION
===========

   To be written. :-)

BUGS / TODO
===========

   We don't do expire stuff yet.

   Documentation.

   Support for systems without gettimeofday.

   Patches are most welcome! :-)  See mod_usertrack.c in the
<apachedist>/src/modules/standard/ directory for 'the original' it's quite
simpel C code!

AUTHOR
======

   Copyright (C) 1998, Ask Bjoern Hansen <ask@netcetera.dk>. All rights
reserved. This module is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.

SEE ALSO
========

   perl(1), mod_perl(3)


File: pm.info,  Node: Apache/Util,  Next: Apache/VMonitor,  Prev: Apache/Usertrack,  Up: Module List

Interface to Apache C util functions
************************************

NAME
====

   Apache::Util - Interface to Apache C util functions

SYNOPSIS
========

     use Apache::Util qw(:all);

DESCRIPTION
===========

   This module provides a Perl interface to some of the C utility functions
available in Perl.  The same functionality is avaliable in libwww-perl, but
the C versions are faster:

     use Benchmark;
     timethese(1000, {
         C => sub { my $esc = Apache::Util::escape_html($html) },
         Perl => sub { my $esc = HTML::Entities::encode($html) },
     });

     Benchmark: timing 1000 iterations of C, Perl...
             C:  0 secs ( 0.17 usr  0.00 sys =  0.17 cpu)
          Perl: 15 secs (15.06 usr  0.04 sys = 15.10 cpu)

     use Benchmark;
     timethese(10000, {
         C => sub { my $esc = Apache::Util::escape_uri($uri) },
         Perl => sub { my $esc = URI::Escape::uri_escape($uri) },
     });

     Benchmark: timing 10000 iterations of C, Perl...
             C:  0 secs ( 0.55 usr  0.01 sys =  0.56 cpu)
          Perl:  2 secs ( 1.78 usr  0.01 sys =  1.79 cpu)

FUNCTIONS
=========

escape_html
     This routine replaces unsafe characters in $string with their entity
     representation.

          my $esc = Apache::Util::escape_html($html);

escape_uri
     This function replaces all unsafe characters in the $string with their
     escape sequence and returns the result.

          my $esc = Apache::Util::escape_uri($uri);

unescape_uri
     This function decodes all %XX hex escape sequences in the given URI.

          my $unescaped = Apache::Util::unescape_uri($safe_uri);

unescape_uri_info
     This function is similar to unescape_uri() but is specialized to
     remove escape sequences from the query string portion of the URI. The
     main difference is that it translates the "+" character into spaces
     as well as recognizing and translating the hex escapes.

     Example:

          $string = $r->uri->query;
          my %data = map { Apache::Util::unescape_uri_info($_) }
                       split /[=&]/, $string, -1;

          This would correctly translate the query string
          ``name=Fred+Flintstone&town=Bedrock'' into the hash:

          data => 'Fred Flintstone',
          town => 'Bedrock'

parsedate
     Parses an HTTP date in one of three standard forms:

          Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123

          Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036

          Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format

     Example:

          my $secs = Apache::Util::parsedate($date_str);

ht_time
     Format a time string.

     Examples:

          my $str = Apache::Util::ht_time(time);

          my $str = Apache::Util::ht_time(time, "%d %b %Y %T %Z");

          my $str = Apache::Util::ht_time(time, "%d %b %Y %T %Z", 0);

size_string
     Converts the given file size into a formatted string. The size given
     in the string will be in units of bytes, kilobytes, or megabytes,
     depending on the size.

          my $size = Apache::Util::size_string -s $r->finfo;

validate_password
     Validate a plaintext password against a smashed one.  Use either
     crypt() (if available), ap_MD5Encode() or ap_SHA1Encode depending
     upon the format of the smashed input password.

     Returns true if they match, false otherwise.

          if (Apache::Util::validate_password("slipknot", "aXYx4GnaCrDQc")) {
              print "password match\n";
          }
          else {
              print "password mismatch\n";
          }

AUTHOR
======

   Doug MacEachern

SEE ALSO
========

   perl(1).


File: pm.info,  Node: Apache/VMonitor,  Next: Apache/Watchdog/RunAway,  Prev: Apache/Util,  Up: Module List

Visual System and Apache Server Monitor
***************************************

NAME
====

   Apache::VMonitor - Visual System and Apache Server Monitor

SYNOPSIS
========

     # mod_status should be compiled in (it is by default)
     ExtendedStatus On

     # Configuration in httpd.conf
     <Location /sys-monitor>
       SetHandler perl-script
       PerlHandler Apache::VMonitor
     </Location>

     # startup file or <Perl> section:
     use Apache::VMonitor();
     $Apache::VMonitor::Config{BLINKING} = 1;
     $Apache::VMonitor::Config{REFRESH}  = 0;
     $Apache::VMonitor::Config{VERBOSE}  = 0;
     $Apache::VMonitor::Config{SYSTEM}   = 1;
     $Apache::VMonitor::Config{APACHE}   = 1;
     $Apache::VMonitor::Config{PROCS}    = 1;
     $Apache::VMonitor::Config{MOUNT}    = 1;
     $Apache::VMonitor::Config{FS_USAGE} = 1;
     $Apache::VMonitor::Config{SORT_BY}  = 'size';
     
     $Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);

DESCRIPTION
===========

   This module emulates the reporting functionalities of top(), mount(),
df() and ifconfig() utilities. It has a visual alert capabilities and
configurable automatic refresh mode. All the sections can be shown/hidden
dynamically through the web interface.

   The are two main modes:

   * Multi processes mode

     All system processes and information are shown. See the detailed
     description of the sub-modes below.

   * Single process mode

     An indepth information about a single process is shown.

     If the chosen process is an Apache/mod_perl process, the following
     info is displayed:

     Process type (child or parent), status of the process (starting,
     reading, sending waiting and etc), how long the current request is
     processed or last was processed.

     Bytes transferred and requests served perl child and per slot.

     Cpu times used by process: total, utime, stime, cutime, cstime.

     For all processes:

     General process info:

     UID, GID, State, TTY, Command line args

     Memory Usage: Size, Share, VSize, RSS

     Memory Segments Usage: text, shared lib, date and stack.

     Memory Maps: start-end, offset, device_major:device_minor, inode,
     perm, library path.

     Loaded libraries sizes.

   Other available modes within 'Multi processes mode'.

refresh mode
     From within a displayed monitor (by clicking on a desired refresh
     value) or by setting of *$Apache::VMonitor::Config{REFRESH}* to a
     number of seconds between refreshes you can control the refresh rate.
     e.g:

          $Apache::VMonitor::Config{REFRESH} = 60;

     will cause the report to be refreshed every single minute.

     Note that 0 (zero) turns automatic refreshing off.

top(1) emulation (system)
     Just like top() it shows current date/time, machine uptime, average
     load, all the system CPU and memory usage: CPU Load, Mem and Swap
     usage.

     The top() section includes a swap space usage visual alert
     capability. The color of the swap report will be changed:

          1) 5Mb < swap < 10 MB             color: light red
          2) 20% < swap (swapping is bad!)  color: red
          3) 70% < swap (swap almost used!) color: red + blinking

     Note that you can turn off blinking with:

          $Apache::VMonitor::Config{BLINKING} = 0;

     The module doesn't alert when swap is being used just a little (<5Mb),
     since it happens most of the time, even when there is plenty of free
     RAM.

     If you don't want the system section to be displayed set:

          $Apache::VMonitor::Config{SYSTEM} = 0;

     The default is to display this section.

top(1) emulation (Apache/mod_perl processes)
     Then just like in real top() there is a report of the processes, but
     it shows all the relevant information about httpd processes only! The
     report includes the status of the process (starting, reading, sending
     waiting and etc), process' id, time since current request was started,
     last request processing time, size, shared, virtual and resident size.
     It shows the last client's IP and Request (only 64 chars, as this is
     the maximum length stored by underlying Apache core library).

     You can sort the report by any column, see the `CONFIGURATION|' in
     this node section for details.

     At the end there is a calculation of the total memory being used by
     all httpd processes as reported by kernel, plus a result of an attempt
     to approximately calculate the real memory usage when sharing is in
     place. How do I calculate this:

     1. For each process sum up the difference between shared and system
     memory.

     2. Now if we add the share size of the process with maximum shared
     memory, we will get all the memory that actually is being used by all
     httpd processes but the parent process.

     Please note that this might be incorrect for your system, so you use
     this number on your own risk. I have verified this number, by writing
     it down and then killing all the servers. The system memory went down
     by approximately this number. Again, use this number wisely!

     If you don't want the Apache section to be displayed set:

          $Apache::VMonitor::Config{APACHE} = 0;

     The default is to display this section.

top(1) emulation (any processes)
     This section, just like the Apache/mod_perl processes section,
     displays the information in a top(1) fashion. You use a regular
     expression for processes you want to see.

     For each group of matched processes, just like with
     Apache/mod_processes a total size and estimation of the real memory
     taken into account the shared memory, is displayed.

     If you want the Apache section to be displayed a REGEX for processes
     to match. e.g if you want to see http, `mysql' and `squid' processes,
     set:

          $Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);

     and

          $Apache::VMonitor::Config{PROCS} = 1;

     The default is not to display this section.

mount(1) emulation
     This section reports about mounted filesystems, the same way as if you
     have called mount() with no parameters.

     If you want the mount() section to be displayed set:

          $Apache::VMonitor::Config{MOUNT} = 1;

     The default is NOT to display this section.

df(1) emulation
     This section completely reproduces the df() utility. For each mounted
     filesystem it reports the number of total and available blocks (for
     both superuser and user), and usage in percents.

     In addition it reports about available and used filenodes in numbers
     and percents.

     This section has a capability of visual alert which is being triggered
     when either some filesystem becomes more than 90% full or there are
     less 10% of free filenodes left. When that happens the filesystem
     related line will go bold and red and a mounting point will blink if
     the blinking is turned on. You can the blinking off with:

          $Apache::VMonitor::Config{BLINKING} = 0;

     If you don't want the df() section to be displayed set:

          $Apache::VMonitor::Config{FS_USAGE} = 0;

     The default is to display this section.

abbreviations and hints
     The monitor uses many abbreviations, which might be knew for you. If
     you enable the VERBOSE mode with:

          $Apache::VMonitor::Config{VERBOSE} = 1;

     this section will reveal all the full names of the abbreviations at
     the bottom of the report.

     The default is NOT to display this section.

CONFIGURATION
=============

   To enable this module you should modify a configuration in httpd.conf,
if you add the following configuration:

     <Location /sys-monitor>
       SetHandler perl-script
       PerlHandler Apache::VMonitor
     </Location>

   The monitor will be displayed when you request
http://localhost/sys-monitor or alike.

   You can control the behavior of this module by configuring the
following variables in the startup file or inside the *<Perl*> section.

   Module loading:

     use Apache::VMonitor();

   Monitor reporting behavior:

     $Apache::VMonitor::Config{BLINKING} = 1;
     $Apache::VMonitor::Config{REFRESH}  = 0;
     $Apache::VMonitor::Config{VERBOSE}  = 0;

   Control over what sections to display:

     $Apache::VMonitor::Config{SYSTEM}   = 1;
     $Apache::VMonitor::Config{APACHE}   = 1;
     $Apache::VMonitor::Config{PROCS}    = 1;
     $Apache::VMonitor::Config{MOUNT}    = 1;
     $Apache::VMonitor::Config{FS_USAGE} = 1;

   Control the sorting of the mod_perl processes report. You can sort them
by one of the following columns: "pid", "mode", "elapsed", "lastreq",
"served", "size", "share", "vsize", "rss", "client", "request".

     $Apache::VMonitor::Config{SORT_BY}  = 'size';

   A regex to match processes for 'PROCS' section:

     $Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);

   Read the `DESCRIPTION|' in this node section for a complete explanation
of each of these variables.

DYNAMIC RECONFIGURATION
=======================

   `Apache::VMonitor' allows you to dynamically turn on and off all the
sections and enter a verbose mode that explains each section and the used
abbreviations. These dynamic settings stored in the URI and not on the
server side.

PREREQUISITES
=============

   You need to have *Apache::Scoreboard* installed and configured in
httpd.conf, which in turn requires mod_status to be installed. You also
have to enable the extended status, for this module to work properly. In
httpd.conf add:

     ExtendedStatus On

   You also need *Time::HiRes* and *GTop* to be installed.

   And of course you need a running mod_perl enabled apache server.

BUGS
====

TODO
====

   I want to include a report about open file handlers per process to
track file handlers leaking. It's easy to do that by just reading them
from `/proc/$pid/fd' but you cannot do that unless you are root. `libgtop'
doesn't have this capability - if you come up with solution, please let me
know. Thanks!

SEE ALSO
========

   *Note Apache: Apache,, `mod_perl' in this node, *Note
Apache/Scoreboard: Apache/Scoreboard,, *Note GTop: GTop,

AUTHORS
=======

   Stas Bekman <stas@stason.org>

COPYRIGHT
=========

   The Apache::VMonitor module is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.


File: pm.info,  Node: Apache/Watchdog/RunAway,  Next: Apache/WebSNMP,  Prev: Apache/VMonitor,  Up: Module List

a monitor for hanging processes
*******************************

NAME
====

   Apache::Watchdog::RunAway - a monitor for hanging processes

SYNOPSIS
========

     stop_monitor();
     start_monitor();
     start_detached_monitor();

     $Apache::Watchdog::RunAway::TIMEOUT = 0;
     $Apache::Watchdog::RunAway::POLLTIME = 60;
     $Apache::Watchdog::RunAway::DEBUG = 0;
     $Apache::Watchdog::RunAway::LOCK_FILE = "/tmp/safehang.lock";
     $Apache::Watchdog::RunAway::LOG_FILE = "/tmp/safehang.log";
     $Apache::Watchdog::RunAway::SCOREBOARD_URL = "http://localhost/scoreboard";

DESCRIPTION
===========

   A module that monitors hanging Apache/mod_perl processes. You define
the time in seconds after which the process to be counted as hanging. You
also control the polling time between check to check.

   When the process is considered as 'hanging' it will be killed and the
event logged into a log file. The log file is being opened on append, so
you can basically defined the same log file that uses Apache.

   You can start this process from startup.pl or through any other method.
(e.g. a crontab). Once started it runs indefinitely, untill killed.

   You cannot start a new monitoring process before you kill the old one.
The lockfile will prevent you from doing that.

   Generally you should use the `amprapmon' program that bundled with this
module's distribution package, but you can write your own code using the
module as well. See the amprapmon manpage for more info about it.

   Methods:

   * stop_monitor()

     Stop the process based on the PID in the lock file. Remove the lock
     file.

   * start_monitor()

     Starts the monitor in the current process. Create the lock file.

   * start_detached_monitor()

     Starts the monitor in a forked process. (used by `amprapmon'). Create
     the lock file.

WARNING
=======

   This is an alpha version of the module, so use it after a testing on
development machine.

   The most critical parameter is the value of
*$Apache::Watchdog::RunAway::TIMEOUT* (see `CONFIGURATION|' in this node),
since the processes will be killed without waiting for them to quit (since
they hung).

CONFIGURATION
=============

   Install and configure `Apache::Scoreboard' module

     <Location /scoreboard>
        SetHandler perl-script
        PerlHandler Apache::Scoreboard::send
        order deny,allow
     #    deny from all
     #    allow from ...
     </Location>

   Configure the Apache::Watchdog::RunAway parameters:

     $Apache::Watchdog::RunAway::TIMEOUT = 0;

   The time in seconds after which the process is considered hanging. 0
means deactivated. The default is 0 (deactivated).

     $Apache::Watchdog::RunAway::POLLTIME = 60;

   Polling intervals in seconds. The default is 60.

     $Apache::Watchdog::RunAway::DEBUG = 0;

   Debug mode (0 or 1). The default is 0.

     $Apache::Watchdog::RunAway::LOCK_FILE = "/tmp/safehang.lock";

   The process lock file location. The default is */tmp/safehang.lock*

     $Apache::Watchdog::RunAway::LOG_FILE = "/tmp/safehang.log";

   The log file location. Since it flocks the file, you can safely use the
same log file that Apache uses, so you will get the messages about killed
processes in file you've got used to. The default is */tmp/safehang.log*

     $Apache::Watchdog::RunAway::SCOREBOARD_URL = "http://localhost/scoreboard";

   Since the process relies on scoreboard URL configured on any of your
machines (the URL returns a binary image that includes the status of the
server and its children), you must specify it. This enables you to run the
monitor on one machine while the server can run on the other machine. The
default is URI is *http://localhost/scoreboard*.

   Start the monitoring process either with:

     start_detached_monitor()

   that starts the monitor in a forked process or

     start_monitor()

   that starts the monitor in the current process.

   Stop the process with:

   stop_monitor()

   The distribution arrives with `amprapmon' program that provides an rc.d
like or apachectl interface.

   Instead of using a Perl interface you can start it from the command
line:

     amprapmon start

   or from the *startup.pl* file:

     system "amprapmon start";

   or

     system "amprapmon stop";
     system "amprapmon start";

   or

     system "amprapmon restart";

   As mentioned before, once started it sholdn't be killed. So you may
leave only the `system "amprapmon start";' in the *startup.pl*

   You can start the `amprapmon' program from crontab as well.

TUNING
======

   The most important part of configuration is choosing the right timeout
(aka $Apache::Watchdog::RunAway::TIMEOUT) parameter. You should try this
code that hangs and see the process killed after a timeout if the monitor
is running.

     my $r = shift;
     $r->send_http_header('text/plain');
     print "PID = $$\n";
     $r->rflush;
     while(1){
       $r->print("\0");
       $r->rflush;
       $i++;
       sleep 1;
     }

TROUBLESHOOTING
===============

   The module relies on correctly configured `/scoreboard' location URI.
If it cannot fetch the URI, it queitly assumes that server is stopped. So
either check manually that the `/scoreboard' location URI is working or
use the above test script that hangs to make sure it works.

   Enable debug mode for more information.

PREREQUISITES
=============

   You need to have *Apache::Scoreboard* installed and configured in
httpd.conf.

BUGS
====

   Was ist dieses?

SEE ALSO
========

   *Note Apache: Apache,, `mod_perl' in this node, *Note
Apache/Scoreboard: Apache/Scoreboard,

AUTHORS
=======

   Stas Bekman <sbekman@iname.com>

COPYRIGHT
=========

   Apache::Watchdog::RunAway is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.


File: pm.info,  Node: Apache/WebSNMP,  Next: Apache/XPP,  Prev: Apache/Watchdog/RunAway,  Up: Module List

Allows for SNMP calls to be embedded in HTML
********************************************

NAME
====

   Apache::WebSNMP - Allows for SNMP calls to be embedded in HTML

SYNOPSIS
========

     <html>
     <body>
     <snmp>
     	host=zoom.google.org
     	community=public
     	connect
     	interface=ifDescr.2
     	mac=ifPhysAddress.2
     	query
     </snmp>
     The interface <b>descriptor</b> for the ethernet card is <snmp> print(interface) </snmp>
      	and its <b>mac address</b> is <snmp> print(mac) </snmp>
     </body>
     </html>

DESCRIPTION
===========

   The WebSNMP module allows one to embed SNMP commands directly into HTML
code.

REQUIRES
========

   This module requires the perl SNMP module, available at the CPAN site.

USAGE
=====

   The module allows for three different kinds of statements, surrounded
by <snmp> and </snmp> html tags.  The three types of statements consist of
configurations, variable assignments, and commands.  A brief description
of each type of statement follows:

Configuration
=============

   The configuration statements allow the user the set which host to poll
for SNMP information, as well as the SNMP community that the get
statements will draw from.  This essentially takes the form of assigning
values to the reserved variables host and *community*.  All variables are
assigned with the following syntax: 	varible_name=value

   Note: there must not be any intervening whitespace between the '=' and
the name and value.  Thus to set the SNMP host to machine.domain.net, we
would issue the configuration statement:

     <snmp>host=machine.domain.net</snmp>

   If not specified, the default host is localhost, and the default
community is public.

Variable Assignments
====================

   Variables are used as temporary holding locations for information
returned from SNMP calls.  The decision to use variables was made to
obviate the necessity of making a different SNMP get call for each
separate piece of information.  Variable assignments follow the simple
format listed above, where the variable and the value, this time the
symbolic name of a SNMP object identifier, are separated only by an equals
sign (no whitespace).  In this case, the user may also append an optional
extension to the value.  Most OIDs require some form of extension (for
example, the 'system' OIDs usually require an extension of 0, while
interface OIDs require the interface number as an extension).  The
extension is merely appended to the OID value contained in the named
variable.  For example: 	description=ifDescr[.extension] The OIDs
currently implemented are a subset of the IETF Management MIB.  Support is
available for the system, interface, ip, tcp, udp, icmp, and at modules.
A list of the currently supported OIDs, and their symbolic equivalents, is
given below:

     # system
     'sysDescr'	=> "1.3.6.1.2.1.1.1",
     'sysObjectID'	=> "1.3.6.1.2.1.1.2",
     'sysUpTime'	=> "1.3.6.1.2.1.1.3",
     'sysContact'	=> "1.3.6.1.2.1.1.4",
     'sysName'	=> "1.3.6.1.2.1.1.5",
     'sysLocation'	=> "1.3.6.1.2.1.1.6",
     'sysServices'	=> "1.3.6.1.2.1.1.7",
     # interface
     'ifIndex'	=> "1.3.6.1.2.1.2.2.1.1",
     'ifDescr'	=> "1.3.6.1.2.1.2.2.1.2",
             	'ifType'        => "1.3.6.1.2.1.2.2.1.3",
             	'ifMtu'         => "1.3.6.1.2.1.2.2.1.4",
             	'ifSpeed'       => "1.3.6.1.2.1.2.2.1.5",
             	'ifPhysAddress' => "1.3.6.1.2.1.2.2.1.6",
             	'ifAdminStatus' => "1.3.6.1.2.1.2.2.1.7",
             	'ifOperStatus'  => "1.3.6.1.2.1.2.2.1.8",
             	'ifLastChange'  => "1.3.6.1.2.1.2.2.1.9",
             	'ifInOctets'    => "1.3.6.1.2.1.2.2.1.10",
             	'ifInUcastPkts' => "1.3.6.1.2.1.2.2.1.11",
             	'ifInNUcastPkts'=> "1.3.6.1.2.1.2.2.1.12",
             	'ifInDiscards'  => "1.3.6.1.2.1.2.2.1.13",
             	'ifInErrors'    => "1.3.6.1.2.1.2.2.1.14",
             	'ifInUnknownProtos' => "1.3.6.1.2.1.2.2.1.15",
             	'ifOutOctets'   => "1.3.6.1.2.1.2.2.1.16",
             	'ifOutUcastPkts' => "1.3.6.1.2.1.2.2.1.17",
             	'ifOutNUcastPkts' => "1.3.6.1.2.1.2.2.1.18",
             	'ifOutDiscards' => "1.3.6.1.2.1.2.2.1.19",
             	'ifOutErrors'   => "1.3.6.1.2.1.2.2.1.20",
             	'ifOutQLen'     => "1.3.6.1.2.1.2.2.1.21",
             	'ifSpecific'    => "1.3.6.1.2.1.2.2.1.22",
     # ip
     'ipForwarding'	=> "1.3.6.1.2.4.1",
             	'ipDefaultTTL'  => "1.3.6.1.2.4.2",
             	'ipInReceives'  => "1.3.6.1.2.4.3",
             	'ipInHdrErrors' => "1.3.6.1.2.4.4",
             	'ipInAddrErrors' => "1.3.6.1.2.4.5",
             	'ipForwDatagrams' => "1.3.6.1.2.4.6",
             	'ipInUnknownProtos' => "1.3.6.1.2.4.7",
             	'ipInDiscards'  => "1.3.6.1.2.4.8",
             	'ipInDelivers'  => "1.3.6.1.2.4.9",
             	'ipOutRequests' => "1.3.6.1.2.4.10",
             	'ipOutDiscards' => "1.3.6.1.2.4.11",
             	'ipOutNoRoutes' => "1.3.6.1.2.4.12",
             	'ipReasmTimeout' => "1.3.6.1.2.4.13",
             	'ipReasmReqds'  => "1.3.6.1.2.4.14",
             	'ipReasmOKs'    => "1.3.6.1.2.4.15",
             	'ipReasmFails'  => "1.3.6.1.2.4.16",
             	'ipFragOKs'     => "1.3.6.1.2.4.17",
             	'ipFragFails'   => "1.3.6.1.2.4.18",
             	'ipFragCreates' => "1.3.6.1.2.4.19",
             	'ipAdEntAddr'   => "1.3.6.1.2.4.20.1.1",
             	'ipAdEntIfIndex' => "1.3.6.1.2.4.20.1.2",
             	'ipAdEntNetMask' => "1.3.6.1.2.4.20.1.3",
             	'ipAdEntBcastAddr' => "1.3.6.1.2.4.20.1.4",
             	'ipAdEntEntReasmMaxSize' => "1.3.6.1.2.4.20.1.5",
             	'ipRouteDest'   => "1.3.6.1.2.4.21.1.1",
     'ipRouteIfIndex' => "1.3.6.1.2.4.21.1.2",
     'ipRouteMetric1' => "1.3.6.1.2.4.21.1.3",
             	'ipRouteMetric2' => "1.3.6.1.2.4.21.1.4",
     'ipRouteMetric3' => "1.3.6.1.2.4.21.1.5",
             	'ipRouteMetric4' => "1.3.6.1.2.4.21.1.6",
     'ipRouteNextHop' => "1.3.6.1.2.4.21.1.7",
             	'ipRouteType'   => "1.3.6.1.2.4.21.1.8",
     'ipRouteProto'  => "1.3.6.1.2.4.21.1.9",
             	'ipRouteAge'    => "1.3.6.1.2.4.21.1.10",
     'ipRouteMask'   => "1.3.6.1.2.4.21.1.11",
             	'ipRouteMetric5' => "1.3.6.1.2.4.21.1.12",
     'ipRouteInfo'   => "1.3.6.1.2.4.21.1.13",
     'ipNetToMediaIfIndex' => "1.3.6.1.2.1.4.22.1.1",
             	'ipNetToMediaPhysAddress' => "1.3.6.1.2.1.4.22.1.2",
             	'ipNetToMediaNetAddress' => "1.3.6.1.2.1.4.22.1.3",
             	'ipNetToMediaType' => "1.3.6.1.2.1.4.22.1.4",
             	'ipRoutingDiscards' => "1.3.6.1.2.4.23",
     # tcp
     'tcpRtoAlgorithm' => '1.3.6.1.2.1.6.1',
             	'tcpRtoMin' 	=> '1.3.6.1.2.1.6.2',
             	'tcpRtoMax' 	=> '1.3.6.1.2.1.6.3',
             	'tcpMaxConn'	=> '1.3.6.1.2.1.6.4',
             	'tcpActiveOpens' => '1.3.6.1.2.1.6.5',
             	'tcpPassiveOpens' => '1.3.6.1.2.1.6.6',
             	'tcpAttemptFails' => '1.3.6.1.2.1.6.7',
             	'tcpEstabResets' => '1.3.6.1.2.1.6.8',
             	'tcpCurrEstab' 	=> '1.3.6.1.2.1.6.9',
             	'tcpInSegs' 	=> '1.3.6.1.2.1.6.10',
             	'tcpOutSegs' 	=> '1.3.6.1.2.1.6.11',
             	'tcpRetransSets' => '1.3.6.1.2.1.6.12',
             	'tcpConnState' 	=> '1.3.6.1.2.1.6.13.1.1',
             	'tcpConnLocalAddress' => '1.3.6.1.2.1.6.13.1.2',
             	'tcpConnLocalPort' => '1.3.6.1.2.1.6.13.1.3',
             	'tcpConnRemAddress' => '1.3.6.1.2.1.6.13.1.4',
             	'tcpConnRemPort' => '1.3.6.1.2.1.6.13.1.5',
             	'tcpInErrs' 	=> '1.3.6.1.2.1.6.14',
             	'tcpOutRsts' 	=> '1.3.6.1.2.1.6.15',
     # udp
     'udpInDatagrams' => '1.3.6.1.2.1.7.1',
             	'udpNoPorts' 	=> '1.3.6.1.2.1.7.2',
             	'udpInErrors' 	=> '1.3.6.1.2.1.7.3',
             	'udpOutDatagrams' => '1.3.6.1.2.1.7.4',
             	'udpLocalAddress' => '1.3.6.1.2.1.7.5.1.1',
             	'udpLocalPort'  => '1.3.6.1.2.1.7.5.1.2',
     # at
     'atIfIndex'	=> '1.3.6.1.2.1.3.1.1.1',
             	'atPhysAddressIfIndex' => '1.3.6.1.2.1.3.1.1.2',
             	'atNetAddress'  => '1.3.6.1.2.1.3.1.1.3',
     # icmp
     'icmpInMsgs'	=> '1.3.6.1.2.1.5.1',
             	'icmpInErrors' 	=> '1.3.6.1.2.1.5.2',
            	 	'icmpInDestUnreachs' => '1.3.6.1.2.1.5.3',
             	'icmpInTimeExcds' => '1.3.6.1.2.1.5.4',
             	'icmpInParmProbs' => '1.3.6.1.2.1.5.5',
             	'icmpInSrcQuenchs' => '1.3.6.1.2.1.5.6',
             	'icmpInRedirects' => '1.3.6.1.2.1.5.7',
            		'icmpInEchos' 	=> '1.3.6.1.2.1.5.8',
             	'icmpInEchoReps' => '1.3.6.1.2.1.5.9',
             	'icmpInTimestamps' => '1.3.6.1.2.1.5.10',
             	'icmpInTimestampsReps' => '1.3.6.1.2.1.5.11',
             	'icmpInAddrMasks' => '1.3.6.1.2.1.5.12',
             	'icmpInAddrMaskReps' => '1.3.6.1.2.1.5.13',
             	'icmpOutMsgs' 	=> '1.3.6.1.2.1.5.14',
             	'icmpOutErrors' => '1.3.6.1.2.1.5.15',
             	'icmpOutDestUnreachs' => '1.3.6.1.2.1.5.16',
             	'icmpOutTimeExcds' => '1.3.6.1.2.1.5.17',
             	'icmpOutParmProbs' => '1.3.6.1.2.1.5.18',
             	'icmpOutSrcQuenchs' => '1.3.6.1.2.1.5.19',
             	'icmpOutRedirects' => '1.3.6.1.2.1.5.20',
             	'icmpOutEchos' 	=> '1.3.6.1.2.1.5.21',
             	'icmpOutEchoReps' => '1.3.6.1.2.1.5.22',
             	'icmpOutTimestampsReps' => '1.3.6.1.2.1.5.23',
             	'icmpOutTimestampsReps' => '1.3.6.1.2.1.5.24',
             	'icmpOutAddrMasks' => '1.3.6.1.2.1.5.25',
            	 	'icmpOutAddrMaskReps' => '1.3.6.1.2.1.5.26',

   For example, to get the number of outbound and inbound errors on the
'second' ethernet interface, we would assign the ifOutErrors and
ifInErrors OIDs to variables.  Thus:

     <snmp> errorin=ifInErrors.2 errorout=ifOutErrors.2 </snmp>

   Note that more than one command can be nested inside a single set of
<snmp> tags, as long as they are separated by whitespace.

Commands
========

   The following command statements are currently available:

   connect initiates a connection with the SNMP host defined with the host
configuration statement.  This statement can be can be utilized multiple
times in order to connect to several different machines, however any
queries sent will be sent to the current connection.

   query actually initiates the SNMP get for the information you have
requested in your variables, contacting the host defined by the host
configuration command, and storing the data in the proper variable.

   *print(variable_name)* simply prints the information returned to a
variable after a query command.

EXAMPLE
=======

   To put all this together, let us take a simple example:  we wish to
retrieve information concerning the ethernet interface on a host named
'host.domain.net'.  Primarily we are concerned with the administrative
status, mac address, and bytes transferred in and out of the interface.
We would begin with the following block:

     <snmp>
             host=host.domain.net
             community=public
             	connect
     </snmp>

   This block defines the host and the SNMP community, and actually makes
the connection to the host.  This block can be placed anywhere within your
HTML document, as long as it comes before your SNMP queries.  Next, we
must define the information that we wish to obtain:

     <snmp>
     	description=ifDescr.2
     	mac=ifPhysAddress.2
     	inbytes=ifInOctets.2
     	outbytes=ifOutOctets.2
     	query
     </snmp>

   This block instantiates four variables: description, mac, inbytes, and
outbytes, in which the information we wish to obtain will be stored.  The
extension commands tell the program that we are interested in interface 2.
Finally, the query statement performs the SNMP get on the connected host.
All that remains is to print out our data.  Let us put it in tabular
format:

     <table>
     	<tr>
     		<td>
     			Description
     		</td>
     		<td>
     			Mac Address
     		</td>
     		<td>
     			Bytes In
     		</td>
     		<td>
     			Bytes Out
     		</td>
     	</tr>
                     <tr>
                             <td>
                                     print(description)
                             </td>
                             <td>
                                     print(mac)
                             </td>
                             <td>
                                     print(inbytes)
                             </td>
                             <td>
                                     print(outbytes)
                             </td>
                     </tr>
     </table>
     This block merely prints out our information as an HTML table.  Mission accomplished.

AUTHOR
======

   Chris Rigby