doc/callscgi.doc

   1 callscgi(1)
   2 ===========
   3
   4 NAME
   5 ----
   6 callscgi - SCGI request handler for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *callscgi* [*-h*] [*-N* 'RETRIES'] [*-i* 'ID'] [*-u* 'UNIXPATH'] [*-t* \[HOST:]'TCPPORT'] ['PROGRAM' ['ARGS'...]]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *callscgi* handler uses SCGI to call an external handler for
  16 requests. *callscgi* is a persistent handler, as defined in *ashd*(7).
  17
  18 Depending on which arguments are given, *callscgi* will run in one of
  19 four operating modes.
  20
  21 If an address option is given (see OPTIONS below), but the 'PROGRAM'
  22 argument is not given, *callscgi* will run in client mode. In client
  23 mode, *callscgi* will try to connect to a SCGI server listening to the
  24 given address. If it cannot connect, it will exit, except when failing
  25 only once, in which case it will retry according to the *-N* option,
  26 described below.
  27
  28 If no address option is given, but the 'PROGRAM' argument is given,
  29 *callscgi* will run in anonymous mode. In anonymous mode, *callscgi*
  30 will create a Unix socket listening on some more-or-less random
  31 address, and start the given 'PROGRAM', passing the listening socket
  32 on its standard input, expecting the program to start accepting
  33 connections on that socket. *callscgi* will then connect to that
  34 socket for each request. If such a connection is refused, the child
  35 program will be assumed to have crashed, and *callscgi* will restart
  36 it. Also in anonymous mode, *callscgi*, will try and kill the child
  37 program whenever *callscgi* itself exits for whatever reason (commonly
  38 because its own control socket is closed by its parent handler).
  39
  40 If both an address option and the 'PROGRAM' argument are given, but
  41 the *-N* option is not given, *callscgi* will run in launching
  42 mode. In launching mode, *callscgi* will try to connect to a SCGI
  43 server at the given address, but if (and only if) that fails, it will
  44 create a socket listening to the given address, and start the given
  45 'PROGRAM', passing the listening socket on its standard input,
  46 expecting the program to start accepting connections on that
  47 socket. Unlike in anonymous mode, *callscgi* will leave any child
  48 process it has started running even when *callscgi* itself exits.
  49
  50 If both an address option, the 'PROGRAM' argument and the *-N* option
  51 are given, *callscgi* will run in mixed mode. In mixed mode,
  52 *callscgi* will try to connect to a SCGI server at the given address,
  53 but if that fails, it will start the given 'PROGRAM'. Unlike in
  54 launching mode, however, *callscgi* will not create the listening
  55 socket itself, but will assume that the 'PROGRAM' will create it
  56 independently (probably based on any 'ARGS' passed to it). When
  57 'PROGRAM' is launched, *callscgi* will try to connect to the given
  58 address once per second, up to 'RETRIES' times. If the connection
  59 cannot succeed even after 'RETRIES' attempts, *callscgi* will exit.
  60
  61 OPTIONS
  62 -------
  63
  64 *-h*::
  65
  66         Print a brief help message to standard output and exit.
  67
  68 *-u* 'UNIXPATH'::
  69
  70         Use 'UNIXPATH' as the Unix socket address of the SCGI server.
  71
  72 *-t* \[HOST:]'TCPPORT'::
  73
  74         Use the given TCP/IP address as the SCGI server address. If
  75         'HOST' is not given, use `localhost` instead. 'TCPPORT' may be
  76         given symbolically.
  77
  78 *-i* 'ID'::
  79
  80         Use 'ID' to create a reasonably unique pathname to use as the
  81         Unix socket address of the SCGI server. This option is mainly
  82         intended for use as a convenience in launching mode, where the
  83         SCGI server does not need to know the actual address it is
  84         listening to (since it gets passed the listening socket on
  85         standard input) to start SCGI servers that can persist even if
  86         *callscgi* exits for some reason.
  87
  88 *-N* 'RETRIES'::
  89
  90         In client mode and mixed mode, try to connect 'RETRIES' times,
  91         once per second, to the SCGI server before giving up. If both
  92         an address option and the 'PROGRAM' argument are given, the
  93         presence of the *-N* option determines whether to run in
  94         launching mode or mixed mode, as described above.
  95
  96 SIGNALS
  97 -------
  98
  99 SIGINT, SIGTERM::
 100
 101         Exit cleanly, sending SIGTERM to any child process started if
 102         running in anonymous mode, as described above.
 103
 104 AUTHOR
 105 ------
 106 Fredrik Tolf <fredrik@dolda2000.com>
 107
 108 SEE ALSO
 109 --------
 110 *ashd*(7)