net/khttpd/README

   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