local-stream-socket-listen — create a socket listening for incoming AF_LOCAL stream connections and chain
local-stream-socket-listen
[--backlog number
] [--uid number
] [--gid number
] [--mode number
] [--pass-credentials] [--pass-security] [--upstart-compatibility] [--systemd-compatibility] {path
} {next-prog
}
local-stream-socket-listen is a chain-loading utility that opens a local domain stream socket bound to path
, 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 local-stream-socket-listen will ignore.
The --backlog option specifies the allowed backlog level (defaulting to 5) of outstanding not-yet-accepted connections to the socket.
After binding the socket to path
, local-stream-socket-listen changes the owner UID of the socket to that specified with the --uid command line argument (if supplied), changes the GID of the socket to that specified with the --gid command line argument (if supplied), and changes the permissions of the socket to those specified with the --mode command line argument (if supplied).
The normal conventions for numbers apply, so for octal permissions use a leading zero.
Symbolic permissions and account names are not supported.
The --pass-credentials option causes local-stream-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 local-stream-socket-listen to set the UPSTART_FDS
environment variable to 3, and the UPSTART_EVENTS
environment variable to socket
.
This is for compatibility with daemons that expect to be run under upstart(1).
The --systemd-compatibility option is for compatibility with daemons that expect to be run under systemd(1).
It causes local-stream-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 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).
Because of an oversight in operating systems that prevents
fchmod(2)
and
fchown(2)
from working with bound local domain sockets, local-stream-socket-listen calls
chmod(2)
and
chown(2)
on path
.
Because of an oversight in operating systems that prevents
bind(2)
from being able to re-use old local domain socket addresses,
local-stream-socket-listen attempts to delete, with
unlink(2),
any file named path
before binding.
An attacker who could change what file is denoted by
path
in between the calls to
bind(2)
and the call to
chmod(2)
and
chown(2)
could change the permissions and ownership of any file in the filesystem.
An attacker who could change what file is denoted by
path
before the call to
unlink(2)
could unlink any file in the filesystem.
To avoid these security holes, ensure that none of the directories in the path to path
(not just the final one) are writable by untrusted users or groups; and ensure that untrusted programs cannot supply path
.
local-stream-socket-listen can be used as a simple daemon monitored by
service-manager(1)
that chains to
local-stream-socket-accept(1).
Together, the two replace
unixserver(1)
from ucspi-unix.
local-stream-socket-listen overlaps the functionality of
inetd(1)
and
systemd(1),
with which only the
local-stream-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).