View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Michael Robinton > IPTables-IPv4-DBTarpit-0.44 > dbtarpit


Annotate this POD


Open  1
View/Report Bugs


dbtarpit - extension for Linux iptables

distributed as perl module IPTables::IPv4::DBTarpit


  dbtarpit [options]...


There is no perl module for dbtarpit. This is a documentation shell.

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

dbtarpit is a C daemon that uses libipq (the Linux iptables userspace packet queuing library) to examine packets that match a filter criteria and tarpit those connections whose IP addresses are found in its database.

Currently it is only supported on Linux with iptables, however the database library and Tools will build and install on any os that supports Perl.

The dbtarpit database is implemented using the Berkeley DB database found in all Linux distributions. dbtarpit is configured for concurrent use of the database, allowing similtaneous access and update of the database by other applications.

dbtarpit checks the packet IP address against its tarpit database for a match. If a match is found the tarpit database is updated with the most recent connection attempt time, the packet is dropped, and the connection tarpitted. Optionally, packet IP addresses that are not found in the tarpit database are logged in the archive database with the most recent connect time for later examination by other applications.

When used to defend against denial of service attacks, the tarpit is highly effective because it eliminates the traffic from the attacking site by stopping the transmission of data packets at the remote IP stack.

To defend against denial of service attacks for protocols other than TCP/IP, DBTarpit can optionally be configured to drop packets for any connection found in the tarpit database. See the -X switch description below.


To build the dbtarpit daemon and tools, type the following:

  perl Makefile.PL
  make test
  make install

On some platforms it appears that ldconfig fails to link the new library. To do so manually, type:

  ldconfig -n /usr/local/lib

To restore the default directory configurations type:

  rm config.db

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

In the iptables configuration file, place the filter for dbtarpit as the first entry in the INPUT chain. do not insert other entries ahead of this rule.

  IPTABLES = "/usr/local/spamcannibal/bin/iptables"
  ANYWHERE = "0/0"

  $IPTABLES -A INPUT -p tcp -s $ANYWHERE --dport 10025 -j QUEUE

This rule will send tcp packets destined for port 10025 from anywhere to the dbtarpit daemon. If the IP address of the packet is not found in the database, the packet is returned to the chain untouched. If the IP address is found in the database, the packet is dropped and the connection tarpitted.

If the traffic that you wish to inspect and tarpit always comes in on a specific interface, you can modify the rule so that only packets from that interface are inspected.

  INET_IFACE="eth0"     # or your internet interface

  $IPTABLES -A INPUT -p tcp -i $INET_IFACE --dport 10025 -j QUEUE

If the target host is not the host that will process the connection, i.e. you are using NAT on a dual-homed bastion host, then the following rules would apply.

  TARGET = ""
  LAN_IFACE = "eth1"

  $IPTABLES -t nat -p tcp --dport 10025 -j DNAT --to $TARGET

If the incoming IP address is virtual (i.e. eth0:n) then simply add the virtual IP address -d $VIRTUAL_DEST_IP to the above rule.

        and in the FORWARD chain
        --dport 10025 -d $TARGET -j QUEUE
        --dport 10025 -d $TARGET -j ACCEPT

WARNING: if the dbtarpit daemon is not running, packets destined for port 10025 (or whatever you select) are silently dropped by IPTABLES.

The Berkeley DB environment and database file will be created automatically, however you may wish to use IPTables::IPv4::DBTables::Tools. Adjust the permissions of these files so that they are accessible by the various applications that will be using the information in the databases. Pay particular attention to the permissions on the files. Because the tarpit daemon has only concurrent access to the database, applications should not write applications 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.

Lastly, copy rc.dbtarpit to your startup directory so it is executed immediately following rc.iptables at boot up as:

  rc.dbtarpit start

Read the rc.dbtarpit documentation, first by typing:

  perdoc -U ./rc.dbtarpit

and then by looking at the comments at the beginning of the file.

See IPTables::IPv4::DBTarpit::SiteConfig to find out how to pass the DBTarpit configuration information directly to your perl scripts.


  libdbtarpit 0.0.0 (included with this distribution)

  Berkeley DB 2.6.4 or better

  LIBNET 1.0 or better

  Linux kernel with iptables (libipq)

  Network packet filtering (replaces ipchains) 
        (CONFIG_NETFILTER) [Y/n/?] y

It is recommended that you not use connection tracking since each tarpitted connection will consume resources. If the tarpit is run on a linux box used as a firewall, then this is unavoidable.

  connection tracking (required for masq/NAT) 
        (CONFIG_IP_NF_CONNTRACK) [Y/m/n/?] n

  Userspace queueing via NETLINK (EXPERIMENTAL)
        (CONFIG_IP_NF_QUEUE) [Y/m/n/?] y or m


COMMENT: Our firewall runs with... connection tracking (required for masq/NAT) (CONFIG_IP_NF_CONNTRACK) [Y/m/n/?] Y

I've seen as many as several thousand threads in the tarpit with affecting performance on an aging 486 with not much memory. This doesn't seem to be a big deal, but I've seen it mentioned by those with better insight into potential problems than me.

OPTIONS - short version ^

   -a           : Allow all connections
   -b           : Log bandwidth usage to syslog
   -d           : Do NOT detach process.
   -D           : Print packet debug info (like tcpdump) in/out
   -k           : Do not respond to SYN/ACKs (Note 1)
   -l           : Log activity to syslog (Note 2)
   -o           : Output to stdout instead of syslog (Note 3)
   -O           : Same as -o w/time output in seconds since epoch
   -p maxrate   : "Persist" state capture connect attempts (Note 4)
   -P           : Persist mode capture only.
   -R           : Soft restart - Wait while recapturing active connects
   -t datasize  : Set connection throttling size in bytes (default 10)
   -T           : Test mode - Prints out debug info but DOES NOT RUN
   -u fifoname  : Log to fifo (Note 5)
   -v           : Verbosely log activity to syslog (Note 2)
   -V           : Print version information and exit
   -x           : Disable IP capture, just drop connection
   -X           : Drop non-TCP/IP connections found in database
   -L           : tarpit Localhost addresses 127.x.x.x (normally disabled)
   -r /path     : Alternate DB root directory (default "/var/run/dbtarpit)
   -f filename  : Alternate primary DB file name (default "tarpit")
   -s filename  : Optional "connected IP's" database name
   -h           : Print this help information
   -?           : Print this help information

 Note 1:
  By default, dbtarpit responds to an inbound SYN/ACK with an RST
  The -k option eliminates this behavior.
 Note 2:
  'kill -USR1 <dbtarpit_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). 
  Silently ignored if '-u' is already present.
 Note 4:
  dbtarpit will permanently capture connect attempts within the limit of the
  maximum data rate specified (in bytes/sec).
 Note 5:
  Logs tarpit activity to a fifo in the DB root directory. This option 
  clears the '-o','-O', and '-d' flags. You still must use the (-l | -v)
  to set the log level. If you wish to use the '-d' flag, it must be 
  explicitly set after the '-u' option is invoked on the command line.
  '-u' logging uses the same format as the '-O' flag. 

OPTIONS - long version ^


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 dbtarpit) 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.



dbtarpit and IPTables::IPv4::DBTarpit::Tools use the Berkeley DB database. The database is of type BTREE, opened for concurrent access and sequential record access. Both of the database files have identical format.

  Files: tarpit, archive

  Key:  32 bit packed network address as produced by inet_aton
  Data: 32 bit unsigned integer, number of seconds since 1-1-70

  Database creation hints for 'C' api:

  * environment flags   *
    u_int32_t eflags = DB_CREATE | DB_INIT_CDB | DB_INIT_MPOOL;
  * db flags *
    u_int32_t dflags = DB_CREATE;
    u_int32_t info = DB_RECNUM;
    DBTYPE type = DB_BTREE;
    int mode = 0664;

environment and database open statements vary depending on the version of BerkeleyDB used. See the code in bdb.c for specifics.

  Database creation hints for Perl api:

    my %env = (
        -Home   => $self->{dbhome},
        -Flags  => DB_CREATE | DB_INIT_CDB | DB_INIT_MPOOL,

    $self->{"_db_${db}"}  = new BerkeleyDB::Btree
          -Filename     => $self->{dbfilename},
          -Flags        => DB_CREATE,
          -Property     => DB_RECNUM,
          -Env          => $self->{env}
          or die "Cannot open database $db: $! $BerkeleyDB::Error\n" ;


Berkeley DB provides a "1" based numbering system for record numbers. i.e. the first record number is "1". By contrast, perl-BerkeleyDB is a "0" based numbering system with the first record number in the same database designated as "0". This means that a database read and written with the 'C' api will have its record numbers begin with "1" while the same database accessed with perl-BerkeleyDB will have record numbers starting with "0".


There are three other modules that come with this bundle. Briefly their purpose is as follows:

For detailed information, please read the man pages for these modules.


... aahhh! now you come to the fun part.

See Mail::SpamCannibal

Used with dbtarpit, it "eats" the spammer for lunch. In less graphic terms, SpamCannibal is a set of tools that helps you identify the originating mail server for the spam message and add the offender's IP address to the tarpit. There are "trolling" tools to allow you to check the DNSBL databases for hits against dbtarpit's archive database and a host of other goodies to help make life difficult for spammers.

I'm sure you can think of many other applications, but this one is on the top of my list.


There are many contributors to this project. Major code snippets came from the work of:

        ipt_TARPIT.c    by Aaron Hopkins <>

        LaBrea          by Tom Liston <>

  and... and interesting email from Cody Hatch <>
        about using a tarpit to trap spammers.


Michael Robinton <>


  Copyright 2003 - 2014, Michael Robinton <>
  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
  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.


IPTables::IPv4::DBTarpit::Tools, IPTables::IPv4::DBTarpit::Inst, IPTables::IPv4::DBTarpit::SiteConfig, libdbtarpit, dbtarpit and for manual db administration, the utility

syntax highlighting: