Consulting djbware Publications

tcpserver - accept incoming IPv4/IPv6 TCP connections and invoke application


tcpserver allows applications to accept TCP connections in a chroot environment. Unlike inetd or xinetd it is not a `super daemon` but works for individual connections in the user space.

tcpserver can listen to any IPv4/IPv6 address and any port. It also supports binding to all local IPv4 and IPv6 addresses (simultaneously).

Reversely, incoming IP/TCP connections are usually under control of tcprules allowing filtering on IP addresses and DNS informations. Remote clients thus can be qualified prior of accepting a TCP session which could be understood as user-level firewall.

Application support

Applications are enabled by means of tcpserver to communication with the network via the standard file descriptors

  1. FD 0: Reading from the network.
  2. FD 1: Writing to the network.

Application may be supplied with any arguments on call.

While typically tcpserver is invoked by root, the application is executed in a chroot enviroment with restricted permissons only. Therefore, one sets

upon calling tcpserver.

tcpserver spawns and instantiates a new copy of application whose concurrent number can be limited providing -c limit.

The application may be fed with several connection relevant informations pushed in its environment for further usage.

Local binding

tcpserver usually uses the host's primary IP address, but can otherwise bind to any IPv4 and/or IPv6 address of the system and to any port (given the required permissions) as defined by


tcpserver will allow to bind to IPv6 LLU addresses, in case additionally the interface name is provided. Beware, that LLU address are in particular subject of SLAAC changes.

Name resolution

tcpserver reads the environment variable DNSCACHEIP which can be used to specify the recursive DNS Resolver.

If not given, tcpserver uses the nameserver entries provided in /etc/resolv.conf.

Network settings and connections from the remote client

Prior to spawning the application tcpserver and be advised to evaluate several IP and DNS connection conditions which are subject of the client's IP and potentially the evaluated DNS and IDENT informations:

Now, TCP(6)REMOTEHOST is correctly populated.

Nowadays almost avoided is the lookup of the remote user via IDENT/TAP:

Apart from those possibilities, some unusual settings are available:

Controlling remote connection behavior via tcprules

tcpserver can be advised to read one or more cdb's prior to accepting a TCP connection including additional policy informations how to handle a connection and which environment variables to be exported to the application:

In order to operate successfully, tcpserver supplies tcprules with the following data to be compared against a database (cdb):

  1. The IP address of the remote client (always),
  2. the hostname (given a DNS lookup),
  3. the identity of the remote caller (given a IDENT lookup).

Certain rules can be set up:

TCP connection management and spawning

Upon invocation from an accepted TCP client tcpserver spawns a new instance while setting up the environment and invoking the application.

TCP connections can be restricted by

  1. (global) -c n, where n is the number of active concurrent tcpserver instances and thus called applications. The default is 40.
  2. (gobal) $MAXCONIP is the number of maximum TCP connections from one single IPv4/IPv6 source given as environment variable resulting to limit the number of children for each uniqe IP address.
  3. (restricted) $MAXCONIP to be provided within a cdb to define a (typically small) value for a given network range or single IP address to be used now as limit to accepted TCP connections from that range for each unique IP address.

In the last case, tcpserver can limit the number of concurrent connections from a single source (or a network range) to 'n' instances prior of calling application and thus preventing a denial of service (DoS) attack. It should be noted, that changes of enviroment variables following the settings in tcprules don't require a new start of tcpserver.

Environment variables set

tcpserver sets up several environment variables available for the application, as described in tcp-environ:

DNS (TCPREMOTEHOST, tcp6REMOTEHOST) and the IDENT (TCPREMOTEINFO) informations are optional and depending on the arguments supplied.


Invoking tcpserver with the options

will provide a logging of the session on FD = 2 including (if possible) the hostname, as well as the used IP addresses and ports of the peers. A DNS lookup for the localhost can be avoided and substitued by a generic name. The displayed IP addresses are shown either as generic IPv4 or as compactified IPv6 addresses.