#
# README
#
# portfwd - Port Forwarding Daemon
#
# $Id: README,v 1.11 2001/01/08 12:29:05 everton Exp $
#

LICENSE

        Portfwd - Port Forwarding Daemon

        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

INTRODUCTION

        Portfwd stands for port forwarding daemon. It's a small C++
        utility which forwards incoming TCP connections and/or UDP
        packets to remote hosts.

        My apologies for my poor English. Corrections are welcome.

BUILDING

        This program has been compiled with Egcs 1.1.2 and tested
	under Linux 2.2.5, but it may work on other plataforms as
	well. Ports would be appreciated. Specially, if you can build
	this software on *BSD, please send a patch to my e-mail
	address given at the end of this document.

	In order to compile, enter the 'src' directory:

		cd src

        Then type:

        	make

	A file named 'portfwd' should be produced.

INSTALL

        Copy the 'portfwd' file to a suitable location
        (e.g. /usr/local/sbin).

CONFIG

        The grammar for the configuration file is described in the
	'conf.txt' file. Examples can be found in the 'cfg' directory.

        For a quick experiment, use the following redirector, then
	test with "telnet 127.0.0.1 10000". It should give you telnet
	access to your local machine.

        /*
         * telnet.cfg
         *
         * Forward all connections on TCP port 10000 to 127.0.0.1:23
         */
        tcp { 10000 { => 127.0.0.1:23 } }
        /*
         * eof: telnet.cfg
         */

        Below you can see a more complete example using most features
	of portfwd.

        /*
         * example.cfg
         */     
        user  nobody
        group nobody
        
        tcp /* TCP connections */
        { 
                /*
                 * Connections on port 12000 from subnet localhost/24 and
                 * ports in the range 0-5000 are forwarded to 127.0.0.1:23.
                 * Anything else goes to localhost:80.
                 */
                12000 { 
                        localhost/24:+5000  => 127.0.0.1:23;
                        /* anything else */ => localhost:80
                };
        
                /*
                 * On port 11000, connections from address localhost, any 
                 * port, are forwarded to 127.0.0.1:telnet.
                 */
                11000 { localhost => 127.0.0.1:telnet };
        
                10000 
		ftp-active-mode-on 127.0.0.1
		ftp-passive-mode-on 127.0.0.1
                { => localhost:ftp }
        }
        
        udp /* UDP packets */
        {
                /*
                 * All packets on port 10000 are forwarded to 127.0.0.1:11000.
                 */
                10000 { => 127.0.0.1:11000 }
        }
        /*
         * eof: example.cfg
         */

RUNNING BASICS

	1. START

        Type:
        portfwd -c <path_to_config_file>

	2. STOP

	Send a TERM signal to the Portfwd master process (the one with
	lowest PID).

COMMAND LINE OPTIONS

	SYNTAX HELP

	Option -h provides brief help on command line syntax.

	CONFIGURATION FILE

	Use -c <config_file_path> to specify the location of your
	configuration file.

	TRANSPARENT PROXY

	The -t switch enables transparent proxying; i.e. IP address of
	outgoing data are "faked" to match those from incoming
	data. If you plan to forward data to hosts behind your
	firewall, you probably want this option turned on, as it
	allows for your servers to see original addresses of clients.

        DEBUG

        If the -d switch is given, portfwd will produce verbose
	logging for debug purposes. Up to 3 switches are meaningful.

        Failure messages are sent to the system log under the
	"daemon" facility.

	PROGRAM VERSION

	Portfwd version can be obtained by passing the -v switch.

SUPPORT

	If you have further questions, please consult the FAQ. If the
	doubt persists, fell free to contact me through the e-mail
	address given below.

	Everton da Silva Marques <evertonm@my-deja.com>

				 -x-