tcp-proxy, test-tcp — transparent generic TCP proxy


tcp-proxy [-hv] [-d dbglev] -f cfgfile

test-tcp [-hv] [-d dbglev] -f cfgfile [-r] [-t test_expr]


The tcp-proxy is a generic TCP proxy that provides proxying protocols behaving according to standard TCP client/server model. The tcp-proxy assumes that servers are listening on a fixed TCP port number, clients connect to them using arbitrary source TCP port numbers and each session takes place within a single TCP connection; no other connections are involved in the session. The tcp-proxy is able to mediate either transparent connections to any number of servers according to the original destination address or to a fixed server, given its address in configuration.

The tcp-proxy reads its configuration file and starts listening on specified TCP sockets (address/port couples), as specified in the listen-on configuration directive. When a connection arrives, configuration is consulted and based on it, a decision is made whether this connection will be permitted. If permitted, several parameters of that connection may be set.

Format of the configuration file is described in tcp-proxy.cfg(5). Program test-tcp tests syntax and partially semantics of configuration; for test expression syntax, see test-expr(5).

Tcp-proxy uses single phase ACL (see access-control(7) manual page) named session-acl.

When a non-transparent connection arrives (i.e., a connection destined directly for one of the sockets tcp-proxy is listening on) and is allowed by policy, the proxy must be configured to connect to a specific remote server with plug-to configuration directive (see below).

When a transparent connection arrives (i.e., a connection destined for a real server transparently redirected to tcp-proxy, see transparency(7) for details), the proxy may decide to connect to the original destination server or to the plug-to given in configuration. If a plug-to directive is applicable for a transparent connection, it has precedence over the original destination. This means that tcp-proxy will ignore the original destination and connect to the plug-to server.

The tcp-proxy uses common Kernun mechanism for listening on its sockets, forking new processes as needed and killing old redundant processes, optionally changing root directory and running with alternative user privileges. For more detailed information, see application(5), tcpserver(5), and tcpserver(7).

The tcp-proxy uses common Kernun mechanism for network input/output operations. Configuration allows for specifying several parameters like buffer sizes and timeouts, both for client and server connections. They can be included in client-conn and server-conn configuration sections, respectively. For more detailed information, see netio(7).

The tcp-proxy uses common Kernun mechanism for logging. For more detailed information, see logging(7). For each connection, three statistical messages are logged: SESSION-START (when the connection is established), ACL (informs about ACL selected for the connection), and SESSION-END (when the connection is closed).

The tcp-proxy uses common Kernun mechanism for policy decisions on arriving connections. It is described in access-control(7) and host-matching(7). For example, it is possible for tcp-proxy to use the real client's address or any specified address as source address for connection to server.

The tcp-proxy uses common Kernun mechanism for runtime monitoring. For more detailed information, see monitoring(7).

The tcp-proxy uses common Kernun mechanism for traffic shaping. For more detailed information, see traffic-shaping(7).

Firewall administrator can choose the out-of-band method described in auth(7) for authenticating users on the proxy.

The tcp-proxy allows to set several parameters in session-acl:

plug-to addr;

Specify server socket address to connect to. This applies both for transparent and non-transparent connections (in the latter case, it is even mandatory).

max-bytes number number;

Maximum number of octets transferred from server to client (first number) and from client to server (second number). The numbers are optional but they default to zero which has a special meaning no limit to transfer size. When either of the limits gets exceeded, both client and server connections are closed by the proxy.

max-time seconds;

Maximum duration of a session. When this time elapses since the connection establishment, both client and server connections are closed by the proxy.

cl2srv-idle-timeout seconds;

Maximum idle time for client-to-server data. When no data are received from the client for this time interval, both client and server connections are closed by the proxy.

srv2cl-idle-timeout seconds;

Maximum idle time for server-to-client data. When no data are received from the server for this time interval, both client and server connections are closed by the proxy.

The tcp-proxy provides encryption and authentication using SSL/TLS protocols. SSL/TLS can be configured separately for the connection from the client and the connection to the server. Four variants are possible: either no connection uses SSL/TLS, or both connections use SSL/TLS, or only one of them uses SSL/TLS. The SSL/TLS mode can be used for building secure tunnels. A client communicates using plain TCP with tcp-proxy. The proxy connects via an SSL/TLS encrypted channel to another proxy across an untrusted network. The second proxy opens a plain TCP connection to a remote server.

SSL/TLS communication with clients can be turned on globally by client-ssl-params configuration directive. Parameter client-ssl-timeout limits the time interval between TCP connection establishent and finishing SSL/TLS handshake. When SSL/TLS is used, session-acl can be selected according to the values from the client certificate (client-cert-match). Enabling SSL/TLS is done by server-ssl-params in session-acl. Item server-cert-match defines requirements for the server certificate. If the certificate does not satisfy the requirements, the proxy terminates the session.



Print usage information.


Display version information and exit.

-d dbglev

Set debuging level to a specific number. Permitted values are 3 through to 9, 3 being the least and 9 the most verbose. See logging(7) for details. This setting is relevant only till configuration reading is finished.

-f cfgfile

Read cfgfile for configuration information.


Resolve names in configuration prior to testing.

-t test_expr

Test configuration according to given expression. Format of the test_expr is described in test-expr(5).

See Also

listen-on(5), application(5), tcp-proxy.cfg(5), tcpserver(5), test-expr(5), access-control(7), configuration(7), host-matching(7), logging(7), monitoring(7), netio(7), tcpserver(7), time-matching(7), traffic-shaping(7), transparency(7)


This man page is a part of Kernun Firewall.
Copyright © 2000–2023 Trusted Network Solutions, a. s.
All rights reserved.