NAME
    bdbaccess -- safe Berkeley DB reader

    distributed as perl module Mail::SpamCannibal::BDBaccess

SYNOPSIS
      bdbaccess [options]...

DESCRIPTION
    There is no perl module for "bdbaccess". This is a documentation shell.

    See the IPTables::IPv4::DBTarpit::Tools manpage to manipulate and
    examine the "bdbaccess" database(s).

    "bdbaccess" is a C daemon that provides access to Berkeley DB files via
    a unix domain socket. "bdbaccess" is configured for concurrent use of
    the database, allowing similtaneous access and update of the database by
    other applications.

    An application can access the data from a database opened by "bdbaccess"
    using one of the following methods:

      Open the domain socket.
      Send a query of the form:

            how, number, name

      where:
            how is a single byte
            = 0 for access by key
            = 1 - 255 for access by record number

      and:
            number is 32 bits
      how = 0, number is a packed network address
      how = 1-255, number is a record number or zero

      and:
            name is the database to access
            TERMINATED with a NULL "\0"

    NOTE: the key, be it a network address or a record number, should be in
    network order. inet_aton produces packed addresses in the correct order,
    however record numbers must be packed correctly and natively are
    dependent on whether your host has a big endian or litte endian
    operating system.

    "bdbaccess" will respond in one of 3 modes depending on the access
    request.

    MODE 1: For requests where how = 0 or 1, The response will be as
    follows:

      key, data

    where key is a 32 bit packed network address and data contains either a
    32 bit integer or a string depending on the database queried.

    If there is a database error, inlcuding the record not being found, the
    key will return INADDR_NONE, which is equivalent to
    inet_aton('255.255.255.255'), and the data will contain the integer
    value of the BerkeleyDB failure code

    MODE 2: For any request where how is 1 or greater, specifiying a record
    number of zero (0) - which does not exist - will result in:

    RETRIEVING DATABASE STATISTICS and VERSION NUMBER

    The first record number in a Berkeley DB is record number ONE (1), there
    is no record ZERO (0). If the bdbaccess daemon is queried by record for
    record ZERO, it will return the version number of the underlying
    database in a form that can be unpacked by inet_ntoa. The returned data
    record will contain the number of keys or unique records currently in
    the database. Both of these will be 32 bit fields.

      version number, number of keys

    MODE 3: For any request where how is 1 or greater and the record number
    specified is one (1) or more, the bdbaccess daemon will return:

      uchar number, key1, key2, ... keyN

    where "uchar number" is an 8 bit field containing the number of keys
    returned, followed by N 32 bit fields containing packed network
    addresses. The first key returned will be from the record number
    specified in the query, followed by number+1, and so on... The daemon
    will return "how" records or what is available if it is less than the
    number requested (zero is a good anwser).

INSTALLATION
    To build the "bdbaccess" daemon, first install IPTables::IPv4::DBTarpit,
    then type the following:

      perl Makefile.PL
      make
      make test
      make install

    To restore the default directory configurations type:

      rm config.db

    Adjust the permissions for "bdbaccess" and its installation directories.
    This is not done automatically since it may involve system directories.

    The Berkeley DB environment and databases can be created automatically.
    However it is recommend that you use the initdb.pl script in the
    ..../Mail/SpamCannibal distribution directory. Adjust the permissions of
    the files and directories so that they are accessible by the various
    applications that will be using the information in the databases.

    Lastly, copy rc.bdbaccess to your startup directory so it is executed at
    boot up as:

      rc.bdbaccess start

    Because the "bdbaccess" daemon has only concurrent access to the
    database, applications should not be written which use db->cursor
    operations these can block dameon access for normal put and sync
    operations. Instead, use repetitive read-by-record-number operations to
    gain sequential access to the data as provided in
    IPTables::IPv4::DBTarpit::Tools.

DEPENDENCIES
      Berkeley DB 2.6.4 or better http://www.sleepycat.com/

      IPTables::IPv4::DBTarpit, version 0.10

OPTIONS - short version
     Options:
      -r    : Alternate DB root directory   [default: /var/run/dbtarpit]

      -f    : Database file name
      -f    : Another db file name (up to 10 total)

      -s    : socket name [default 'bdbread'] (Note 1)
      -p    : port number to listen on (Note 1)
      -i    : use inetd (Note 1)

      -d    : Do NOT detach process.
      -l    : Log activity to syslog (Note 2)
      -o    : Output to stdout instead of syslog (Note 3)
      -V    : Print version information and exit
      -T    : Test mode - Print out debug info and exit
      -h    : Print this help information
      -?    : Print this help information

     Note 1:
      bdbaccess can be configured to listen on EITHER a unix
      domain socket or a port. If listening on a port, it can be
      run as a stand-alone daemon or from inetd. The listening
      modes are mutually exclusive.
     Note 2:
      'kill -USR1 <bdbaccess_PID>' to toggle logging on and off.
      If logging was not enabled at start this sets the '-l' flag
      If logging (-l | -v) are set this saves the value and turns off
      logging. If logging is presently toggled off it restores the 
      saved level (-l | -v)
     Note 3:
      This sends log information to stdout rather than to syslog.
      This option also implies and sets the -d option (Do NOT detach
      process).

OPTIONS - long version
    * -r /path
        Set the database root aka path to db environment home

          (default: /var/run/dbtarpit)

    * -f filename
        Database to open. Up to 10 of names may be specified on the command
        line. There are no defaults, all databases that bdbaccess responds
        for must be specified when the daemon is started.

    * -h
        Print the "short" help information and exit.

    * -?
        Print the "short" help information and exit.

    * -d
        Some people want to run "bdbaccess" under the control of another
        process. This keeps "bdbaccess" from detaching and running as a
        daemon.

    * -l
        Logs any "bdbaccess" activity to syslog.

    * -o
        This gives you the option to have "bdbaccess" log information go to
        stdout instead of the syslog. This option also sets "-d".

    * -V
        Print version information and exit.

    * -T
        This prints a bunch of diagnostic information an exits.

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. If an
    environment home directory has been specified (done by default or with
    the -r option to "bdbaccess") 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

AUTHOR
    Michael Robinton <michael@bizsystems.com>

COPYRIGHT AND LICENCE
      Copyright 2003 - 2014, 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.

SEE ALSO
    the IPTables::IPv4::DBTarpit::Tools manpage the
    Mail::SpamCannibal::BDBclient manpage

