ksgi

1
.Dd $Mdocdate$
2
.Dt KFCGI 8
3
.Os
4
.Sh NAME
5
.Nm kfcgi
6
.Nd FastCGI server for kcgi applications
7
.\" .Sh LIBRARY
8
.\" For sections 2, 3, and 9 only.
9
.\" Not used in OpenBSD.
10
.Sh SYNOPSIS
11
.Nm kfcgi
12
.Op Fl drv
13
.Op Fl l Ar backlog
14
.Op Fl n Ar workers
15
.Op Fl N Ar maxworkers
16
.Op Fl p Ar chroot
17
.Op Fl s Ar sockpath
18
.Op Fl u Ar sockuser
19
.Op Fl U Ar procuser
20
.Op Fl w Ar waittime
21
.Ar prog Op arg0...
22
.Sh DESCRIPTION
23
The
24
.Nm
25
server starts up
26
.Ar workers
27
processes of
28
.Ar prog
29
to handle FastCGI connections.
30
It can handle any FastCGI worker implementing the FastCGI v1.0
31
Specification as well as those implementing the FastCGI Extensions for
32
Management Control (see
33
.Fl r ,
34
.Fl N ,
35
and
36
.Fl w ) .
37
.Pp
38
By default, it opens the socket
39
.Pa /var/www/run/httpd.sock
40
in mode 0660 under the current user and group, changes to a file-system
41
jail in
42
.Pa /var/www ,
43
daemonises and opens its system log,
44
then starts 3 workers executing
45
.Ar prog ,
46
which must exist relative to the file-system jail root.
47
The back-log is twice the worker pool size
48
.Pq Fl n
49
or, in the event of variable-sized pools, twice the maximum worker size
50
.Pq Fl N .
51
.Pp
52
The arguments are as follows:
53
.Bl -tag -width Ds
54
.It Fl d
55
Do not daemonise and, in addition to syslog, print messages to standard
56
error.
57
.It Fl v
58
Be more verbose in output.
59
This can produce a
60
.Em lot
61
of output.
62
.It Fl l Ar backlog
63
The connection backlog.
64
If this is too small, connections will be refused and cause the request
65
to error out.
66
The operating system will usually truncate this.
67
.It Fl n Ar workers
68
The initial number of workers >1.
69
.It Fl N Ar maxworkers
70
The maximum number of workers in a variable-sized pool.
71
By default, this is twice
72
.Fl n .
73
.It Fl p Ar chroot
74
Location of file-system jail.
75
This is mandatory: use the root directory if you insist on being
76
insecure.
77
.It Fl r
78
Use a variable-sized pool of workers.
79
This can
80
.Em only
81
be used for workers implementing the FastCGI Extensions for Management
82
Control.
83
The pool will be at least (and initially) size
84
.Fl n ,
85
maximum size
86
.Fl N
87
with a release policy dictated by
88
.Fl w .
89
.It Fl s Ar sockpath
90
Alternative socket path.
91
.It Fl u Ar sockuser
92
The user in whose name (user and group) the socket is created.
93
.It Fl U Ar procuser
94
The user in whose name the process is dropped.
95
.It Fl w Ar waittime
96
The amount of time in seconds a worker must be idle before being
97
released from a variable-sized pool.
98
By default, this is five minutes.
99
.El
100
.Pp
101
To properly stop a
102
.Nm
103
server, send it a
104
.Dv SIGTERM .
105
If you send a
106
.Dv SIGHUP
107
to the process, it will restart all workers.
108
.\" .Sh CONTEXT
109
.\" For section 9 functions only.
110
.\" .Sh IMPLEMENTATION NOTES
111
.\" Not used in OpenBSD.
112
.\" .Sh RETURN VALUES
113
.\" For sections 2, 3, and 9 function return values only.
114
.\" .Sh ENVIRONMENT
115
.\" For sections 1, 6, 7, and 8 only.
116
.\" .Sh FILES
117
.Sh EXIT STATUS
118
.Ex -std
119
.\" For sections 1, 6, and 8 only.
120
.Sh EXAMPLES
121
On OpenBSD, the default user for the web server is
122
.Dq www .
123
Assuming we have a server that doesn't need any files, we can run the
124
following to keep it in a safe jail:
125
.Pp
126
.D1 # kfcgi -u www -U www -- /fcgi-bin/prog
127
.Pp
128
This will execute
129
.Pa /fcgi-bin/prog
130
within the default file-system jail of
131
.Pa /var/www
132
as user
133
.Dq www .
134
It will create the default socket
135
.Pa /var/www/run/httpd.sock
136
in mode 0660 as user
137
.Dq www .
138
.Pp
139
This can also be extended to run a variable-sized pool of workers that
140
responds to system load.
141
.Pp
142
.D1 # kfcgi -r -n 2 -N 100 -w 10 -u www -U www -- /fcgi-bin/prog
143
.Pp
144
This will start with only two servers, but scale it to 100 in the event
145
of a burst of communication.
146
Workers started to handle the burst will be terminated after 10 seconds.
147
.\" .Sh DIAGNOSTICS
148
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
149
.\" .Sh ERRORS
150
.\" For sections 2, 3, 4, and 9 errno settings only.
151
.Sh SEE ALSO
152
.Xr kcgi 3
153
.Sh STANDARDS
154
.Nm
155
implements the
156
.Dq FastCGI Specification ,
157
version 1.0, published 29 April 1996, for properly passing connections
158
to the workers.
159
It also implements the
160
.Lk https://kristaps.bsd.lv/kcgi/extending01.html "FastCGI Extensions for Management Control"
161
for variable-sized worker pools.
162
.\" .Sh HISTORY
163
.\" .Sh AUTHORS
164
.\" .Sh CAVEATS
165
.\" .Sh BUGS
166
.\" .Sh SECURITY CONSIDERATIONS
167
.\" Not used in OpenBSD.
168