tcpserver(1)

NAME
tcpserver - accept or deny incoming TCP connections

SYNOPSIS
tcpserver [ -146jpPhHrRoOdDqQv ] [ -climit ] [ -X-xrules.cdb ] [ -X-yrules.cdb ] [ -Bbanner ] [ -ggid ] [ -uuid ] [ -bbacklog ] [ -llocalname ] [ -ttimeout ] [ -Iifname ] host port program [ arg ... ]

DESCRIPTION
tcpserver waits for connections from TCP clients. For each connection, it runs program with the given arguments, with descriptor 0 reading from the network and descriptor 1 writing to the network.

BINDINGS
tcpserver will attach to the primary IP address of host while the host name is fed through qualification using dns_ip6_qualify. If host is given as dotted decimal IPv4 or compactified IPv6 address, tcpserver will bind uniquely to those. In order to bind tcpserver to a LLU IPv6 address (ie. fe80::a:b:c) additionally the interface name -Iifname has to be provided. Note: The kernel might use temporary changing SLAAC addresses. tcpserver can be instructed to be multi-homing capable while binding to all available IP addresses. Now host is given as 0.0.0.0 or ::. tcpserver additionally supports legacy binding to host as 0 which is identical to 0.0.0.0. Further, tcpserver may be forced to provide dual-stack capabilities, thus allowing IPv4 and IPv6 clients to attach to the same instance once host equals :0 as pseudo IP address. port may be a numeric port number or a port name. If port is 0, tcpserver will choose a free port. tcpserver sets up several environment variables, as described in tcp-environ(5). tcpserver exits when it receives SIGTERM.

OPTIONS

-1  After preparing to receive connections, print the local ip address and port number to standard output.

-4  Only use IPv4 connections.

-6  Force IPv6 connections.

-c n
    Do not handle more than n simultaneous connections. If there are n simultaneous copies of program running, defer acceptance of a new connection until one copy finishes. n must be a positive integer. Default: 40.

-x rules.cdb
    Follow the rules compiled into rules.cdb by tcprules. These rules may specify setting environment variables or rejecting connections from bad sources. tcpserver does not read rules.cdb into memory; you can rerun tcprules to change tcpservers behavior on the fly.

-X  continue processing, even if rules.cdb is not readable.

-y rules.cdb
    Evaluate and follow IP rules compiled into rules.cdb prior of doing a DNS or IDENT lookup. This rule file should only consider deny as rule, though a shared rules.cdb is possible. In case the IP address lookup deliveres a deny, the connection is closed immediately. If the lookup result is an explicit allow, the given environment variables are provided for connections from those source(s) and the preceeding -x cdb evaluation is omitted.

-B banner
    Write banner to the network immediately after each connection is made. tcpserver writes banner before looking up TCPREMOTEHOST, before looking up TCPREMOTEINFO, and before checking rules.cdb. This feature can be used to reduce latency in protocols where the client waits for a greeting from the server.

-g gid
    Switch group ID to gid after preparing to receive connections. gid must be a positive integer.

-u uid
    Switch user ID to uid after preparing to receive connections. uid must be a positive integer.

-I ifname
    Bind to the network interface ifname ("eth0" on Linux, for example). This is only defined and needed for IPv6 link-local addresses.

-b n
    Allow up to n simultaneous SYN_RECEIVEDs. Default: 20. On some systems, backlog is silently limited to 5. See listen(2) for more details.

-o  Leave IP options alone. If the client is sending packets along an IP source route, send packets back along the same route.

-O  (Default.) Kill IP options. A client can still use IPv4/IPv6 source routing to connect and to send data, but packets will be sent back along the default route.

-d  (Default.) Delay sending data for a fraction of a second whenever the remote host is responding slowly, to make better use of the network.

-D  Never delay sending data; enable TCP_NODELAY. This is appropriate for interactive connections.

-q  Quiet. Do not print any messages.

-Q  (Default.) Print error messages.

-v  Verbose. Print all available messages.

DATA-GATHERING OPTIONS

-p  Paranoid. After looking up the remote host name, look up the IP addresses for that name, and make sure one of them matches TCPREMOTEIP. If none of them do, unset TCPREMOTEHOST.

-P  (Default.) Not paranoid.

-h  (Default.) Look up the remote host name and set TCPREMOTEHOST.

-H  Do not look up the remote host name.

-l localname
    Do not look up the local host name; use localname for TCPLOCALHOST.

-r  Attempt to obtain TCPREMOTEINFO from the remote host.

-R  (Default.) Do not attempt to obtain TCPREMOTEINFO from the remote host.

-t n
    Give up on the TCPREMOTEINFO connection attempt after n seconds. Default: 26.

LOOPBACK ADDRESSES
IPv4 and IPv6 have a significant different understanding of loopback addresses:

    127./8

    ::1/128

this is the host-scoped loopback-address, while

    fe80::1%lo0

is the link-scoped looback-address and lo0 is the name of the loopback interface.

DNS RESOLVER SETTINGS
Use $DNSCACHEIP to set the DNS resolvers IP(s) dynamically irrespectively from the settings in /etc/resolv.conf. The individual IPs are separated by blanks; IPv6 LLU addresses may be appended with the interface name following a % sign. If the environment variable $LOCALDOMAIN is populated, this name will be appended to unqualified host names. Additional rewriting of local to public names is facilitated in case the file /etc/dnsrewritefile exists and is populated, or alternatively, the environment variable $DNSREWRITEFILE points to a different file.

ENVIRONMENT VARIABLES READ
tcpserver acknowledges the environment variable MAXCONIP="n" where n is the number of tcpserver children spawned for a particular remote IP address. n is initally set to the general connection limit c provided as call argument. MAXCONIP is typically defined in tcpservers cdb for a given condition and thus only active meeting those. MAXCONIP defaults 0 meaning no restriction.

ENVIRONMENT VARIABLES SET
tcpserver provides the following environment variables: PROTO this is either TCP or TCP6. The interface name for IPv6 connections: TCP6INTERFACE. The local information: TCPLOCALIP, TCP6LOCLAIP, TCPLOCALPORT, TCP6LOCALPORT, TCPLOCALHOST, TCP6LOCALHOST. The IP address of connection: TCPREMOTEIP and TCP6REMOTEIP. The remote port number: TCPREMOTEPORT, TCP6REMOTEPORT. The hostname (FQDN) of the peer, if available: TCPREMOTEHOST, TCP6REMOTEHOST. In case of a successfull IDENT lookup: TCPREMOTEINFO.

LOGGING
Invoking tcpserver with the option -v will provide a logging of the session including local and remote IP addresses and port together with the number of used/available/ip connection limited children:

tcpserver: status: x/y/z.

Additional information is given as:

tcpserver: ok pid localhost:ipbound:localport remotehost:remoteip:remoteport

tcpserver: deny pid localhost:ipbound:localport remotehost:remoteip:remoteport [ip connection limit:maxconip exceeded]

tcpserver: WARNING ip connection limit of maxconip exceeded for: remoteip

SEE ALSO
argv0(1), fixcr(1), recordio(1), tcpclient(1), tcprules(1), listen(2), tcp-environ(5)