psendfile: Fixed missing include.
[ashd.git] / 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)