Name

tcp-socket-listen — create a socket listening for incoming TCP connections and chain

Synopsis

tcp-socket-listen [--no-reuse-address] [--reuse-port] [--bind-to-any] [--numeric-host] [--numeric-service] [--check-interfaces] [--combine4and6] [--backlog number] [--upstart-compatibility] [--systemd-compatibility] {host} {service} {next-prog}

Description

tcp-socket-listen is a chain-loading utility that opens a TCP socket bound to host and service, executes a call to listen(2), sets the socket to file descriptor 3+n (where n is the number of already-opened listening file descriptors), closing whatever that descriptor was, and then chain loads to next-prog with the execvp(3) function.

next-prog may contain its own command line options, which tcp-socket-listen will ignore.

If the --numeric-host command line option is used, then no name lookup is done on host and it must be (a human readable form of) an IP address. If the --numeric-service command line option is used, then no name lookup is done on service and it must be a port number. Otherwise, host is looked up using the system name resolution facility, with the first IP address found being used, and service can be an alphanumeric service name.

The --backlog option specifies the allowed backlog level (defaulting to 5) of outstanding not-yet-accepted connections to the socket. The --no-reuse-address sets a flag that prevents the kernel from re-using an IP address and port combination if there are still TCP connections for that address and port in the CLOSE_WAIT state,

The --reuse-port option sets a flag that allows the same IP address and port combination to be used by multiple TCP listeners, as long as they all use the flag. The --check-interfaces option prevents the use of any IPv4 addresses if there are no IPv4 addresses on any network interface, and the use of any IPv6 addresses if there are no IPv6 addresses. This isn't particularly useful on a dynamically configured system where network interface IP addresses can come and go. Conversely, the --bind-to-any option is quite useful on such a system, as it allows binding to any IPV4 or IPV6 address, even one that is not on any network interface.

The --upstart-compatibility option causes tcp-socket-listen to set the UPSTART_FDS environment variable to 3, and the UPSTART_EVENTS environment variable to socket. This is for compatibility with dæmons that expect to be run under upstart(1).

The --systemd-compatibility option is for compatibility with dæmons that expect to be run under systemd(1). It causes tcp-socket-listen to set the LISTEN_FDS environment variable to the number of listening file descriptors, and the LISTEN_PID environment variable to its own process ID. If the command is started up with the LISTEN_FDS and the LISTEN_PID environment variables already appropriately set, the number of listening file descriptors is taken from them and increased by one, otherwise the number of file descriptors is 1. Thus a list of listening file descriptors can be built up with multiple commands, as long as they all use the --systemd-compatibility option.

For compatibility with dæmons that expect to be run under inetd(1), inheriting the listening socket as their standard input, simply use fdmove 0 3 in next-prog. See fdmove(1).

On systems that support such, the --combine4and6 option allows a listener to communicate with both IPv4 and IPv6 clients. (host must denote an IPv6 address for this to work.) On other systems, and also the default if --combine4and6 is not used, one must run an IPv4 listener for IPv4 clients and an IPv6 listener for IPv6 clients. See RFCs 3493 and 4038 for more details.

Protocols

tcp-socket-listen is fully IPv6 capable, albeit that by the nature of IP versions it is not possible on some operating system kernels to handle both IPv4 and IPv6 with a single socket. To listen on an IPv4 address and an IPv6 address on such kernels, one must have two tcp-socket-listen processes.

Usage

tcp-socket-listen can be used as a simple dæmon monitored by service-manager(1) that chains to tcp-socket-accept(1). Together, the two replace tcpserver(1) from ucspi-tcp. tcp-socket-listen overlaps the functionality of inetd(1) and systemd(1), with which only the tcp-socket-accept(1) half of the pair would be needed (in the systemd-recommended configuration of Accept=false sockets).

To change the process' UID and GID after a successful call to listen(2), simply chain through setuidgid(1).

See also

udp-socket-listen(1), local-datagram-socket-listen(1), local-stream-socket-listen(1), local-seqpacket-socket-listen(1), netlink-datagram-socket-listen(1)

listeners for other protocols

Author

Jonathan de Boyne Pollard