-----------------------------------------------------------------------------
pftabled @PACKAGE_VERSION@
-----------------------------------------------------------------------------

The pftabled daemon is a small helper to make your pf tables reachable
from other hosts. You can add/delete/flush IP addresses to/from a remote
table with a single UDP datagram. Sample client programs in C, Perl, PHP
and Python are included.

SECURITY: The daemon runs chrooted and drops privileges to a user named
pftabled (or nobody if it doesn't exist). Even with SHA1 authentication
I still recommend to secure the receiving port by adequate pf rules, e.g.

  block in proto udp from any to ($if_int) port 56789
  pass in on $if_int proto udp from $authorized to ($if_int) port 56789

-----------------------------------------------------------------------------
Upgrading
-----------------------------------------------------------------------------

If you're upgrading from version 1.05 you only need to upgrade the server,
it accepts old format messages also. The option format of the included
C client has changed (see pftabled-client -h).

If you're upgrading from a version older than 1.04 you have to upgrade
client and server.

-----------------------------------------------------------------------------
Installation
-----------------------------------------------------------------------------

Just run:

  $ ./configure
  $ make

Installing binaries and manpage to /usr/local:

  # make install
or
  # make client-install
  # make server-install

The pftabled daemon is built on pf(4) enabled platforms only (by checking
for the net/pfvar.h include file). The client is always built.

Now generate an authentication key:

  # dd if=/dev/random of=/etc/pftabled.key bs=20 count=1
  # chmod 0400 /etc/pftabled.key

Copy this key to your hosts via a secure channel (ssh, floppy disk) and
make sure it can only be read by the programs.

-----------------------------------------------------------------------------
Usage examples
-----------------------------------------------------------------------------

1. Spam blocking

On your firewall you are redirecting certain IPs to spamd:

  table <spammer> persist
  pass in on egress proto tcp from <spammer> to any port 25 \
      rdr-to 127.0.0.1 port spamd

Now you're able to fill this table from your mailservers, e.g. with qmail

  $ cat .qmail-spamtrap
  |pftabled-client 10.1.1.1 1234 add spammer $TCPREMOTEIP /etc/pftabled.key


2. Portsentry response

You're running portsentry (or some other honeypot tool) on your hosts.
Add these lines to your portsentry.conf

  KILL_RUN_CMD_FIRST = "0"
  KILL_RUN_CMD="pftabled-client 10.1.1.1 1234 add blocked $TARGET$ /etc/key"

to add attackers to a blocklist on your firewall

  table <blocked> persist
  block in on $ext from <blocked> to any

-----------------------------------------------------------------------------
Internals
-----------------------------------------------------------------------------

Datagram format (64 bytes):

	+---------+---------+---------+---------+
	| Version | Command | Reserved| Netmask |
	+---------+---------+---------+---------+
	|              IPv4 address             |
	+---------+---------+---------+---------+
	|                                       |
	:         Table name (32 bytes)         :
	|                                       |
	+---------+---------+---------+---------+
	|               Timestamp               |
	+---------+---------+---------+---------+
	|                                       |
	:    Signature (20 bytes, HMAC-SHA1)    :
	|                                       |
	+---------+---------+---------+---------+

Version:
	0x01	pftabled 1.05 and earlier
	0x02	pftabled 1.06 and later

Command:
	0x01	Add address to table.
	0x02	Delete address from table.
	0x03	Flush table.

Timestamp:
	The server compares incoming timestamps with it's local clock. If
	the difference (= clock difference + network delay) is greater than
	60 seconds, the packet gets dropped (see pftabled.h if you really
	need to change this value).

-----------------------------------------------------------------------------
History
-----------------------------------------------------------------------------

2010-11-12 Version 1.09
           Add sample PHP client. Use mandoc manual formatter if available.

2010-04-20 Version 1.08
           Add sample python client. Check not only for replay attacks but
           for clock deviations to both sides (patch by Melissa Jenkins).

2009-02-04 Version 1.07
           Add sample perl client.

2006-03-06 Version 1.06
           Add mask field to enable addition/deletion of whole networks (idea
           and initial patch from Niki Denev). Changed pftabled-client option
           parsing.

2005-01-27 Version 1.05
           Make authentication completely optional. Portability fixes for
           servers running on FreeBSD (prompted by Nick Buraglio).

2004-09-12 Version 1.04
           SHA1 authentication and client selectable tables (idea from
           Russell Fulton) which necessitates a new wire format.

2004-05-01 Version 1.03
           Bugfix: Missing initializer for timeout queue.

2004-04-24 Version 1.02
           New timeout option to automatically remove table entries after a
           fixed time (idea from Samuel Ljungkvist).

2003-10-29 Version 1.01
           Initial release.

-----------------------------------------------------------------------------
Homepage
-----------------------------------------------------------------------------

You can always find the latest version of pftabled at:

  http://www.wolfermann.org/pftabled.html

-----------------------------------------------------------------------------