tcpproxy.1

tcp protocol proxy,it is userful!

.de ES
.sp
.in +0.5i
..
.de EE
.in -0.5i
.sp
..
.de EX
.sp
.in +0.5i
\\$1
.in -0.5i
.sp
..
.TH TCPPROXY 1 "02 September 1999"
.SH NAME
tcpproxy \- generic TCP proxy server
.SH SYNOPSIS
\fBtcpproxy\fR [\fIoptions\fR] [\fIserver\fR]
.SH DESCRIPTION
.I tcpproxy
is a generic TCP proxy server.
It connects a client and a server and forwards any data from the client to
the server and vice versa.
\fItcpproxy\fR doesn't care about the data being transported.
.PP
If \fIserver\fR begins with a `/' or `.' it's taken as a pathname to a
program that acts as a request handler for incoming connections.
Otherwise \fIserver\fR is interpreted as \fIhost\fR[:\fIport\fR] and the
client request is forwarded to the given \fIhost\fR and \fIport\fR.
If in this case \fIport\fR is omitted \fItcpproxy\fR uses it's own server
port as destination port on \fIhost\fR.
.PP
If \fItcpproxy\fR has to start a local program it set the environment
variables \fBPROXY_PORT\fR, \fBPROXY_INTERFACE\fR, \fBPROXY_CLIENT\fR and
\fBPROXY_CLIENTNAME\fR with the data of the current connection.
The `PROXY_' prefix might be changed with the command line option \fB-v\fR
or the \fBsetenv\fR configuration directive.
.PP
.I tcpproxy
can be either started from
.IR inetd (1)
or act as a standalone server listening an several ports.
If the \fIserver\fR argument is missing \fItcpproxy\fR reads it's configuration
file \fI/etc/tcpproxy.conf\fR and either forwards the current connection or
binds to the specified ports waiting for client requests.
.SH "CONFIGURATION FILE"
The following directives define the global configuration.
.TP
\fBuid\fR \fInumeric-uid\fR
defines the numeric user id to which \fItcpproxy\fR changes before listening
to client requests.
.TP
\fBgid\fR \fInumeric-gid\fR
same as \fBuid\fR but for the group id under which the server runs.
.TP
\fBstandalone\fR [\fByes\fR|\fBno\fR]
if set to `yes' the server binds to the defined ports waiting for requests.
This is the default if a configuration file is used.
.PP
The \fBuid\fR and \fBgid\fR settings are only used if the user starting
\fItcpproxy\fR is \fBroot\fR, otherwise they are ignored.
If however the calling user is \fBroot\fR and no settngs are found
\fItcpproxy\fR uses it's internal default of -1 and -2 for the user and
group id.
\fItcpproxy\fR won't run as root.
.PP
The following directives control the available services and how they are
served.
.TP
\fBport\fR \fIport-number\fR
defines a new port where \fItcpproxy\fR should accept client requests.
.TP
\fBinterface\fB \fIip-number\fR
defines an interface on which connections on the service port from the
last \fBport\fR directive are handled.
.TP
\fBserver\fB \fIserver\fR[:\fIport\fR]
defines the server and port where \fItcpproxy\fR will forward an incoming
connection to.
If \fIport\fR is ommited the listening \fItcpproxy\fR port is used.
.TP
\fBexec\fR \fIcommand\fR
defines a local command which is executed to handle a request.
.TP
\fBacp\fR \fIprogram\fR
sets the access control program that is used to grant or deny incoming
connections.
.TP
\fBtimeout\fR \fItimeout\fR
defines a different timeout in seconds than the default of 60.
.TP
\fBsetenv\fR \fIvarprefix\fR
defines the variable prefix.
.TP
\fBwritefile\fR \fIfilename\fR
defines the basename for files where the server/client communication
is written.
.PP
For a service configuration either \fBserver\fR or \fBexec\fR must be
specified.
The \fItimeout\fR value is only used in conjunction with a \fIserver\fR
configuration and \fIvarprefix\fR only if requests are handled by a local
program.
\fBtimout\fR, \fBsenenv\fR amd \fBacp\fR define configuration defaults if they
appear before the first \fBport\fR directive.
.SH "ACCESS CONTROL"
If for a port configuration an access control program is set this program
is executed before forwarding the request.
The acp can then decide if it grants (exit status 0) or denies (exit
status not 0) the access.
The acp can additionaly print a diagnostic message to the requesting client
through it's standard output and to the \fItcpproxy\fR through it's
standard error.
.PP
The \fBPROXY_\fR variables are set for the current connection when the
acp is called.
.SH OPTIONS
The following options are available:
.TP
\fB-a\fR \fIprogram\fR
sets \fIprogram\fR as access control program.
.TP
\fB-b\fR [\fIinterface\fR:]\fIport\fR
tells \fItcpproxy\fR that it should bind to \fIport\fR on the given
\fIinterface\fR.
If \fIinterface\fR is omitted \fItcpproxy\fR will bind to all available
interfaces.
\fB-b\fR implies \fB-s\fR.
.TP
\fB-f\fR \fIconfig\fR
sets a different configuration file than \fI/etc/tcpproxy.conf\fR.
.TP
\fB-l\fR \fIlogname\fR
sets the name under which \fItcpproxy\fR writes to syslog.
.TP
\fB-p\fR
creates the pidfile \fI/var/run/tcpproxy.pid\fR.
This default name can be changed by giving the \fB-p\fR option twice followed
by the name of the pidfile.
.TP
\fB-s\fR
sets standalone (bind to ports and listen) mode.
.TP
\fB-t\fR \fItimeout\fR
defines a different \fItimeout\fR in seconds than the default of 60 seconds
for each connection.
.TP
\fB-v\fR \fIvarprefix\fR
specifies a different variable prefix than `PROXY_' for the request handler
variables.
.TP
\fB-w\fR \fIwritefile\fR
specifies that the client/server communication is written to the
file \fIwritefile\fR.pid.log.
.TP
\fB-y\fR
clears the whole environment before starting the request handler.
.TP
.B -z
lists the configured server ports and exits.
This is useful if you want to shutdown the tcpproxy services with either
\fIfuser\fR(1) or \fInetuser\fR(1).
Giving \fB-z\fR twice lists the basic configuration data.
.PP
In case that the \fB-b\fR option is found on the command line the \fIserver\fR
is expected.
.SH "EXAMPLES"
The following examples assume that \fItcpproxy\fR is installed on a machine
with two network interface cards.
One is the external interface with the IP number 192.44.100.7 and the other
is the internal one with IP numbers 192.168.1.1 and 192.168.1.2 (virtual
interfaces).
.ES
 #
 # /etc/tcpproxy.conf - sample configuration
 #
 
 #
 # Define SMTP proxys ...
 #
 port 25

   # ... for outgoing ...
   #
   interface 192.168.1.1
     server mailrelay.provider.com

   # ... and incoming email.
   #
   interface 192.44.100.7
     server mail.domain.com

 #
 # There are also NNTP-Servers on the outside
 #
 port 119

    interface 192.168.1.1
      server nntp.provider.com
     
    interface 192.168.2.1
      server nntp.other-provider.com

 #
 # Users from the outside can access our internal
 # POP3 server ...
 #
 port 110

   interface 192.44.100.7

   # ... but only trough a real application gateway.
   #
   exec /usr/local/sbin/pop3.proxy mail.domain.com
.EE
With this configuration file \fItcpproxy\fR might be started with
.EX "tcpproxy -s"
to make tcpproxy bind itself to all the listed interfaces.
Another way of serving requests is to configure the ports in
\fI/etc/inetd.conf\fR
and start \fItcpproxy\fR without the \fB-s\fR option from there.
The proxy will then inspect it's configuration file to see how the connection
made by \fIinetd\fR should be handled.
.PP
tcpproxy -b 192.44.100.7:79 /bin/date
opens a date server on the external interface.
This service won't be available on the interfaces numbered 192.168.1.1
and .2 but the service is still accessable from the internal network:
.ES
 user@192.168.1.10/~ > telnet 192.44.100.7 79
 <current date goes here>
.EE
If you want to provide a service only on one network card you'll have to
implement further access control of packet filters.
.SH NOTES
\fItcpproxy\fR doesn't forward the FTP protocol.
It doesn't work with any UDP protocol too.
And furthermore \fItcpproxy\fR doesn't protect you against network attacks
like buffer overflows.
You'll have to use application gateway level proxys for that.
.SH "SEE ALSO"
.IR inetd (1).