diff options
author | Ralf Baechle <ralf@linux-mips.org> | 1999-10-09 00:00:47 +0000 |
---|---|---|
committer | Ralf Baechle <ralf@linux-mips.org> | 1999-10-09 00:00:47 +0000 |
commit | d6434e1042f3b0a6dfe1b1f615af369486f9b1fa (patch) | |
tree | e2be02f33984c48ec019c654051d27964e42c441 /net/khttpd/README | |
parent | 609d1e803baf519487233b765eb487f9ec227a18 (diff) |
Merge with 2.3.19.
Diffstat (limited to 'net/khttpd/README')
-rw-r--r-- | net/khttpd/README | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/net/khttpd/README b/net/khttpd/README new file mode 100644 index 000000000..57d974051 --- /dev/null +++ b/net/khttpd/README @@ -0,0 +1,235 @@ +===== + +kHTTPd - Kernel httpd accelerator + +(C) 1999 by Arjan van de Ven +Licensed under the terms of the GNU General Public License + +===== + + +1. Introduction +--------------- + kHTTPd is a http-daemon (webserver) for Linux. kHTTPd is different from + other webservers in that it runs from within the Linux-kernel as a module + (device-driver). + + kHTTPd handles only static (file based) web-pages, and passes all requests + for non-static information to a regular userspace-webserver such as Apache or + Zeus. The userspace-daemon doesn't have to be altered in any way. + + Static web-pages are not a very complex thing to serve, but these are very + important nevertheless, since virtually all images are static, and a large + portion of the html-pages are static also. A "regular" webserver has little + added value for static pages, it is simply a "copy file to network"-operation. + This can be done very efficiently from within the Linux-kernel, for example + the nfs (network file system) daemon performs a similar task and also runs + in the kernel. + + By "accelerating" the simple case within the kernel, userspace daemons can + do what they are very good at: Generating user-specific, dynamic content. + + Note: This document sometimes uses "Apache" instead of "any webserver you + ever might want to use", just for reasons of readability. + + +2. Quick Start +-------------- + + 1) compile and load the module + 2) configure the module in /proc/sys/net/khttpd if needed + 3) echo 1 > /proc/sys/net/khttpd/start + + unloading: + + echo 1 > /proc/sys/net/khttpd/stop + echo 1 > /proc/sys/net/khttpd/unload + rmmod khttpd + + + +3. Configuration +---------------- + + Modes of operation + ================== + + + There are two recommended modes of operation: + + 1) "Apache" is main webserver, kHTTPd is assistant + clientport -> 80 + serverport -> 8080 (or whatever) + + 2) kHTTPd is main webserver, "Apache" is assistant + clientport -> 8080 (or whatever) + serverport -> 80 + + + Configuring kHTTPd + ================== + + Before you can start using kHTTPd, you have to configure it. This + is done through the /proc filesystem, and can thus be done from inside + a script. Most parameters can only be set when kHTTPd is not active. + + The following things need configuration: + + 1) The port where kHTTPd should listen for requests + 2) The port (on "localhost") where "Apache" is listening + 3) The location of the documents (documentroot) + 4) The strings that indicate dynamic content (optional) + [ "cgi-bin" is added by default ] + + It is very important that the documentroot for kHTTPd matches the + documentroot for the userspace-daemon, as kHTTPd might "redirect" + any request to this userspace-daemon. + + A typical script (for the first mode of operation) to do this would + look like: + +#!/bin/sh +modprobe khttpd +echo 80 > /proc/sys/net/khttpd/clientport +echo 8080 > /proc/sys/net/khttpd/serverport +echo /var/www > /proc/sys/net/khttpd/documentroot +echo php3 > /proc/sys/net/khttpd/dynamic +echo shtml > /proc/sys/net/khttpd/dynamic +echo 1 > /proc/sys/net/khttpd/start + + For the second mode of operation, this would be: + +#!/bin/sh +modprobe khttpd +echo 8080 > /proc/sys/net/khttpd/clientport +echo 80 > /proc/sys/net/khttpd/serverport +echo /var/www > /proc/sys/net/khttpd/documentroot +echo php3 > /proc/sys/net/khttpd/dynamic +echo shtml > /proc/sys/net/khttpd/dynamic +echo 1 > /proc/sys/net/khttpd/start + + In this case, you also have to change the configuration of the + userspace-daemon. For Apache, you do this by changing + + Port 80 + + to + + Port 8080 + + in /etc/apache/httpd.conf. For security-reasons, you can also change + + BindAddress * + + to + + BindAddress 127.0.0.1 + + (in the same file) to prevent outside users from accessing Apache + directly. + + + + Stopping kHTTPd + =============== + In order to change the configuration, you should stop kHTTPd by typing + echo 1 > /proc/sys/net/khttpd/stop + on a command-prompt. + + If you want to unload the module, you should type + echo 1 > /proc/sys/net/khttpd/unload + after stopping kHTTPd first. + + If this doesn't work fast enough for you (the commands above can wait for + a remote connection to close down), you can send the daemons a "HUP" + signal after you told them to stop. This will cause the daemon-threads to + stop immediately. + + Note that the daemons will restart immediately if they are not told to + stop. + + + +4. Permissions +-------------- + The security model of kHTTPd is very strict. It can be, since there is a + userspace daemon that can handle the complex exceptions. + + kHTTPd only serves a file if + + 1) There is no "?" in the URL + 2) The URL starts with a "/" + 3) The file indicated by the URL exists + 4) The file is world-readable (*) + 5) The file is not a directory, executable or has the Sticky-bit + set (*) + 6) The URL doesn't contain any "forbidden" substrings such as ".." + and "cgi-bin" (*) + 7) The mime-type is known (*) + + The items marked with a (*) are configurable through the + sysctl-parameters in /proc/sys/net/khttpd. + + + In all cases where any of the above conditions isn't met, the + userspace-daemon is handed the request. + + + +5. Parameters +------------- + The following parameters are settable through /proc/sys/net/khttpd: + + Name Default Description + + serverport 8080 The port where kHTTPd listens on + + clientport 80 The port of the userspace + http-daemon + + threads 2 The number of server-threads. Should + be 1 per CPU for small websites, 2 + per CPU for big (the active files + do not fit in the RAM) websites. + + documentroot /var/www the directory where the + document-files are + + start 0 Set to 1 to start kHTTPd + (this also resets "stop" to 0) + + stop 0 Set to 1 to stop kHTTPd + (this also resets "start" to 0) + + unload 0 Set to 1 to prepare kHTTPd for + unloading of the module + + sloppymime 0 If set to 1, unknown mime-types are + set to text/html. If set to 0, + files with unknown mime-types are + handled by the userspace daemon + + perm_required S_IROTH Minimum permissions required + (for values see "man 2 stat") + + perm_forbid dir+sticky+ Permission-mask with "forbidden" + execute permissions. + (for values see "man 2 stat") + + dynamic cgi-bin .. Strings that, if they are a subset + of the URL, indicate "dynamic + content" + + maxconnect 1000 Maximum number of concurrent + connections + +6. More information +------------------- + More information about the architecture of kHTTPd, the mailinglist and + configuration-examples can be found at the kHTTPd homepage: + + http://www.fenrus.demon.nl + + Bugreports, patches, etc can be send to the mailinglist + (khttpd-users@zgp.org) or to khttpd@fenrus.demon.nl + |