
    mmtcpfwd v0.1.0 stable
    Copyright (C) 2001  Matthew Mondor

    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




PLEASE READ ALL SECTIONS CAREFULLY... it is short, but packed of information.



INSTALLATION
------------

To compile and install it, make sure that the CFLAGS env var is set, modify
the Makefile so that $SCRIPTDIR reflects to the proper boot scripts directory,
and do:

cd src
make clean
make

cp mmtcpfwd /usr/sbin/
cp ../mmtcpfwd.sh /etc/init.d/
cp ../mmtcpfwd.conf /etc/       # Do not perform to keep your current config

Note: mmtcpfwd.sh may need modifications depending on system. It is not even
necessary to use it if using BSD-init or simple-init rather than SYSV-init.


This software comes with absolutely no warranty, use at your own risk.




USAGE
-----

This consists of a tcp port forwarder, a fake masq-capable ident server and
an ftp passive proxy. It is a superserver which uses /etc/mmtcpfwd.conf as
it's configuration file and sets-up an independant daemon for each port,
very efficient on SMP multi-CPU systems, and it uses pthreads which is faster
than fork() to multi-thread.

It supports kernel's transparent proxy which permits the ports to be forwarded
from the gateway to the internal LAN box service, pretending to originate from
the IP address of the actual client rather than from the gateway's, so services
actually behave just as if a client directly connected to them. It also
supports verbose syslog logging with connection IDs, in/out bytes that were
transfered, how long connection was sustained, etc.

There are several anti-DoS features imbedded into mmtcpfwd: maximum connection
limits per IP address, maximum total IP addresses that may connect, as well as
an optional threshold of how many exceededed connections may be rejected before
that IP address being DENYed, in which case the DENY command is used to modify
the kernel's firewall chain. It was especially made to run on firewalls to
replace direct IP forwarding and redir ftp proxy utility which has some
race-conditions vulnerablities. It is also possible to tell mmtcpfwd to listen
to specific TCP ports and immediately DENY IP addresses connecting to it,
issuing a custom message. When addresses are DENYed, they will automatically
be undenyed after a specified amount of time, or remain DENYed forever if
wanted (unless the firewall is reset).

 * The /etc/mmtcpfwd.conf configuration file
In the config file, the first non-commented line specifies the command to be
used to DENY an offending IP. Similarily, the second non-comment line specifies
the command to be used to UNDENY a previously denyed IP address using the
command specified on the first line. %s will internally be replaced by the IP
address of the offendant in both cases. The third non-comment line specifies
the message to be issued to a connecting client on an auto-DENY only port
(fake service).  The fourth specifies how long to keep an IP address denied
in minutes (or -1 for no limit). Then follows a section of IP addresses, one
per line, ending by a single ., to never be DENYed. At least 127.0.0.1 should
be included here. The sixth section holds the UID and GID (userid as in
/etc/passwd and groupid as in /etc/group) under which mmtcpfwd should run.
It uses a special internal pipe system to be allowed to execute the IP-DENY
and IP-FREE commands even when not running as root.



There are four main various types of configuration entries that may follow:



1. A fake service to which we should auto-DENY any connecting IP address.
   This consists of four columns (eg):

# Port Resolve Max/IP MaxIPs
138    1       0      32

This instructs mmtcpfwd to open a fake service on port 138, and to resolve
hostnames of IP addresses connecting to it when logging. The Max/IP SHOULD
be 0 in this case, telling mmtcpfwd that all connections should be considered
an offence. The MaxIPs column tells mmtcpfwd that we want to be able to handle
32 simultanious connections at once (from 32 different IP addresses).

All other configuration entries consist of exactly 10 columns.



2. A fake random secure ident server (mmidentd which is now imbedded in
   mmtcpfwd) eg:

# Port Resolve Max/IP MaxIPs MaxRej ToHost ToPort Transp FTP Timeout
113    0       3      32     1      0      0      0      0   10000

This tells mmtcpfwd that we want to run a secure fake ident server which can
be run on MASQ gateways, port has to be 113. In this case we don't want to
resolve the hostname of the clients when logging to be faster, but Resolve can
be set to 1 if wanted. Max/IP specifies the amount of maximum connections to
allow per IP address before MaxRej takes effect. MaxRej specifies the amount of
exceeded allowed connections to reject for an IP address before issuing a DENY
rule on that address (considered DoSsing). ToHost, Transp and FTP must be 0 in
this case. Timeout specifies how much time to wait in milliseconds for the
ident request before closing connection on the client.



3. A normal TCP service which we want to forward either on the same host on
   another port or on another host at some port. This is useful to protect
   http, ssh and other single-TCP-port services or to forward them from the
   gateway/firewall to the internal server box. eg:

# Port Resolve Max/IP MaxIPs MaxRej ToHost      ToPort Transp FTP Timeout
22     1       2      3      0      192.168.1.2 22     1      0   -1
80     0       8      32     3      192.168.1.2 80     1      0   180000

We show two distinct examples here. Port is the port number to listen to on
the local box, Resolve either we want to resolve hostnames or not to the
logfile. Max/IP specifies how much connections to allow at once from a single
IP address before MaxRej be taken into consideration. MaxIPs specifies how much
different IP addresses at once to accept connections from at once. MaxRej still
specifies how many exceeded connections from an IP to be rejected before DENYing
it. ToHost specifies the hostname or IP address of the host to internally
connect to which we forward the service to. Note that using IP addresses here
is faster than using a hostname, however if a hostname is used it could be a
pool of IP addresses. Eg: irc.dal.net, and it would resolve the hostname at
each connection to be forwarded. ToPort is which port to connect to on host
ToHost to forward service to. Transp (0 or 1) specifies either we want the
service host we forward to to see connections incomming from the actual client's
IP address that connected to us (1) or if we want the host to see the
connection as originating from the actual gateway forwarding system. Transproxy
requires linux kernel's "transparent proxy support" option to be compiled in if
1 is to be used here. FTP should be 0. Timeout specifies in milliseconds the
maximum allowed inactivity period in between the service and the client before
closing the connection, or -1 for no limit.



4. A transparent FTP passive proxy. This works much like 3 above, but permits
   to forward passive FTP connections to an internal LAN FTPd, and to
   masquerade the PORT/PASV, LPRT/LPSV and EPRT/EPSV IPs of the internal LAN
   addresses to the gateway's address. It requires transparent proxy support.
   eg:

# Port Resolve Max/IP MaxIPs MaxRej ToHost       ToPort Transp FTP Timeout
21     0       3      32     3      192.168.1.2  21     1      1   -1

All columns work as the same as for 3 above, with the exception of Transp and
FTP which both should be set to 1. This is a great feature added to mmtcpfwd
as of version 0.6, as most kernel-level NAT/PAT support cannot properly handle
FTP passive sessions forwarding, and other user-level software which could do
usually had serious race condition/DoS exploits vulnerabilities. Although this
should work with any ftpd, I highly recommend trying ginseng-ftpd which is a
bsd-ftpd derivate which I modified (added read-only accounts support, maximum
homedir size limits per user, default umask per user, use of a single
configuration file (/etc/ftpusers) even for chroot option, etc).. that is the
ftpd I mostly tested it with.



Logging is performed using syslog, LOG_NOTICE into the AUTH group.
On most configurations this leads to /var/log/auth.log.
By default mmtcpfwd looks for /etc/mmtcpfwd.conf, however the configuration
file can be specified on the command line. It is the only command-line option
that mmtcpfwd supports. mmtcpfwd should be started as root, where it will
itself drop root privileges. It requires root privileges to bind ports below
1024, and to setup the initial shared mmtcpfwd root daemon which permits to
serve DENY requests from other mmtcpfwd daemons through a secure internal
communication pipe, permitting mmtcpfwd forwarders to run as non-root.




SETTING UP
----------

After installation, modify the /etc/mmtcpfwd.conf file to suit your needs.
The script to start/restart it is called mmtcpfwd.sh, place that in your
/etc/init.d/ or /etc/rc.d/init.d/ directory, and add the appropriate symlink
in the proper runlevel to start it, in /etc/rc*.d or /etc/rc.d/rc*.d
directory, (use the runlevel command to know the default one, replace *
with it).

eg:
cd /etc/rc2.d/
ln -s ../init.d/mmtcpfwd.sh S99mmtcpfwd




TRANSPROXY SUPPORT AND REQUIREMENTS
-----------------------------------

The "Transp" column, permits forwarding connections keeping the original
client's IPs addresses when connecting to the actual service. This way, httpd
for instance, on the LAN box, properly places the various clients IP addresses
into it's log file, it does not know that connections to it originate from a
gateway running mmtcpfwd. This only works if connections are coming in from
the outside network (eg: the internet, ouside the firewall), and are connecting on
the firewall port. IP transparent proxying support MUST be compiled into
the kernel for this to work (see kernel's networking options). Useful for NAT
setups. Transproxy support been was in the second beta devel version of
mmtcpfwd (v0.3). (See ChangeLog) The new FTP passive proxying support that
was added in v0.6 requires Transproxy support as well. mmtcpfwd requires
libpthread.




RESTRICTIONS
------------

For security considerations, as well as to keep the name of this product clean,
I strongly suggest compiling from source code after matching the MD5 hash on the
official site (http://mmondor.rubiks.net). It is discouraged to use binary
packages distributed by third parties. This is security related software intended
to run on firewalls, and always has to remain free any backdoor.




CONTACT - BUGREPORTS
--------------------

Bugfixes/comments: mmondor@linuxguru.net
Matthew Mondor

