"Fossies" - the Fresh Open Source Software Archive

Member "tcpproxy-2.0.0-beta15/tcpproxy.1" (28 Aug 2006, 18471 Bytes) of package /linux/privat/old/tcpproxy-2.0.0-beta15.tar.gz:

Caution: As a special service "Fossies" has tried to format the requested manual source page into HTML format but links to other man pages may be missing or even erroneous. Alternatively you can here view or download the uninterpreted manual source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.




tcpproxy − generic TCP proxy server


tcpproxy [options] [server]


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. tcpproxy doesn’t care about the data being transported.

If server begins with a ‘/’ or ‘.’ it’s taken as a pathname to a program that acts as a request handler for incoming connections. Otherwise server is interpreted as host[:port] and the client request is forwarded to the given host and port. If in this case port is omitted tcpproxy uses it’s own server port as destination port on host.

If tcpproxy has to start a local program it set the environment variables PROXY_PORT, PROXY_INTERFACE, PROXY_CLIENT and PROXY_CLIENTNAME with the data of the current connection. The ‘PROXY_’ prefix might be changed with the command line option -v or the setenv configuration directive.

tcpproxy can be either started from inetd(1) or act as a standalone server listening an several ports. If the server argument is missing tcpproxy reads it’s configuration file /etc/tcpproxy.conf and either forwards the current connection or binds to the specified ports waiting for client requests.

User IDs
If tcpproxy is started as user root it will change to the user nobody after a connection is accepted, that is, tcpproxy will not run as root if not configured so. Other user ids can be configured with either the user configuration option or the -u command line switch. Both accept a parameter of the form



If only username is given username’s user and group id are set as read ids.


Giving the numeric userid argument sets only the user id.


The group part (which can be set with ot without the user part) sets always only the group id either by the group’s name or it’s numeric id.

Usually the exact user id is not important for proxy connections as long as it’s not root. This may be different if tcpproxy is used to start services that need certain privileges like an FTP or ssh server.

Dynamic Interfaces
The interface configuration option accepts now also interface names (everything that does not start with a number is considered to be the name of a network card, tcpproxy does not verify that the interface exists). In this case tcpproxy binds to all interfaces on the requested port and evaluates the interface’ss IP number when a request comes in.

Interface Wildcards
The interface parameter may be also ‘any’ or ‘*’ which work as wildcard for all interfaces. Since proxy definitions are searched in the order as they appear in the configuration file these keywords can be used to define default rules.

Connection Redirection
may receive connection request which were originally not destined for it by configuring an iptables/NAT rule like

# iptables -t nat -A PREROUTING --protocol TCP \
--dport 25 -j REDIRECT --to-port 8025
In this example all connections requests going to port 25 would be redirected to the machine’s local port 8025.

tcpproxy accepts such requests either if configured for this or not. Support for redirected requests can be configured with either the redirect-mode configuration option. Valid redirect modes are


turns off any special redirect handling, this is the default.


puts the original requested server data into the PROXY_ORIGDST variables, connects the client to the configured server.


puts the original requested server data into the PROXY_ORIGDST variables and connects the client to the requested server.


like forward but drops connections which are not redirected.

The redirect mode can also be set with the -r command line switch.

Connection Status Files
can write information about it’s current connections to status files, one for each connection. Each status file contains the following, space separated, information:


program name, is always tcpproxy,


the configured logname, default is tcpproxy,


the proxy’s process id,


time in seconds since 01.01.1970 when the process started,


IP number and port of the proxy’s incoming interface,


client’s IP number and name,


IP number and port of the server,


IP number and port of the original requested server if the connection was redirected, otherwise ‘’.

To enable status files either the statdir option must be set in the configuration file or the directory must be specified with the -o command line option.

The statdir is a global option and used for all proxy configurations. Status files are automatically removed when the proxy terminates and the file and directory permission allow it.

Client Address ACLs
has simple IP number access control list handling built in. If an acl is set for a port/interface configuration the acl is evaluated after the request accepted. acls are comma separated list of IP numbers optionally followed by a network mask. Each list item is prefixed with a plus or minus sign to grant or deny access for the item’s IP specification. The plus sign may be omitted. The acl’s result is the result of the ‘best-matching’ list item, that is the item with the smallest network mask.

IP acls can be set with either the -A command line option or with the acl configuration option. If an acl is configured the default is to deny access if the acl does not grant. More than one acl option may be given in whch case the options sum up to one large list.

Access Control Programs
If for a port configuration an access control program is set (-a command line or acp configuration option) this program is executed after accepting but before forwarding the request. The acp receives the environment variables listed below.

The access control programm (acp) grants or denies access with it’s exit code, 0 to accept and non-zero to deny. The acp can print an additionaly diagnostic message to it’s stderr which is send to syslog.

Session Logfiles
writes it’s log messages to syslog. In addition to this the messages from each session can be written into a logfile (one for each session) and the logfile may be (depending on the session’s exit code) kept or passed to a script. The handling mode is set with the session-mode option, valid options are:


turns session handling off.


session logfiles are kept where they are created.


the session logfiles is passed via stdin to a program (set with the exit-handler option).

Exit codes for which the logfile is kept or processed can be selected with the exit-code configuration option. Valid exit codes are


occurs when proxy access is denied, possible reasons are denied by acp, by acl or no configuration.


the proxy could not connect to any of configured upstream servers.


the connection timed out.


the proxy detected an error on the server side.


the proxy detected an error on the client side.


a proxy error occured.


the proxy session generated warning (e.g. the proxy could no connect to one of the configued servers) but the session itself did not return any error.


the proxy session did not generate errors or warnings.


any of the error codes above.

If an exit-handler script is configured it is called with environment variables set (see "Environment Variables" below) and the session’s logfile on it’s stdin..

All session options are global and therefore used for all proxy configurations.

Environment Variables
sets the following environment variables (listed in alphabetical order).

configured interface (the configured value) followed by a colon and the port where the client is connected.


number of bytes send to the server.


number of bytes send to the client.


IP number and name of the client.


session’s duration in seconds.


the IP number of the interface where the client is connected.


is either the configured logname or ‘tcpproxy’.


the value as set by the name configuration option.


if the connection is redirected from a NAT rule and NAT support is turned on, these variable hold server and port of the original request.


tcpproxy’s process id.


is always ‘tcpproxy’.


the server’s IP number and name.


the server port.


the time (as number of seconds from 1970) when the session started.


the session’s exit-code.


the session exit code as numerical value.

Notice that not all of the variables above are always set, this depends on the session’s state.


Global Options

if set to ‘yes’ the server binds to the defined ports waiting for requests. This is the default if a configuration file is used.

pidfile pathname

sets the name of tcpproxy’s pidfile. tcpproxy will write the pidfile only when running in standalone mode and remove it when it terminates.

setenv varprefix

defines a different variable prefix than ‘PROXY_’.

Service Configuration
All proxy services are configured by a port option followed by an interface on the next line. The following directives control the available services and how they are served.

sets the access control program that is used to grant or deny incoming connections.

exec command

defines a local command which is executed to handle a request.

extended-info boolean

if set to yes tcpproxy included the client’s source port and its own outgoing connection info into the logentry when the connection to the server is established.

interface ip-number|interface-name

defines an interface on which connections on the service port from the last port directive are handled. If the name of a network interface is given, tcpproxy will bind to all interfaces on that port and evaluate the interface’s IP number when a request comes in.

logname name

sets a different syslog name.

port port-number

defines a new port where tcpproxy should accept client requests.

rotate ip-start ip-end

defines a range of IP numbers that is used for the connection to the server.

server server[:port]

defines the server and port where tcpproxy will forward an incoming connection to. If port is ommited the listening tcpproxy port is used.

srcip ip-number

sets the source IP number for the outgoing connection to the server.

timeout timeout

defines a different timeout in seconds than the default of 60.

user [username|userid][.groupname|groupid]

instead of giving numeric ids for user and group for a particular user it’s name can be set directly.

writefile filename

defines the basename for files where the server/client communication is written.
is a synonym for writefile but turns also tcpproxy’s debug option ‘-dfR’ on.

For a service configuration either server or exec must be specified. The timeout value is only used in conjunction with a server configuration and varprefix only if requests are handled by a local program. timeout, setenv amd acp define configuration defaults if they appear before the first port directive.

Session Statusfiles

sets the directory where tcpproxy should write it’s statusfiles.

Session Handling
The interface to session handling may change in a future release.

set the directory where tcpproxy stores it’s session logfiles.

session-mode word

set the session handling mode.

exit-code list

defines the exit codes for which session handling is done.

exit-handler path [arg ...]

sets the exit handler program with optional command line arguments.

All of the options above must be set to activate session handling.


The following options are available:

sets program as access control program.

-b [interface:]port

tells tcpproxy that it should bind to port on the given interface. If interface is omitted tcpproxy will bind to all available interfaces. -b implies -s. interface might be the name of a network interface card.


sets debug mode, diagnositc output is printed to stderr and tcpproxy does not fork into the background in standalone mode.

-f config

sets a different configuration file than /etc/tcpproxy.conf.

-l logname

sets the name under which tcpproxy writes to syslog.


does not resolve the client’s name, use it’s IP number.

-o directory

sets the directory where tcpproxy stores it’s statfiles and turn statfile creation on.

-p | -pp filename

creates the pidfile /var/run/tcpproxy.pid. This default can be changed by giving the -p option twice followed by the name of the pidfile. The pidfile is only in standalone mode created.

-q srcip

sets a single source IP for the outgoing connection.

-r mode

sets support for redirected connection to mode.


sets standalone (bind to ports and listen) mode.

-t timeout

defines a different timeout in seconds than the default of 60 seconds for each connection.

-u [username|userid][.groupname|groupid]

sets the user and/or group to which tcpproxy after a connected has been accepted and if started as root. The default is to take user and group id of the user nobody.

-v varprefix

specifies a different variable prefix than ‘PROXY_’ for the request handler variables.

-w writefile

specifies that the client/server communication is written to the file writefile.pid.log.


clears the whole environment before starting the request handler.

-A string

adds the IP range string to the access control list. -E mode,dir,handler sets the session handler mode, directory and handler script for tcpproxy’s exit-handler, the handler is called for any exit code.


selects extended connection loginfo (see extended-info above).

-O dir

sets the session directory.

In case that the -b option is found on the command line the server argument is expected.


The following examples assume that tcpproxy is installed on a machine with two network interface cards. One is the external interface named ppp0 with a dynamic IP number and at least one internal interface with the IP number

# /etc/tcpproxy.conf - sample configuration

# Define SMTP proxys ...
port 25

# ... for outgoing ...
server mailrelay.example.com
timeout 60

# ... and incoming email which is devlivered on our external and
# dynamic interface ppp0.
interface ppp0
server my-local-smtp.server

# We also define a default configuration for other interfaces
interface *
server another-mail-server

# Users from the outside can access our internal
# POP3 e-mail ...
port 110

# We have support for any external POP3 server trough transparent
# proxy-ing - don’t forget the iptables rule.
redirect-mode only
timeout 120

# Outside users can fetch it from the local server,
# but only trough a real application gateway.
interface ppp0
exec /usr/local/sbin/pop3.proxy my-local-pop3-server

With this configuration file tcpproxy might be started with
to make tcpproxy bind itself to all the listed interfaces.
Another way of serving requests is to configure the ports in

and start tcpproxy without the -s option from there:
The proxy will then inspect it’s configuration file to see how the connection
made by inetd should be handled.

tcpproxy -b /bin/date
opens a date server on the external interface.
This service won’t be available on the interfaces numbered
and .2 but the service is still accessable from the internal network:

user@ > telnet 79
<current date goes here>
If in inetd mode you want to provide a service only on one network card you’ll have to implement further access control with packet filters.


tcpproxy doesn’t forward the FTP protocol; use ftp.proxy for this. It doesn’t work with UDP protocols too, TCP uses connection and UDP not - this is an imortant difference. And furthermore tcpproxy doesn’t protect you against network attacks like buffer overflows against the addressed server. You’ll have to use application gateway level proxys for that.