patch-2.3.14 linux/net/khttpd/README

• Lines: 236
• Date: Wed Aug 18 09:45:10 1999
• Orig file: v2.3.13/linux/net/khttpd/README
• Orig date: Wed Dec 31 16:00:00 1969

diff -u --recursive --new-file v2.3.13/linux/net/khttpd/README linux/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
+