1 =====
2
3 kHTTPd - Kernel httpd accelerator
4
5 (C) 1999 by Arjan van de Ven
6 Licensed under the terms of the GNU General Public License
7
8 =====
9
10
11 1. Introduction
12 ---------------
13 kHTTPd is a http-daemon (webserver) for Linux. kHTTPd is different from
14 other webservers in that it runs from within the Linux-kernel as a module
15 (device-driver).
16
17 kHTTPd handles only static (file based) web-pages, and passes all requests
18 for non-static information to a regular userspace-webserver such as Apache or
19 Zeus. The userspace-daemon doesn't have to be altered in any way.
20
21 Static web-pages are not a very complex thing to serve, but these are very
22 important nevertheless, since virtually all images are static, and a large
23 portion of the html-pages are static also. A "regular" webserver has little
24 added value for static pages, it is simply a "copy file to network"-operation.
25 This can be done very efficiently from within the Linux-kernel, for example
26 the nfs (network file system) daemon performs a similar task and also runs
27 in the kernel.
28
29 By "accelerating" the simple case within the kernel, userspace daemons can
30 do what they are very good at: Generating user-specific, dynamic content.
31
32 Note: This document sometimes uses "Apache" instead of "any webserver you
33 ever might want to use", just for reasons of readability.
34
35
36 2. Quick Start
37 --------------
38
39 1) compile and load the module
40 2) configure the module in /proc/sys/net/khttpd if needed
41 3) echo 1 > /proc/sys/net/khttpd/start
42
43 unloading:
44
45 echo 1 > /proc/sys/net/khttpd/stop
46 echo 1 > /proc/sys/net/khttpd/unload
47 rmmod khttpd
48
49
50
51 3. Configuration
52 ----------------
53
54 Modes of operation
55 ==================
56
57
58 There are two recommended modes of operation:
59
60 1) "Apache" is main webserver, kHTTPd is assistant
61 clientport -> 80
62 serverport -> 8080 (or whatever)
63
64 2) kHTTPd is main webserver, "Apache" is assistant
65 clientport -> 8080 (or whatever)
66 serverport -> 80
67
68
69 Configuring kHTTPd
70 ==================
71
72 Before you can start using kHTTPd, you have to configure it. This
73 is done through the /proc filesystem, and can thus be done from inside
74 a script. Most parameters can only be set when kHTTPd is not active.
75
76 The following things need configuration:
77
78 1) The port where kHTTPd should listen for requests
79 2) The port (on "localhost") where "Apache" is listening
80 3) The location of the documents (documentroot)
81 4) The strings that indicate dynamic content (optional)
82 [ "cgi-bin" is added by default ]
83
84 It is very important that the documentroot for kHTTPd matches the
85 documentroot for the userspace-daemon, as kHTTPd might "redirect"
86 any request to this userspace-daemon.
87
88 A typical script (for the first mode of operation) to do this would
89 look like:
90
91 #!/bin/sh
92 modprobe khttpd
93 echo 80 > /proc/sys/net/khttpd/clientport
94 echo 8080 > /proc/sys/net/khttpd/serverport
95 echo /var/www > /proc/sys/net/khttpd/documentroot
96 echo php3 > /proc/sys/net/khttpd/dynamic
97 echo shtml > /proc/sys/net/khttpd/dynamic
98 echo 1 > /proc/sys/net/khttpd/start
99
100 For the second mode of operation, this would be:
101
102 #!/bin/sh
103 modprobe khttpd
104 echo 8080 > /proc/sys/net/khttpd/clientport
105 echo 80 > /proc/sys/net/khttpd/serverport
106 echo /var/www > /proc/sys/net/khttpd/documentroot
107 echo php3 > /proc/sys/net/khttpd/dynamic
108 echo shtml > /proc/sys/net/khttpd/dynamic
109 echo 1 > /proc/sys/net/khttpd/start
110
111 In this case, you also have to change the configuration of the
112 userspace-daemon. For Apache, you do this by changing
113
114 Port 80
115
116 to
117
118 Port 8080
119
120
121
122 Stopping kHTTPd
123 ===============
124 In order to change the configuration, you should stop kHTTPd by typing
125 echo 1 > /proc/sys/net/khttpd/stop
126 on a command-prompt.
127
128 If you want to unload the module, you should type
129 echo 1 > /proc/sys/net/khttpd/unload
130 after stopping kHTTPd first.
131
132 If this doesn't work fast enough for you (the commands above can wait for
133 a remote connection to close down), you can send the daemons a "HUP"
134 signal after you told them to stop. This will cause the daemon-threads to
135 stop immediately.
136
137 Note that the daemons will restart immediately if they are not told to
138 stop.
139
140
141
142 4. Permissions
143 --------------
144 The security model of kHTTPd is very strict. It can be, since there is a
145 userspace daemon that can handle the complex exceptions.
146
147 kHTTPd only serves a file if
148
149 1) There is no "?" in the URL
150 2) The URL starts with a "/"
151 3) The file indicated by the URL exists
152 4) The file is world-readable (*)
153 5) The file is not a directory, executable or has the Sticky-bit
154 set (*)
155 6) The URL doesn't contain any "forbidden" substrings such as ".."
156 and "cgi-bin" (*)
157 7) The mime-type is known (*)
158
159 The items marked with a (*) are configurable through the
160 sysctl-parameters in /proc/sys/net/khttpd.
161
162
163 In all cases where any of the above conditions isn't met, the
164 userspace-daemon is handed the request.
165
166
167
168 5. Parameters
169 -------------
170 The following parameters are settable through /proc/sys/net/khttpd:
171
172 Name Default Description
173
174 serverport 8080 The port where kHTTPd listens on
175
176 clientport 80 The port of the userspace
177 http-daemon
178
179 threads 2 The number of server-threads. Should
180 be 1 per CPU for small websites, 2
181 per CPU for big (the active files
182 do not fit in the RAM) websites.
183
184 documentroot /var/www the directory where the
185 document-files are
186
187 start 0 Set to 1 to start kHTTPd
188 (this also resets "stop" to 0)
189
190 stop 0 Set to 1 to stop kHTTPd
191 (this also resets "start" to 0)
192
193 unload 0 Set to 1 to prepare kHTTPd for
194 unloading of the module
195
196 sloppymime 0 If set to 1, unknown mime-types are
197 set to text/html. If set to 0,
198 files with unknown mime-types are
199 handled by the userspace daemon
200
201 perm_required S_IROTH Minimum permissions required
202 (for values see "man 2 stat")
203
204 perm_forbid dir+sticky+ Permission-mask with "forbidden"
205 execute permissions.
206 (for values see "man 2 stat")
207
208 dynamic cgi-bin .. Strings that, if they are a subset
209 of the URL, indicate "dynamic
210 content"
211
212 maxconnect 1000 Maximum number of concurrent
213 connections
214
215 6. More information
216 -------------------
217 More information about the architecture of kHTTPd, the mailinglist and
218 configuration-examples can be found at the kHTTPd homepage:
219
220 http://www.fenrus.demon.nl
221
222 Bugreports, patches, etc can be send to the mailinglist
223 (khttpd-users@zgp.org) or to khttpd@fenrus.demon.nl
224
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.
