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
  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
  37 2. 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
  53 3. 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
  94 modprobe khttpd
  95 echo 80 > /proc/sys/net/khttpd/clientport
  96 echo 8080 > /proc/sys/net/khttpd/serverport
  97 echo /var/www > /proc/sys/net/khttpd/documentroot
  98 echo php3 > /proc/sys/net/khttpd/dynamic
  99 echo shtml > /proc/sys/net/khttpd/dynamic
 100 echo 1 > /proc/sys/net/khttpd/start
 101
 102    For the second mode of operation, this would be:
 103
 104 #!/bin/sh
 105 modprobe khttpd
 106 echo 8080 > /proc/sys/net/khttpd/clientport
 107 echo 80 > /proc/sys/net/khttpd/serverport
 108 echo /var/www > /proc/sys/net/khttpd/documentroot
 109 echo php3 > /proc/sys/net/khttpd/dynamic
 110 echo shtml > /proc/sys/net/khttpd/dynamic
 111 echo 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
 149 4. 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
 175 5. 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
 222 6. 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
 236 7. 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