path: root/doc/configuration.txt

=================
Configuation File
=================

------------
Module: core
------------

:Author: Jan Kneschke
:Date: $Date$
:Revision: $Revision$

:abstract:
  the layout of the configuration file
  
.. meta::
  :keywords: lighttpd, configuration
  
.. contents:: Table of Contents

Description
===========

Basic Syntax
------------

A BNF like notation: ::

  option   : NAME = VALUE
  merge    : NAME += VALUE
  NAME     : modulename.key
  VALUE    : ( <string> | <integer> | <boolean> | <array> | VALUE [ + VALUE ]*)
  <string> : "text"
  <integer>: digit*
  <boolean>: ( "enable" | "disable" )
  <array>  : "(" [ <string> "=>" ] <value> [, [ <string> "=>" ] <value> ]* ")"
  INCLUDE  : "include" VALUE
  INCLUDE_SHELL : "include_shell" STRING_VALUE
  
Example
-------

::
  
  # default document-root
  server.document-root = "/var/www/example.org/pages/"
  
  # TCP port
  server.port = 80
  
  # selecting modules
  server.modules = ( "mod_access", "mod_rewrite" )
  
  # enable directory listings
  server.dir-listing = "enable"

  # variables, computed when config is read.
  var.mymodule = "foo"
  server.modules += ( "mod_" + var.mymodule )

  # include, relative to dirname of main config file
  include "mime.types.conf"

  # read configuration from output of a command
  include_shell "/usr/local/bin/confmimetype /etc/mime.types"


Conditional Configuration
=========================

Most options can be configured conditionally by using the following syntax
(including nesting).

::

  <field> <operator> <value> {
    ...
    <field> <operator> <value> {
      ... nesting: match only when parent match
    }
  }
  else <field> <operator> <value> {
    ... the "else if" block
  }

where <field> is one of one of the following:

$HTTP["cookie"]
  match on cookie
$HTTP["host"]
  match on host
$HTTP["useragent"]
  match on useragent
$HTTP["referer"]
  match on referer
$HTTP["url"]
  match on url
$SERVER["socket"]
  match on socket.  Value must be on the format "$ip:$port" where $ip is an IP
  address and $port a port number.  Only equal match (==) is supported.
  It also binds to this socket.

<operator> is one of:

==
  string equal match
!=
  string not equal match
=~
  perl style regular expression match
!~
  perl style regular expression not match

and <value> is either a quoted ("") literal string or regular expression.


Example
-------

::

  # disable directory-listings for /download/*
  server.dir-listing = "enable"
  $HTTP["url"] =~ "^/download/" {
    server.dir-listing = "disable"
  }
  
  # handish virtual hosting
  # map all subdomains to a single document-root
  $HTTP["host"] =~ "\.example\.org$" {
    server.document-root = "/var/www/htdocs/example.org/pages/"
  }
  
  # multiple sockets
  $SERVER["socket"] == "127.0.0.1:81" {
    server.document-root = "..."
  }
  
  $SERVER["socket"] == "127.0.0.1:443" {
    ssl.pemfile = "/var/www/certs/localhost.pem"
    ssl.engine = "enable"
    
    server.document-root = "/var/www/htdocs/secure.example.org/pages/"
  }

  # deny access for all googlebot
  $HTTP["useragent"] =~ "Google" {
    url.access-deny = ( "" )
  }
  
  # deny access for all image stealers
  $HTTP["referer"] !~ "^($|http://www\.example\.org)" {
    url.access-deny = ( ".jpg", ".jpeg", ".png" )
  }

Options
=======

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

main sections
`````````````

server.document-root
  document-root of the webserver

  This variable has the specified as it will be used for all requests
  without a Host: header and for all with a know hostname which you
  might have specified with one of the above conditionals.

  Default: no default, required
  
server.bind
  hostname of the server
  
  Default: bind to all interfaces
  
server.port
  tcp-port to bind the server to
  
  NOTE: port belows 1024 require root-permissions
  
  Default: 80 (443 if ssl is enabled)
  
server.use-ipv6
  bind to the IPv6 socket
  
server.errorlog
  pathname of the error-log
  
  Default: either STDERR or ``server.errorlog-use-syslog``
  
server.errorlog-use-syslog
  send errorlog to syslog
  
  Default: disabled
  
server.chroot
  root-directory of the server
  
server.username
  username used to run the server
  
  NOTE: requires root-permissions

server.groupname
  groupname used to run the server
  
  NOTE: requires root-permissions

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

dir-listing.hide-dotfiles
  if enabled, does not list hidden files in directory listings generated
  by the dir-listing option.

  Default: enabled

dir-listing.external-css
  path to an external css stylesheet for the directory listing

dir-listing.exclude
  list of regular expressions.  Files that match any of the specified regular
  expressions will be excluded from directory listings.

server.follow-symlink
  allow to follow-symlinks
  
  Default: enabled

server.indexfiles
  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
  modules to load
  
.. note:: the order of the modules is somewhat important as the modules are
        handled in the way they are specified. mod_rewrite should always be
        the first module, mod_accesslog always the last.
  
  e.g.: ::

    server.modules          = ( "mod_rewrite", 
                                "mod_redirect", 
				"mod_alias",
			        "mod_access", 
				"mod_auth", 
                                "mod_status", 
				"mod_fastcgi",
				"mod_proxy",
				"mod_simple_vhost",
				"mod_evhost",
				"mod_userdir",
				"mod_cgi",
				"mod_compress",
                                "mod_ssi",
                                "mod_usertrack",
				"mod_expire",
				"mod_secdownload",
 				"mod_rrdtool",
				"mod_accesslog" )

server.event-handler
  set the event handler 
  
  Default: "poll"

server.pid-file
  set the name of the .pid-file where the PID of the server should be placed. 
  This option is used in combination with a start-script and the deamon mode
  
  Default: not set
  
server.max-request-size
  maximum size in kbytes of the request (header + body) 
  
  Default: 2Gb

server.max-worker
  number of worker processes to spawn (works but has no benefit)
  
  Default: 0
  
server.name
  name of the server/virtual server
  
  Default: hostname

server.max-keep-alive-requests
  maximum number of request within a keep-alive session before the server 
  terminates the connection
  
  Default: 128

server.max-keep-alive-idle
  maximum number of seconds until a idling keep-alive connection is droped
  
  Default: 30

server.max-read-idle
  maximum number of seconds until a waiting, non keep-alive read times out 
  and closes the connection
  
  Default: 60

server.max-write-idle
  maximum number of seconds until a waiting write call times out and closes
  the connection
  
  Default: 360

server.error-handler-404
  uri to call if the requested file results in a 404

  Default: not set
  
  Example: ::
    
    server.error-handler-404 = "/error-404.php"

server.protocol-http11
  defines if HTTP/1.1 is allowed or not.
  
  Default: enabled

server.range-requests
  defines if range requests are allowed or not.
  
  Default: enabled


SSL engine
``````````

ssl.pemfile
  path to the PEM file for SSL support

debugging
`````````

debug.dump-unknown-headers
  enables listing of internally unhandled HTTP-headers
  
  e.g. ::
    
    debug.dump-unknown-headers = "enable"

mimetypes
`````````

mimetype.assign
  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" )


mimetype.use-xattr
  If available, use the XFS-style extended attribute interface to
  retrieve the "Content-Type" attribute on each file, and use that as the
  mime type. If it's not defined or not available, fall back to the
  mimetype.assign assignment.
  
  e.g.: ::
  
    mimetype.use-xattr = "enable"
  
    on shell use:
    
    $ attr -s Content-Type -V image/svg svgfile.svg
    
    or
	    
    $ attr -s Content-Type -V text/html indexfile


debugging
`````````

debug.log-request-header

  default: disabled 
  
debug.log-response-header

  default: disabled 

debug.log-file-not-found

  default: disabled 

debug.log-request-handler

  default: disabled