NAME

       socket-activate - open sockets and exec a systemd-style socket-activated service

SYNOPSIS

       socket-activate [-v] [socketinfo ...]  [--] prog [args]

       where socketinfo is of the form:

       --family:[option=value,...]:address

       See EXAMPLES below.

DESCRIPTION

       The  socket-activate  program  opens  the  requested  sockets  and then waits for incoming
       activity on them.  When this happens, it  execs  prog,  which  inherits  these  open  file
       descriptors.   The  first  requested  socket  will  be  opened  on  file descriptor 3, and
       subsequent ones follow in order.

       If -v or --verbose is present, socket-activate will write details of what it is  doing  to
       stderr before it execs prog.

       prog is the first argument that does not start with a -, or the first argument after a --.

SOCKET FAMILIES

       family can be one of several different values.

       For  the  following values of family, if address is a single decimal number, it is treated
       as a port number and socket-activate will bind to all available addresses  on  that  port.
       If  address contains a /, the part before the / is interpreted as a network address of the
       requested family, and the part after the / is treated as a port number.

       • tcp: TCP on IPv4 and/or IPv6

       • udp: UDP on IPv4 and/or IPv6

       For the following values of family, address is interpreted as a filesystem path.

       • unix: Unix-domain streaming socket

       • unix-dgram: Unix-domain datagram socket

SOCKET OPTIONS

       Each socketinfo can have 0 or  more  options  appended  to  it,  separated  by  the  comma
       character (,) with their value appended after an equals sign (=).

       Available options are:

       • label: simple text string to identify this socket to the inheriting process

       • backlog: For streaming sockets (tcp and unix), the maximum queue for pending connections
         (see listen(2) – defaults to SOMAXCONN).

       • mode: octal mode for Unix-domain socket (defaults to relying on umask(2))

       • user: a numeric User ID value for Unix-domain socket ownership

       • group: a numeric Group ID value for Unix-domain socket ownership

EXIT CODES

       socket-activate exits 100 when called  with  unparseable  options.   It  prints  an  error
       message  to  stderr  and  exits  11  if  it  cannot successfully bind all of the requested
       sockets.  It prints an error message to stderr and exits with the value of errno if it  is
       unable  to  exec(3) the intended process.  Otherwise, its exit code is the same as that of
       prog.

ENVIRONMENT VARIABLES

       socket-activate stores the number of opened file descriptors in the  environment  variable
       $LISTEN_FDS,  sets $LISTEN_PID to getpid(2), and stores the list of colon-separated labels
       in $LISTEN_FDNAMES.

       These  environment  variables  follow  the  convention  understood  by   libsystemd   (see
       sd_listen_fds(3))  so  it  should  be usable with any socket-activated daemon that expects
       this behavior.

EXAMPLES

       Run a webserver as a non-privileged user, using privileged ports, and  indicating  to  the
       webserver which ports should offer HTTPS:

              socket-activate --tcp::80 --tcp:label=tls:443 -- \
               runuser -u httpd -- \
                webserver

       Expose a foregrounded (supervised) pulseaudio daemon to the network:

              socket-activate --tcp:backlog=5:1000 -- \
               pulseaudio --daemonize=no

       Run a network daemon only on the IPv4 loopback:

              socket-activate --tcp::127.0.0.1/9999 -- \
               network-daemon

       Run a network daemon over a unix-domain socket instead of IP:

              socket-activate --unix::/srv/network-access -- \
               network-daemon

       Run  a  public-facing  network  daemon  with a local socket for the local administrator to
       control it:

              socket-activate --tcp::443 --unix:label=control,user=1000,mode=0600:/run/xyz/control -- \
               xyzd

SEE ALSO

       exec(3), listen(2), runuser(1), sd_listen_fds(3), umask(2)

AUTHOR

       Mark Hindley ⟨mark@hindley.org.uk⟩

       Originally written for (socket-activate)[https://gitlab.com/dkg/socket-activate] by Daniel
       Kahn Gillmor ⟨dkg@fifthhorseman.net⟩