Installing ftwall
-----------------

By:   Chris Lowth <chris@lowth.com>
Date: 25 July 2003


The home site for this software is: http://www.lowth.com/p2pwall.

Documentation, FAQs and support forums can all be accessed by this web
site.

========================================================================
STEP 1 - OBTAINING THE FTWALL SOURCE CODE
========================================================================

Get the latest ftwall source file tarball from..

	http://www.lowth.com/p2pwall/ftwall

and download to your hard drive, then uncompress and "un-tar" ..

	gunzip ftwall-X.XX.tar.gz
	tar xvf ftall-X.XX.tar
	cd ftwall-X.XX

(replace X.XX with the ftwall version number)

========================================================================
STEP 2 - OBTAINING OR BUILDING "LIBIPQ"
========================================================================

"ftwall" uses the "libipq" library from iptables. It needs the files
"libipq.a" and "libipq.h". If there is an iptables-devel package for
your linux distribution, then it is likely that this is where the
required files can be found - so install it before trying to compile the
ftwall program. If your system already has these files installed, you
can skip this step.

The RedHat distributions (and, possibly others) dont include this peice
of the iptables software, so you will need to build it for yourself.
It's quite easy to do. Here is what needs to be done.

1. Obtain the iptables sources that match the version installed on your
   system. These can be downloaded from..

       ftp://ftp.netfilter.org/pub/iptables

   You will need the file iptables-VERSION.tar.bz2 (where "VERSION" is
   the version of iptables installed on your firewall).

2. Copy the downloaded file into the ftwall sources directory and
   "unzip" and "untar" (please note: for the build process to work, the
   iptables source directory MUST be placed under the ftwall source
   directory - this location is NOT optional).

       bunzip2 iptables-VERSION.tar.bz2
       tar xf iptables-VERSION.tar

3. "cd" into the iptables sources directory and build the software.

       cd iptables-VERSION/libipq
       make
       cd ../..

That's it - now you can compile the ftwall software. The libipq library
does NOT need to be installed for the ftwall compilation to work - the
ftwall "make file" will find the files provided that they are located
under the ftwall source tree.


========================================================================
STEP 3 - BUILDING FTWALL
========================================================================

This is just a matter of running "make" in the ftwall source directory.


========================================================================
STEP 4 - INSTALLING FTWALL
========================================================================

If you are installing on a RedHat 7.x, 8 or 9 system, installation is
done by running the command..

	make redhat_install

For recent Mandrake systems, run..

	make mandrake_install


On other systems, the following manual procedure can be used ...


1. Copy the "ftwall" program to a directory of your choise. /usr/sbin
   seems like a good option for this. Use the "-a" option of the "cp"
   command to ensure that the ownership and modes are carried over
   during the copy process.

	cp -a ftwall /usr/sbin/ftwall

2. If your system uses the RedHat daemon startup logic of placing files
   in the directory /etc/init.d then copy the "ftwall.redhat.init" file
   to /etc/init.d/ftwall and edit it to change the configuration options.

	cp -a ftwall.redhat.init /etc/init.d/ftwall
	chkconfig --add ftwall
	vi /etc/init.d/ftwall

   Note: on some recent distributions, the /etc/init.d directory is
   "sym-linked" to /etc/rc.d/init.d.

   If your system does not use this mechanism, then visit the p2pwall
   web site or "contributions" forum to see whether anyone has
   contributed instructions or code suitable for your system. If not -
   then cut your own and send news of your progress to the forum.

   The "contributions" forum can be found at..

       https://sourceforge.net/forum/forum.php?forum_id=294611


========================================================================
STEP 5 - CONFIGURING IPTABLES
========================================================================

*******************************************************************
*                                                                 *
*   WARNING #1 - PUT THE "QUEUE" RULES AT THE END OF THE CHAINS   *
*                                             ===                 *
*                                                                 *
*******************************************************************

The "QUEUE" target for iptables is a "terminating" target - in other
words; any packets passed to it STOP traversing the rules, but are
either accepted (in which case they are transmitted) or dropped (in
which case they vanish completely) and are not processed by further
rules in the chain. For this reason, you should probably place the rules
at the END of the chains.

*******************************************************************
*                                                                 *
*     WARNING #2 - ALLOW UDP PACKETS TO GET THROUGH TO FTWALL     *
*                                                                 *
*******************************************************************

Ftwall makes use of the contents of UDP packets to identify the
fast-track clients and peers. If these packets dont get through to the
software then it cannot identify the connections unless you have the
"string match" logic in place and the client attempts a download. Please
ensure that UDP packets can flow through your network and other FORWARD
chain rules - but DONT ignore warning #1. If ftwall is not blocking
fast-track traffic, try running it with logging of UDP packets turned
on, and make sure that it is dropping UDP packets withn a few seconds of
a fast-track client being started.

If you want to be more specific about the UDP packets you allow through,
then you can use the fact that the actual packets needed by ftwall are
contain the string "KaZaA". You can use the "string" match to set up
the relevant filters.


-- NB: ftwall's filter is focussed on "outbound" traffic --

These notes and the ftwall software add the feature of preventing Fast
Track clients in the HOME network from establishing links to peers on
the PUBLIC internet ("outbound" connections). It is assumed that you
already have iptables rules in place to prevent TCP/IP connections FROM
the public internet TO workstations on the HOME network ("inbound"
connections).


-- A note about port 1214 --

You may be tempted to set up rules that block port 1214. This might seem
to make sense if you know that this is the port that old Fast Track
clients used to use. The new versions make use of (almost) any port that
they can "break through" on. Since the ftwall logic works best when it
gathers most information about addresses that refer to Fast Track peers,
it is actually beneficial to allow the port 1214 packets to be queued to
ftwall rather than being blocked directly by iptables. If you have "port
1214 block" rules in place - please remove them when deploying ftwall.
If you wish to leave explicit rules to block port 1214 traffic from the
public internet (inbound connections), then you may do so - this has no
impact on ftwall.


-- Rule for queuing Forwarded UDP packets --

All UDP packets forwarded FROM hosts in the "Home" network TO the public
internet must be passed to the ftwall program using the iptables "QUEUE"
target. The following rule is one way that this can be done, assuming
that the firewall interface connected to the home network is "eth0" and
the home network is 192.168.0.0/24.

   iptables -A FORWARD -p udp -i eth0 -s 192.168.0.0/24 -j QUEUE

It is *very* important that only OUTBOUND udp packets are passed to the
queue. On no account should any of the UDP packets coming from the
public internet back into the home network be passed to the QUEUE - if
they are, the ftwall logic will break down and the software will block
the wrong traffic.

If there are multiple "workstation" subnets in the home network, then
you need to ensure that they are all covered by the rule(s).

If you have servers or other systems that can be guaranteed NOT to run
Fast track software, then it would be an advantage to use IPtables rules
to prevent traffic from those systems passing through ftwall. This
boosts performance and reduces the risk of false possitive
classifications.


-- Rule for queuing Forwarded TCP/IP SYN packets --

All TCP/IP SYN packets forwarded FROM hosts in the "Home" network TO
hosts on the public internet must also be passed to ftwall via the
"QUEUE" target. Assuming that the interface on the home network is
"eth0", and the home subnet is 192.168.0.0/24, then the following
command achieves this end..

   iptables -A FORWARD -p tcp -i eth0 -s 192.168.0.0/24 --syn -j QUEUE

The same warnings given for the forwarded UDP packets (above) apply to
TCP/IP SYNs. You must ensure that ONLY and ALL the relevant packets are
passed. Further, you must ensure that they are passed to the queue from
EXACTLY the same set of hosts as the UDP packets. The logic will not
work if there is a mismatch between these two rules.


-- Rule for queuing responces to UDP probe packets --

The ftwall program periodically sends UDP packets to identified Fast
track clients, and these are returned via the iptables INPUT chain.
Assuming that the interface connected to the home network is "eth0", and
the home subnet is 192.168.0.0/24 then the following rule can be used..

   iptables -A INPUT -p udp -i eth0 -s 192.168.0.0/24 -j QUEUE

The same warnings given for the forwarded UDP and TCP/IP SYN packets
(above) applies to these "INPUT" UDP packets. You must ensure that ONLY
and ALL the relevant packets are passed. Further, you must ensure that
they are passed to the queue from EXACTLY the same set of home network
hosts as the UDP and TCP/IP SYN packets. The logic will not work if
there is a mismatch between these two rules.


-- Rule for TCP/IP data packet match --

If you wish to configure the safety net of filtering file transfers on
the basis of the contents of HTTP-like headers employed (see the
documentation on the web site for information on why you may wish to do
this), then you need to pass data packets into ftwall as well. Since
passing ALL data packets is likely to have a negative impact on the
performance of your firewall, you may wish to pre-filter the packets
using the the experimental "string" module of iptables.

It is likely that your kernel does NOT include this module, and so you
will need to add it. This requires a kernel re-build.

The process for adding this logic is described at..
  http://www.lowth.com/p2pwall/ftwall/docs/adding_string_match.php

Once the module is in place, the following rule is required to pass the
relevant packets to ftwall (adjust the interface and subnet
specifications to match your system/network)..

   iptables -A FORWARD -p tcp -i eth0 -s 192.168.0.0/24 \
	-m string --string X-Kazaa -j QUEUE

If you dont wish to install the module (and rebuild the kernel), but
wish to filter data packets anyway and are happy to live with the
performance hit, then you can simply remove the "--syn" flag from the
TCP/IP SYN packet rule (above). This will cause ALL TCP/IP packets to be
queued.


On systems that use the /etc/sysconfig/iptables file to hold iptables
configuration, the easiest way to configure these rules is to type the
iptables commands in by hand (as root) and then run..

   service iptables save
