Commit | Line | Data |
---|---|---|
6ee8b6fa FT |
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) |