Description

udp-socket-listen is a chain-loading utility that opens a UDP socket bound to host and port, sets the socket to file descriptor 3 (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 udp-socket-listen will ignore.

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

The [--reuse-port] sets a flag that allows the same IP address and port combination to be used by multiple UDP 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 [--systemd-compatibility] option causes udp-socket-listen to set the LISTEN_FDS environment variable to 1, and the LISTEN_PID environment variable to its own process ID. This is for compatibility with daemons that expect to be run under systemd(1).

For compatibility with daemons 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

udp-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 udp-socket-listen processes.

USAGE

udp-socket-listen can be used as a simple daemon monitored by service-manager(1). udp-socket-listen overlaps the functionality of inetd(1) and systemd(1) (in the systemd-recommended configuration of Accept=false sockets).

To change the process' UID and GID after opening the socket, simply chain through setuidgid(1).

Author

Jonathan de Boyne Pollard