NAME
IPTables::IPv4::DBTarpit::Tools - to manipulate tarpit databaseSYNOPSIS
use IPTables::IPv4::DBTarpit::Tools qw(
$DBTP_ERROR
inet_aton
inet_ntoa
bdbversion
libversion
db_strerror
);
$tool = new IPTables::IPv4::DBTarpit::Tools (
# defaults shown - one or more db's
dbfile => ['tarpit','... etc'],
dbhome => '/var/run/dbtarpit',
umask => 007,
# optional
txtfile => ['name1','... etc'],
recover => 1,
);
$string = db_strerror($DBTP_ERROR);
$tool = new IPTables::IPv4::DBTarpit::Tools(%hash);
$tool->closedb;
$rv = $tool->get($db,$4byteIPaddress);
($key,$data) = $tool->getrecno($db,$recno);
$rv = $tool->remove($db,$4byteIPaddress);
$rv = $tool->put($db,$4byteIPaddress,$value);
$rv = $tool->touch($db,$4byteIPaddress,$timestamp);
$rv = $tool->sync($db);
$rv = $tool->clear($db);
$rv = $tool->cull($db,$age,\%hash,$nop);
$rv = $tool->dump($db,\%hash);
$number = $tool->nkeys($db)
($string,$major,$minor,$patch)=bdbversion();
($string,$major,$minor,$patch)=libversion()
$netaddr = inet_aton($dotquad);
$dotquad = inet_ntoa($netaddr);DESCRIPTION
IPTables::IPv4::DBTarpit::Tools provides utilities to manage the database for IPtables QUEUE packets delivered to user space routine dbtarpit. Utilities are available to add/update the DB file as well as get, remove, and expire the host ip's in the databases.
$DBTP_ERROR;
The code returned by the last DB operation. A text string representing the code will be returned by:
$string = db_strerror($DBTP_ERROR);
Return a string describing the error condition in $DBTP_ERROR.
$tool = new IPTables::IPv4::DBTarpit::Tools(%hash);
Open a database environment and its databases and return its reference. Returns undef on failure.
%hash = ( # defaults shown - one or more db's dbfile => ['tarpit','... etc'], dbhome => '/var/run/dbtarpit', umask => 007, # optional txtfile => ['name1','... etc'], recover => 1, ); dbhome => '/var/run/dbtarpit',Default if not present. Location of BerkeleyDB sub-system files.
The leading directories must be present and writable.
dbfile => ['tarpit','...etc'],Default is 'tarpit' if not present. However, if 'dbfile' is omitted and 'txtfile' is present, no 'dbfile' will be forced by default. BerkeleyDB file located in dbhome containing keys which are four byte ip address's (as returned by inet_aton() and values which are time in seconds since epoch of the record update.
The combined maximum total number of open dbfiles + txtfiles must be 10 or less.
Multiple db files may be created, each referenced in other methods by the file name specified. The dbname will be the file portion of the path/file database name.
The home directory and database will be created if they do not exist. However, the parent directories for dbhome must already exist and have adequate premissions.
umask => 007,Default if omitted. Files and directories are created with mode 0666 and 0777, respectively, masked with 'umask' of 007 by default.
txtfile => ['name1','name2', etc...]Optional database(s) that take text as the value. The databases specified by dbfile only accept and return unsigned long timestamps.
recover => 1, # any true valueUse this flag if the Berkeley DB returns a DB_RUNRECOVERY error. The database environment is destroyed and recreated. Since the databases for this application are not transactional, the DB_RECOVER flag is not applicable. DBENV->remove is called to remove the corrupt environment. All other threads must be stopped and this thread run by itself. See the Berkeley DB documentation for further details.
See: DATABASE CONFIGURATION FILE below for additional configuration options.
$rv = $tool->closedb();
returns: FALSE unconditional Close the database files$rv = $tool->get($db,$4byteIPaddress);
input: dbname, address, # as returned by inet_aton() For dbfile type db's: returns: action code or time (seconds) of last update or undef if db or key not found or 0 on ERROR (real db error) NOTE: the error will be in $DBTP_ERROR. Use $tool->db_error($DBTP_ERROR) to get a string describing the error. For txtfile type db's: returns: text string($key,$data) = $tool->getrecno($db,$recno);
input: dbname, record number for all types the first element, returns: a key consisting of a 4byteIPaddress for dbaddr types a second element returns: action code or time (seconds) of last update for dbtxt types a second element returns: text string In scalar context, returns only only the key -- 4byteIPaddress returns: an empty array or undef if there is a db error or record is not found for array and scalar context as appropriateNOTE: (in BIG LETTERS!)
Berkeley DB provides a "1" based numbering system for record numbers. i.e. the first record number is "1". Attempting to access record "0" will create and error, you've been warned.
$rv = $tool->remove($db,$4byteIPaddress);
input: dbname, address, # as returned by inet_aton() returns: ZERO (null) on success or undef on key not found or non-zero, see BerkeleyDB documentation Removes database record$rv = $tool->put($db,$4byteIPaddress,$value);
input: dbname, address, # as returned by inet_aton() value returns: ZERO on success or non-zero, see BerkeleyDB documentation Update or insert a record into named database USE caution, do not insert text values into databases specified with B<dbfile>. You will get erroneous results.$rv = $tool->touch($db,$4byteIPaddress,$timestamp);
input: dbname, address, # as returned by inet_aton() $timestamp or current time returns: ZERO on success or non-zero, see BerkeleyDB documentation Updates or creates or updates record with the $timestamp or current epoch time in seconds if $timestamp is not present. (may be used to put arbitrary non-zero values in the database for test purposes -- this will break normal operations)$rv = $tool->sync($db);
Flush the cached pages of the database to file. $tool->sync() should be performed after database update (remove, put, touch) when the operation(s) are complete.
input: db name returns: false on success or Berkeley DB error code$rv = $tool->clear($db);
Clear a database of all records.
input: db name returns: false on success or Berkeley DB error code$rv = $tool->cull($db,$age,\%hash,$nop);
input: dbname, age in seconds from now, hash pointer, no operation = true returns: number of keys removedFills the %hash with 4 byte IP address and time tag for each address older than $age seconds from the current time.
If $nop is false, the %hash represents the addresses deleted from the database. If $nop is true, no action is taken on the database. The %hash is just returned showing what action is proposed.
This operation can consume a lot of memory and is intended primarily for use in testing on smallish databases. Use a tied %hash if you expect large arrays.
$rv = $tool->dump($db,\%hash);
input: dbname, pointer to hash returns: 0 on success or BerkeleyDB error codeReturns the hash filled with the contents of the database.
This operation can consume a lot of memory and is intended primarily for use in testing on smallish databases. Use a tied %hash if you expect large arrays.
$number = $tool->nkeys($db)
Returns the number of unique keys (or records) in a connected database. If there is an error, it return undef and sets the error number in $DBTP_ERROR.
input: database name returns: number of keys or zeroNote: zero is a perfectly good answer. If the error number is also zero, then that's the real answer.
($string,$major,$minor,$patch)=bdbversion();
Returns the version of the installed Berkeley DB.
input: none output: scalar context, a string describing the version or array context, the string as above followed by the major, minor, and patch revision levels($string,$major,$minor,$patch)=libversion();
Returns the version of the bdbtarpit library.
input: none output: scalar context, a string describing the version or array context, the string as above followed by the major, minor, and patch revision levels$netaddr = inet_aton($dotquad);
Provided for convenience. This method is the same as the one in Socket from perl 5.8. Takes a string giving the name of a host, and translates that to the 4-byte string (structure). Takes arguments of both the 'blackhole.spamcannibal.org' type and '86.1.2.4'. If the host name cannot be resolved, returns undef. For multi-homed hosts (hosts with more than one address), the first address found is returned.
$dotquad = inet_ntoa($netaddr);
Provided for convenience. This method is the same as the one in Socket from perl 5.8. Takes a four byte ip address (as returned by inet_aton()) and translates it into a string of the form 'd.d.d.d' where the 'd's are numbers less than 256 (the normal readable four dotted number notation for internet addresses).
DATABASE CONFIGURATION FILE [optional]
Usually used to increase database cache size.
Most of the configuration information that can be specified to DB_ENV methods can also be specified using a configuration file. Any file named DB_CONFIG in the database home directory will be read for lines of the format NAME VALUE.
One or more whitespace characters are used to delimit the two parts of the line, and trailing whitespace characters are discarded. All empty lines or lines whose first character is a whitespace or hash (#) character will be ignored. Each line must specify both the NAME and the VALUE of the pair. The specific NAME VALUE pairs are documented in the Berkeley DB manual for the corresponding methods.
See: http://www.sleepycat.com/docs/ref/env/db_config.html
DEPENDENCIES
noneEXPORT
DB_NOTFOUND
DB_RUNRECOVERYEXPORT_OK
$DBTP_ERROR
inet_aton
inet_ntoa
bdbversion
libversion
db_strerrorACKNOWLEDGEMENTS
inet_aton and inet_ntoa have been included with a few modifications from perl-5.80 by Larry Wall, copyright 1989-2002. Thank you Larry for making PERL possible for all of us.
Much of how to write this module and the bdb functions in the SpamCannibal package I learned from reading the source code of Paul Marquess's BerkeleyDB-0.20. The versioning information for Berkeley DB was all taken directly from Paul's module. Thanks Paul.
COPYRIGHT
Copyright 2003 - 2008, Michael Robinton <michael@bizsystems.com> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
AUTHOR
Michael Robinton <michael@bizsystems.com>
SEE ALSO
perl(1), Socket(3)
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 527:
=cut found outside a pod block. Skipping to next block.