FTwall V2 (P2P firewalling with Linux) Draft MAN PAGE

[ Project home page ]

This document is currently a work in progress. It describes version 2.01 of ftwall reasonably well, but has not yet been updated to match the changes in 2.02. This page will be corrected in due course.

• NAME
• MORE NAMES
• USAGE SUMMARY
• DESCRIPTION
• LIMITATIONS
• OPTION DETAILS
• DNS AUTO-TRAINING
• BLOCKING WinMX
• IPTABLES RULES
• EXTERNAL COMMANDS
• LICENSE
• AUTHOR
• PROJECT HOME PAGE
• SUPPORTING THE PROJECT

NAME

ftwall - Fast Track Firewall. Control of IP traffic from Kazaa and its clones plus WinMX and OpenNAP.

MORE NAMES

``Fast track'' is the networking protocol used by Kazaa, KazaaLite, iMesh and Grokster.

``Ftwall'' is part of the ``p2pwall'' project, which aims to provide similar mechanisms for other peer-to-peer file sharing protocols in future.

``P2pwall'' is short for ``Peer-to-peer traffic firewall''.

Ftwall can also be used to block WinMX and OpenNAP clients, and in this sense the name of the program is a slight historical mis-noma.

USAGE SUMMARY

See the ``OPTION DETAILS'' section for more information on ftwall's options and their meanings.

 ftwall [option(s)]

 -d what       debug and stay in foreground. Show ..
                  A      : All / everything
                  -      : nothing (just stay in foreground)
                  d,a,D  : DNS queries, answers, all
                  t      : timelock
                  h      : F.T. HTTP packet headers
                  p      : F.T. probe events
                  l      : show syslog messages on stdout too
 -n            don't block UDP packets (default: do)
 -a ip         set localhost address (default: 127.0.0.1)
 -b number     set socket buffer size (default: 32k)
 -f filename   set name of storefile (default: none)
 -D filename   set name of the DNS training file (default: none)
 -t number     set seconds of timelock. 0 disables (default: 120)
 -c directory  create/delete files here as clients appear/vanish
 -l|L what     set events to log to syslog|stderr (default: none)
                  u (U) : dropped (accepted) UDP packets
                  t (T) : dropped (accepted) TCP/IP packets
                  c     : identified green-network clients
                  p     : identified public-network peers
                  x     : external command packets
                  m     : add MAC address to log messages

DESCRIPTION

``Ftwall'' is a program for linux firewalls that allows the control of network traffic from ``Fast Track'' peer-to-peer clients like ``Kazaa'' and it's derivatives, WinMX and OpenNAP clients.

It is designed to block network traffic from P-2-P applications running in the ``home'' (or ``green'') network from making access to any peers on the public internet. It is ideal for use in networks where the security paradigm is ``open access'' for outbound connections and ``tightly limited'' access for inbound ones. Ftwall can be used in such a network to prevent outbound P2P access, hence preventing illegal file downloads and uploads.

Anyone familiar with the technical problems assoicated with controlling P2P clients will be aware that a ``home'' client that establishes an ``outbound'' connection is typically immediately available to accept inbound connections through the established TCP/IP socket - even if the gateway firewall blocks all in-bound connections via ``normal'' TCP/IP and UDP mechanisms. This is a kind of limited ``tunnelling''. Ftwall solves this (and other) problems.

``Ftwall'' runs on Linux-based firewalls using kernel 2.4 (tested with 2.4.20) or later and iptables (test with version 1.2.6). This combination of version numbers is the current set employed by RedHat 8.0 - which is the system on which the software has been developed.

ftwall runs well on the ``ipcop'' firewall, version 1.3.0 (GPL). I believe that it will run on Smoothwall 2 (GPL) although I have not tested this. It will NOT run on Smoothwall 1.0 since this is an ``ipchains'' based firewall, not an ``iptables'' one.

Full details of the clients which have been tested with this software can be found on the p2pwall web site.

LIMITATIONS

Ftwall requires Linux kernel version 2.4, equipped with ``iptables'' and the ``QUEUE'' target. The ``ip_string'' match module of iptables is desirable, but not required,

Ftwall works with the ``current'' version of the Fast track, WinMX and OpenNAP network protocols at the time of writing (July 2003). It is possible that it will need to be re-worked if these protocols are changed in future.

Ftwall does not block P2P traffic transmitted via a SOCKS Proxy. For full protection you should configure your firewall to block SOCKS proxy traffic as well. At the time of writing, the p2pwall project does not include a HOWTO on SOCKS Proxy traffic control, but check the web site from time to time since one may appear there soon.

OPTION DETAILS

-b buffer_size

Specifies the size of the netlink socket buffer size used to pass packets from the linux kernel to the ftwall daemon.

The size that can actually be used is limited by the system configuration value ``rmem_max''. This can be changed by writing to the file /proc/sys/net/core/rmem_max. If a ``-b size'' value is given that exceeds this limit, it is silently lowered by the operating system to stay in range.

-c directory

When a new P2P client is identified in the ``Home'' network, ftwall creates an empty file in this directory (if specified). The name of the file is the IP addresss of the client. When ftwall finds that the client is no longer running a known P2P application, the file is deleted. Thus the list of files contained in this directory at any point in time is the list of active P2P clients.

Note that this facility provides a current snapshot of the active P2P clients. For historical log, use ``-lc'' or ``-Lc'' options.

-d what

Turns on the generation of debug output, written to the standard output device/file of the process. With the -d option specified, ftwall does not fork itself into the background, but stays ``attached'' to the parent process.

The ``what'' string indicates the combination of debug messages desired.

 A   "All" possible debug messages are output. This is equivalent
     to "Dthpl".

 -   "Nothing" - no debug messages are output, but ftwall stays
     in the foreground. Thus "-d-" is equivalent to "-s" in
     earlier versions of the software.

 d   The "question" block of DNS reply messages.

 a   The "answer" block(s) of DNS reply messages.

 D   All available DNS packet information.

 t   Information about time locks.

 h   FastTrack HTTP headers are printed (during actual file
     transfers).

 p   Information about FastTrack probe packets.

 l   All syslog messages are also printed to stdout.

-f filename

This specifies a file to which the ftwall program will write the addresses of all remote peers that it identifies. The file can then be re-read into memory when the program is next started so that it can continue to block those addresses even if the clients in the home network have entered ``stealth mode''. This option is useful if you anticipate stopping and starting ftwall while P2P clients are still active.

-D filename

Specifies the name of a file that contains regex(7) DNS name patterns and WSX file path specifications. If ftwall is passed a DNS reply packet that gives IP addresses for domain names that match any of these patterns or files, then those IP addresses are added to the list of blocked peers. Iptables must be used to pass DNS query reply packets to ftwall via the QUEUE target for this mechanism to work. See the section ``DNS AUTO TRAINING'' below for more details.

See regex(7) for details of the syntax of the REGEX patterns, but note that patterns used by ftwall are NOT case sensitive.

-l events

Causes the specified list of events to be logged to the ``syslog'' mechanism. The ``events'' is a string of characters that specifies what to log. The following characters are understood..

 u   Log all dropped UDP packets

 U   Log all accepted UDP packets

 t   Log all dropped TCP/IP packets

 T   Log all accepted TCP/IP packets

 c   Log the identification (and clearing) of P2P clients
     in the green (home) network.

 p   Log the identification of P2P peers in the public
     network.

 x   Log all external commands submitted by track_napigator.pl
     etc.

 m   Include MAC addresses in log messages, where available.

Example:

 ftwall -l pc

-L events

This option is identical to ``-l'', except that the events are logged to the ftwall program's standard error (stderr). Using this option also causes the program to stay in the foreground, as if the ``-s'' option had been specified.

The same event characters are recognised as described for the ``-l'' option (above).

Example:

 ftwall -L uU

-n

Prevents ftwall from blocking the UDP exchanges between the home network fast track clients and peer systems. ftwall continues to block the TCP/IP connections, thus rendering the clients unable to connect, but allows them to collect additional address to try from the peers that respond to the UDP exchange. This means that the clients are not limited to attempting to connect to the 200 peer addresses they last spoke to, but can potentially attempt connections to thousands of systems.

This option is NOT for use in production systems, but was added during the development process in order to test the logic with far larger than normal numbers of peer addresses.

-t seconds

This specifies the ``timelock'' time interval. When ftwall identifies a packet from a P2P client, it starts a time and blocks all subsequent packets from that IP address until the timer expires. FastTrack typically continually attempts connections which keeps this ``timelock'' active until the P2P software is closed down. Using a low value for this time means that ftwall may eroneously re-allow connection while a client is still active. Using a high value is safer but means that ftwall will take longer to detect that the P2P software has ceased operating.

The default value is 120 seconds, which is about right for most installations.

DNS AUTO-TRAINING

Ftwall supports the notion of blocking IP addresses on the basis of DNS name REGEX patterns. This allows us (for example) to block all servers with a domain name that ends with ``winxp.com'' or includes the label ``kazaa''. This cannot be done simply by using domain names as the arguments to iptables.

To use this mechanism, ftwall must be passed all DNS answer packets that are being returned to clients AND DNS servers on the home network. The software inspects these packets and identifies IP addresses that relate to domain names that match any of the configured patterns. These IP addresses are then added to the hash of addresses that are ``blocked'' and all further out-bound TCP/IP connection (syn) packets to those addresses are DROPPED by the software. The DNS answer packets themselves are NOT blocked - but continue on their journey to their intended target. This logic effectively means that DNS exchanges are used to ``train'' the ftwall blocking mechanism.

The list of DNS names to be blocked in this way is specified in a configuration file. Each line in the file is either a regex(7) pattern or the path name of a ``wsx'' file. Comments (lines that start with a ``#'' character) and blank lines are ignored. For details and examples of the syntax of this file, please refer to the ``dns-patterns.conf'' supplied in the ``conf'' directory of the ftwall sources. This file is probably installed under /etc/ftwall/dns-patterns.conf on your system.

The path name of the dns patterns file must be specified to the ftwall program using the option ``-D'', and iptables must be configured to pass DNS answer packets to the QUEUE target. Details of the relevant iptables rules are given in the INSTALL document.

BLOCKING WinMX

In order to block WinMX, the DNS Training mechanism (above) must be configured to block domain names ending with ``.winmx.com''. This effectively blocks the native WinMX protocol which uses hosts with these names as directory servers. The regex(7) pattern to use for this is..

  \.winmx\.com$

WinMX is also capable of using the OpenNAP protocol. Files with an extension ``.wsx'' are needed to configure the networks and servers to be accessed. To block this protocol, the DNS training logic must be given a list of all the possible OpenNAP network servers that can be used by providing it with one or more valid ``wsx'' files. These files can be obtained from a number of sources..

1. A number of samples are included with this software in the directory conf/wsx, and are installed in /etc/conf/wsx by default.

2. Use the WinMX software itself to download as may .WSX files as it can find.

3. Use the ``NapMX'' software to generate the files from the Napigator web site.

4. By running the ``get-napigator-wsx.pl'' script to extract the servers listed on the page http://www.napigator.com/servers/. The command can be run as follows...

    perl get-napigator-wsx.pl > \
        /etc/ftwall/wsx/from-napigator.wsx

   Dont forget to configure your iptables rules to pass DNS answer packets to ftwall via the QUEUE target (see the INSTALL file for details).

IPTABLES RULES

The ``INSTALL'' document describes the iptables rules that you should configure in order to pass the relevant packets to ftwall for processing. ``Ftwall'' is very tightly tied to the correct iptables rules being used to pass it the traffic it requires. Errors in iptables rules building will cause it's logic to fail.

EXTERNAL COMMANDS

block peer-ip[:port [client-ip]]

unblock peer-ip[:port [client-ip]]

dump-blocks

Writes a list of the ``blockages'' currently held in the ftwall hash to the file /tmp/ftwall-blocks.dump``.

ban-dns-name name

Adds the specified name to the list of DNS host names that ftwall will ban. The name is NOT a regex pattern but an actual fully qualified domain name.

dump-dns-names

Writes a list of the currently banned DNS names help in ftwall's hash to the file /tmp/ftwall-dns-names.dump.

accept-all flag

If the flag is 1, ftwall stops blocking ANY traffic and starts to accept everything passed to it. This should be considered an unsupported action since it cannot be reliably reversed - if there are P2P clients active at the time it is set to 1 then they may continue to be allowed access to their peers even after it is set back to 0. The peers will only be properly blocked again once they are closed and restarted.

LICENSE

``Ftwall'' is released under the terms of the ``GNU GENERAL PUBLIC LICENSE'' Version 2, June 1991. It comes with all the freedoms and disclaimers normally associated with that license.

    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., 675 Mass Ave, Cambridge, MA 02139, USA.

The ``lhash'' library is part of the ``OpenSSL'' project and is licensed as described in lhash/LICENSE.

    This product includes software developed by the OpenSSL Project
    for use in the OpenSSL Toolkit (http://www.openssl.org/)

    This product includes software written by Eric Young
    (eay@cryptsoft.com).  This product includes software written by Tim
    Hudson (tjh@cryptsoft.com).

AUTHOR

Chris Lowth <chris@lowth.com>

Please don't mail the author directly about this software, unless it is to discuss project funding, direct involvement or alternative license terms. If you wish to discuss the use of this tool, or problems associated with it, please make use of the ``help'' forum, accessed via the project web site (see below).

PROJECT HOME PAGE

Ftwall is part of the ``p2pwall'' project, the home page of which can be found at http://p2pwall.sourceforge.net.

The project includes some public discussion and support forums and an announcements mailing list. The latter is a ``low traffic'' list that is focused on announcing new releases or patches to the software, and will typically deliver no more than a couple of messages a month.

SUPPORTING THE PROJECT

If you find this software useful, please consider supporting the project in one of these ways ..

- Making a donation (how ever small) via PayPal

- Shopping at Amazon.com or Amazon.co.uk using the links on Lowth.com.

- Buying the author something on his Amazon.co.uk ``wish list''.

- Sponsoring the development of a new feature or tool.

Details of how you can help in any of these ways can be found at

      http://www.lowth.com/donate.php