Name

netlink-datagram-socket-listen — create a socket listening for incoming Netlink datagrams and chain

Synopsis

netlink-datagram-socket-listen [--raw] [--pass-credentials] [--pass-security] [--upstart-compatibility] [--systemd-compatibility] {protocol} {multicast-group} {next-prog}

Description

netlink-datagram-socket-listen is a chain-loading utility that opens a netlink datagram socket bound to protocol and multicast-group, 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 netlink-datagram-socket-listen will ignore.

The --pass-credentials option causes netlink-datagram-socket-listen to request the SO_PASSCRED socket option. The --pass-security option causes it to request the SO_PASSSEC socket option.

The --upstart-compatibility option causes netlink-datagram-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 netlink-datagram-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).

The netlink socket address family makes no distinction between the SOCK_RAW and the SOCK_DGRAM socket types. By default, a SOCK_DGRAM socket is opened. However, unfortunately, some netlink server programs do make such a distinction and require the use of SOCK_RAW for what is nominally a datagram socket. The --raw option causes netlink-datagram-socket-listen to open a SOCK_RAW socket, for the benefits of those programs.

Usage

netlink-datagram-socket-listen can be used as a simple dæmon monitored by service-manager(1). netlink-datagram-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).

See also

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

listeners for other protocols

Author

Jonathan de Boyne Pollard