
$Id: $

README - small lighttpd manual

additional docs:

- doc/fastcgi.txt
- doc/authentification.txt
- INSTALL

Description:
============

lighttpd a secure, fast, compliant and very flexible web-server 
which has been optimized for high-performance environments. It has a very
low memory footprint compared to other webservers and takes care of cpu-load.
Its advanced feature-set (FastCGI, CGI, Auth, Output-Compression,
URL-Rewriting and many more) make lighttpd the perfect webserver-software
for every server that is suffering load problems.

the naming:
-----------
lighttpd is a *httpd* which is 
- fast as *light*ing and 
- *light* if it comes to memory consumtion and system requirement

Features:
---------

Network:
- IPv4, IPv6

Protocols:
- HTTP/1.0 (http://www.ietf.org/rfc/rfc1945.txt)
- HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt)
- HTTPS (provided by openssl)
- CGI/1.1 (http://CGI-Spec.Golux.Com/)
- FastCGI (http://www.fastcgi.com/devkit/doc/fcgi-spec.html)

Advanced Features:
- load-balanced FastCGI
  (one webserver distibutes request to multiple PHP-servers via FastCGI)
- custom errorpages (for Response-Code 400-599)
- virtual hosts 
- directory listings
- streaming CGI and FastCGI
- URL-Rewritung
- HTTP-Redirects
- output-compression with transparent caching

FastCGI-Support:
- parses the Response-header and completes the HTTP-header accordingly
- Keep-Alive handling based on Content-Length header

PHP-Support:
- same speed as or faster than apache + mod_php4
- handles various PHP bugs in the FastCGI SAPI
- includes a utility to spawn FastCGI processes (neccesary for PHP 4.3.x)

Security features:
- chroot(), set UID, set GID
- protecting docroot

HTTP/1.1 features:
- Ranges (start-end, start-, -end, multiple ranges)
- HTTP/1.0 Keep-Alive + HTTP/1.1 persistent Connections
- methods: GET, HEAD, POST
- Last-Modified + If-Modified handling 
- sends Content-Length if possible
- sends Transfer-Encoding: chunk, if Content-Length is not possible
- sends Content-Type
- on-the-fly output compression (deflate, gzip)
- authentification: basic and digest
  (http://www.ietf.org/rfc/rfc2617.txt)

HTTP/1.1 compliance:
- Sends 206 for Range Requests
- Sends 304 for If-Modified Requests
- Sends 400 for missing Host on HTTP/1.1 requests
- Sends 400 for broken Request-Line
- Sends 411 for missing Content-Length on POST requests
- Sends 416 for "out-of-range" on Range: Header
- Sends 501 for request-method != (GET|POST|HEAD)
- Sends 505 for protocol != HTTP/1.0 or HTTP/1.1
- Sends Date: on every requests 

Intended Audience:
------------------
- Ad-Server Front-Ends ("Banner-Schleuder")
  - delivering small files rapidly
- php-servers under high load
  (load-balancing the php-request over multiple PHP-servers)

Works with:
-----------

It has been tested to work with
- IE 6.0
- Mozilla 1.x
- Konqueror 3.1 
  (for Keep-Alive/Persistent Connections, Accept-Encoding for PHP + gzip)
- wget 
  (for Resuming)
- acrobat plugin
  (for multiple ranges)
  
  
Works on:
---------

lighttpd has been verified to compile and work on

Linux, FreeBSD, NetBSD, Solaris 8 + 9, Windows (Cygwin), IRIX

missing for HTTP/1.1 compliance:
--------------------------------
- parsing chunked POST request






Starting lighttpd:
==================

As deamon in the background:

$ lighttpd -f <configfile>

or without detaching from the console:

$ lighttpd -D -f <configfile>


Configuration:
==============

- basic syntax

  <name>           = <variable>
  
  <name> is module-name + dot + key
  e.g.:
    server.host
  
  <variable> is one of 
    <string>, <integer>, <boolean>, <array>
    
  <string> is a string of characters covered in double quotes:
  e.g.:
    "www.example.org"
    
  <integer> is a integer in range of 0 to 65535:
  e.g.:
    80
  
  <boolean> is used to enable or disable features and can have two values:
    "enable" or "disable"
    default is "disable"
    
  <array> is a complex type of all the previous named types:
  e.g.: a plain array
    ( "string", "string" ) 
  or various custom array-types like
    ( "key" => ( "string", integer ), 
      "string", 
      integer )

  
  every <name> field is only allowed once. 
  
  HINT:
  
  Use 
  
  e.g. url.rewrite = ( "foo" => "bar", "foo2" => "bar2" ) 
  
  if you have to use a <name> twice. (that's why we have arrays.)


server module
-------------

- main sections

server.virtual-root          STRING
  sets the root directory for the virtual-hosting support
  
server.virtual-default-host  STRING
  hostname to use if the provided hostname doesn't exists locally
  
server.virtual-docroot       STRING
  relative path to the document-root 
  
server.docroot               STRING
  document-root if virtual-hosting is not used

server.host                  STRING
  hostname of the server
  
server.port                  INTEGER
  tcp-port to bind the server to
  if nothing is specified port 80 is used
  NOTE: port belows 1024 require root-permissions
  
server.use-ipv6              BOOLEAN
  bind to the IPv6 socket
  
server.errorlog              STRING
  pathname of the error-log
  if nothing is specified STDERR is used
  
server.errorfile-prefix      STRING   [might change, don't use]
  path-prefix for the error files 
  
server.chroot                STRING
  see "Using Change-Root"
  
server.userid                STRING
server.groupid               STRING
  username and groupname used to run the server
  NOTE: requires root-permissions

server.dir-listing           BOOLEAN
  enables virtual directory listings if a directory is requested no
  index-file was found 


server.indexfiles            ARRAY
  list of files to search for if a directory is requested
  
  e.g.:
  server.indexfiles           = ( "index.php", "index.html", 
                                  "index.htm", "default.htm" )
  
server.modules               ARRAY
  modules to load
  NOTE: the order is important
  
  e.g.:
  server.modules              = ( "mod_rewrite", 
			          "mod_access", 
			  	  "mod_auth", 
                                  "mod_status", 
				  "mod_fastcgi",
				  "mod_cgi",
				  "mod_compress",
				  "mod_accesslog" ) 


- SSL engine

ssl.pemfile                  STRING
  path to the PEM file for SSL support

- debugging

debug.dump-unknown-headers   BOOLEAN
  enables listing of internally unhandled HTTP-headers

- mimetypes

mimetype.assign              ARRAY
  list of known mimetype mappings
  NOTE: if no mapping is given "application/octet-stream" is used
  
  e.g.:
  mimetype.assign             = ( ".png"  => "image/png", 
                                  ".jpg"  => "image/jpeg",
                                  ".jpeg" => "image/jpeg",
				  ".html" => "text/html",
  				  ".txt"  => "text/plain" )


CGI Module
----------

cgi.assign                   ARRAY

  file-extensions that are handled by a CGI program

  e.g.:
  cgi.assign                  = ( ".pl"  => "/usr/bin/perl",
                                  ".cgi" => "/usr/bin/perl" )

FastCGI Module
--------------

fastcgi.server               custom-ARRAY

  structure of custom-ARRAY:
    ( <extension> => 
      ( <handle> => 
        ( "host" => <string> ),
	( "port" => <integer> )
      ), 
      ( <handle> => ... 
      )
    )
    
  <extension> is the file-extension
  <handle>    is just a unique handle name
  "host"      is hostname/ip of the FastCGI process
  "port"      is tcp-port on the "host" used by the FastCGI process

  e.g.:
  fastcgi.server              = ( ".php" =>
 				  ( "grisu" => 
				    ( 
				      "host" => "192.168.2.10",
				      "port" => 1026
				    )
				  )
			        )



Compression Module
------------------

compress.cache-dir           STRING
  name of the directory where compressed content will be cached


compress.filetype            ARRAY
  mimetypes where might get compressed
  
  e.g.:
  compress.filetype           = ("text/plain", "text/html")


Rewrite Module
--------------

url.rewrite                  ARRAY
  rewrites a set of URLs interally in the webserver BEFORE they are handled.
  
  e.g.
  
  url.rewrite = ( "^/show/([0-9]+)/([0-9]+)$" => "/show.php?isdn=$1&page$2",
                  "^/get/([0-9]+)/([0-9]+)$"  => "/get.php?isdn=$1&page$2" )


Using Change-Root
=================

  - chroot to /home/www/
  - docroot at /servers/<hostname>/pages/
  - defaulthost www.example.org
  
  e.g. (external view)
  /home/www/servers/www.example.org/pages/index.html
  
  (in chroot)
  /servers/www.example.org/pages/index.html
  
  config:
  
  server.chroot  = "/home/www/"
  server.userid  = "wwwrun"
  server.groupid = "nogroup"
  
  server.document-root = "/servers/"
  
  The FastCGI process is living outside this chroot definition as it is 
  started seperatly.


Log-Cycling
===========

  sending HUP to lighttpd will close and re-open the logfiles. this is used
  for cycling logfiles.

#! /bin/sh

###
#
# a simple logfile rotator for lighttpd
#

DATE=`date +"%Y%m%d-%H%M"`
LPID=`pidof lighttpd`
mv access.log access.log.${DATE}
kill -HUP ${LPID}
gzip access.log.${DATE}

