FreeBSD/Linux Kernel Cross Reference
sys/net/khttpd/

The Design and Implementation of the FreeBSD Operating System (Second Edition)

    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

FreeBSD/Linux Kernel Cross Reference sys/net/khttpd/

FreeBSD/Linux Kernel Cross Reference
sys/net/khttpd/