| 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) |