local-seqpacket-socket-accept 1 user commands nosh
local-seqpacket-socket-accept accept incoming local socket connections and spawn a program per connection
`local-seqpacket-socket-accept` --verbose --connection-limit number --localname pathname next-prog

## Description

`local-seqpacket-socket-accept` expects to inherit 1 or more sockets that have been set up to listen for incoming local socket connections, as done by local-seqpacket-socket-listen 1. It loops forever, accepting local socket connections and (for each such connection) spawning next-prog.

next-prog may contain its own command line options, which `local-seqpacket-socket-accept` will ignore.

If the --verbose option is used, `local-seqpacket-socket-accept` logs information about processes spawned and the current and maximum number of connections. The latter is set with the --connection-limit option, which defaults to 40. If it is reached, `local-seqpacket-socket-accept` stops accepting new connections until one or more child processes exit. `local-seqpacket-socket-accept` always limits the number of connections, and has no notion of an "unlimited" number of connections.

### Listening socket conventions

There are no UCSPI conventions for listening sockets before a connection has been accepted. `local-seqpacket-socket-accept` follows the systemd convention, falling back on a daemontools-like default.

If the `LISTEN_PID` environment variable is set, if its value is parseable as a (decimal) number, if that number is the process ID of the `local-seqpacket-socket-accept` process, if the `LISTEN_FDS` environment variable is set, and if its value is parseable as a (positive decimal) number n: then the listening sockets are taken to be file descriptors 3 up to but not including 3+n. (It is an error for there to be zero listening file descriptors.) Otherwise file descriptor 3 is taken unconditionally to be the single listening open file descriptor.

`local-seqpacket-socket-accept` unconditionally unsets the `LISTEN_PID`, `LISTEN_FDS`, and `LISTEN_FDNAMES` environment variables after it has determined what the open file descriptors to use are.

### UCSPI (specifically UCSPI-UNIX) conventions

next-prog is expected to follow the UCSPI conventions: its standard input and output are the connected socket, which it should treat as generic I/O streams and not expect to be a socket, and information about the local and remote ends of the connected socket is in environment variables.

In the child process, `local-seqpacket-socket-accept` closes all of the listening sockets. It obtains information about the local socket connection, using the `getpeername` 2, `getsockname` 2, and (if available) `SO_PEERCRED` option of the `getsockopt` 2 library functions, and sets up the conventional UCSPI-UNIX environment variables as follows:

`PROTO`

  This always has the value `UNIX`, indicating the prefix to the names of the remaining environment variables.

`UNIXLOCALPATH`

  The local (server) pathname of the socket. The pathname set by the --localname option forcibly overrides the information supplied by the library function.

`UNIXREMOTEPATH`

  The remote (client) pathname of the socket.

`UNIXREMOTEPID`

  The PID of the remote (client) process that connected.

`UNIXREMOTEEUID`

  The effective UID of the remote (client) process that connected.

`UNIXREMOTEEGID`

  The effective GID of the remote (client) process that connected.

## USAGE

`local-seqpacket-socket-accept` can be used

- as a "socket-activated" dæmon monitored by systemd 1 (with the systemd-recommended `Accept=false`),

- as a dæmon started by inetd 1 (with `wait` and as long as it is chained via `fdmove` 0 3), and

- as a simple dæmon chained from local-seqpacket-socket-listen 1 and monitored by service-manager 1.

Together, `local-seqpacket-socket-accept` and local-seqpacket-socket-listen 1 replace unixserver 1 from ucspi-unix.

To change the process' UID and GID after a successful call to accept 2, simply chain to setuidgid 1 or setuidgid-fromenv 1. This is, however, not usually necessary because unprivileged processes can accept any connections. It is preferable to chain `local-seqpacket-socket-accept` from setuidgid 1 or setuidgid-fromenv 1.

## Author

Jonathan de Boyne Pollard