linux-old/net/khttpd/README
<<
>>
Prefs
   1=====
   2
   3kHTTPd  -  Kernel httpd accelerator
   4
   5(C) 1999 by Arjan van de Ven
   6Licensed under the terms of the GNU General Public License
   7
   8=====
   9
  10
  111. 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 
  19   or 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"
  25   operation.
  26   This can be done very efficiently from within the Linux-kernel, for example 
  27   the nfs (network file system) daemon performs a similar task and also runs 
  28   in the kernel.
  29
  30   By "accelerating" the simple case within the kernel, userspace daemons can
  31   do what they are very good at: Generating user-specific, dynamic content.
  32
  33   Note: This document sometimes uses "Apache" instead of "any webserver you
  34   ever might want to use", just for reasons of readability.
  35   
  36
  372. Quick Start  
  38--------------
  39
  40   1) compile and load the module
  41   2) configure the module in /proc/sys/net/khttpd if needed
  42   3) echo 1 > /proc/sys/net/khttpd/start
  43
  44   unloading:
  45 
  46   echo 1 > /proc/sys/net/khttpd/stop
  47   echo 1 > /proc/sys/net/khttpd/unload 
  48   sleep 2
  49   rmmod khttpd
  50   
  51
  52
  533. Configuration 
  54----------------
  55
  56   Modes of operation
  57   ==================
  58
  59
  60   There are two recommended modes of operation:
  61
  62   1) "Apache" is main webserver, kHTTPd is assistant
  63        clientport   -> 80
  64        serverport   -> 8080 (or whatever)
  65
  66   2) kHTTPd is main webserver, "Apache" is assistant
  67        clientport   -> 8080 (or whatever)
  68        serverport   -> 80
  69
  70   
  71   Configuring kHTTPd
  72   ==================
  73
  74   Before you can start using kHTTPd, you have to configure it. This
  75   is done through the /proc filesystem, and can thus be done from inside
  76   a script. Most parameters can only be set when kHTTPd is stopped.
  77
  78   The following things need configuration:
  79
  80   1) The port where kHTTPd should listen for requests
  81   2) The port (on "localhost") where "Apache" is listening
  82   3) The location of the documents (documentroot)
  83   4) The strings that indicate dynamic content (optional)
  84      [  "cgi-bin" is added by default ]
  85
  86   It is very important that the documentroot for kHTTPd matches the
  87   documentroot for the userspace-daemon, as kHTTPd might "redirect"
  88   any request to this userspace-daemon.
  89
  90   A typical script (for the first mode of operation) to do this would 
  91   look like:
  92
  93#!/bin/sh
  94modprobe khttpd
  95echo 80 > /proc/sys/net/khttpd/clientport
  96echo 8080 > /proc/sys/net/khttpd/serverport
  97echo /var/www > /proc/sys/net/khttpd/documentroot
  98echo php3 > /proc/sys/net/khttpd/dynamic
  99echo shtml > /proc/sys/net/khttpd/dynamic
 100echo 1 > /proc/sys/net/khttpd/start
 101
 102   For the second mode of operation, this would be:
 103
 104#!/bin/sh
 105modprobe khttpd
 106echo 8080 > /proc/sys/net/khttpd/clientport
 107echo 80 > /proc/sys/net/khttpd/serverport
 108echo /var/www > /proc/sys/net/khttpd/documentroot
 109echo php3 > /proc/sys/net/khttpd/dynamic
 110echo shtml > /proc/sys/net/khttpd/dynamic
 111echo 1 > /proc/sys/net/khttpd/start
 112
 113   In this case, you also have to change the configuration of the 
 114   userspace-daemon. For Apache, you do this by changing
 115
 116   Port 80
 117
 118   to 
 119
 120   Port 8080
 121
 122   Starting kHTTPd
 123   ===============
 124   Once you have set up the configuration, start kHTTPD by running
 125   echo 1 > /proc/sys/net/khttpd/start
 126   It may take a jiffie or two to start.
 127
 128   Stopping kHTTPd
 129   ===============
 130   To stop kHTTPd, do
 131   echo 1 > /proc/sys/net/khttpd/stop
 132   It should stop in a jiffy or two.
 133
 134   Unloading kHTTPd
 135   ===============
 136   To unload the module, do
 137   echo 1 > /proc/sys/net/khttpd/stop
 138   echo 1 > /proc/sys/net/khttpd/unload
 139   #killall -HUP khttpd
 140   sleep 2
 141   rmmod khttpd
 142
 143   If this doesn't work fast enough for you (unloading can wait for 
 144   a remote connection to close down), you can send the daemons a "HUP"
 145   signal after you told them to stop. This will cause the daemon-threads to
 146   stop immediately. 
 147   
 148
 1494. Permissions
 150--------------
 151   The security model of kHTTPd is very strict. It can be, since there is a 
 152   userspace daemon that can handle the complex exceptions. 
 153
 154   kHTTPd only serves a file if
 155
 156        1)  There is no "?" in the URL
 157        2)  The URL starts with a "/"
 158        3)  The file indicated by the URL exists
 159        4)  The file is world-readable (*)
 160        5)  The file is not a directory, executable or has the Sticky-bit
 161            set (*)
 162        6)  The URL doesn't contain any "forbidden" substrings such as ".."
 163            and "cgi-bin" (*)
 164        7)  The mime-type is known (*)
 165
 166   The items marked with a (*) are configurable through the
 167   sysctl-parameters in /proc/sys/net/khttpd.
 168
 169
 170   In all cases where any of the above conditions isn't met, the
 171   userspace-daemon is handed the request.
 172
 173
 174
 1755. Parameters
 176-------------
 177   The following parameters are settable through /proc/sys/net/khttpd:
 178 
 179        Name            Default         Description
 180
 181        serverport      8080            The port where kHTTPd listens on
 182
 183        clientport      80              The port of the userspace
 184                                        http-daemon
 185
 186        threads         2               The number of server-threads. Should
 187                                        be 1 per CPU for small websites, 2
 188                                        per CPU for big (the active files
 189                                        do not fit in the RAM) websites.
 190
 191        documentroot    /var/www        the directory where the
 192                                        document-files are
 193
 194        start           0               Set to 1 to start kHTTPd 
 195                                        (this also resets "stop" to 0)
 196
 197        stop            0               Set to 1 to stop kHTTPd
 198                                        (this also resets "start" to 0)
 199
 200        unload          0               Set to 1 to prepare kHTTPd for
 201                                        unloading of the module
 202
 203        sloppymime      0               If set to 1, unknown mime-types are
 204                                        set to text/html. If set to 0,
 205                                        files with unknown mime-types are
 206                                        handled by the userspace daemon
 207
 208        perm_required   S_IROTH         Minimum permissions required
 209                                        (for values see "man 2 stat")
 210        
 211        perm_forbid     dir+sticky+     Permission-mask with "forbidden"
 212                        execute         permissions.
 213                                        (for values see "man 2 stat")
 214
 215        dynamic         cgi-bin ..      Strings that, if they are a subset
 216                                        of the URL, indicate "dynamic
 217                                        content"
 218
 219        maxconnect      1000            Maximum number of concurrent
 220                                        connections
 221
 2226. Known Issues
 223   kHTTPd is *not* currently compatible with tmpfs.  Trying to serve
 224   files stored on a tmpfs partition is known to cause kernel oopses
 225   as of 2.4.18.  This is due to the same problem that prevents sendfile()
 226   from being usable with tmpfs.  A tmpfs patch is floating around that seems
 227   to fix this, but has not been released as of 27 May 2002.
 228   kHTTPD does work fine with ramfs, though.
 229
 230   There is debate about whether to remove kHTTPd from the main
 231   kernel sources.  This will probably happen in the 2.5 kernel series,
 232   after which khttpd will still be available as a patch.
 233
 234   The kHTTPd source code could use a good spring cleaning.
 235
 2367. More information
 237-------------------
 238   More information about the architecture of kHTTPd, the mailinglist and
 239   configuration-examples can be found at the kHTTPd homepage:
 240
 241        http://www.fenrus.demon.nl
 242
 243   Bugreports, patches, etc can be send to the mailinglist
 244   (khttpd-users@zgp.org) or to khttpd@fenrus.demon.nl
 245   Mailing list archives are at 
 246      http://lists.alt.org/mailman/listinfo/khttpd-users
 247
 248
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.