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

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

:Author: Jan Kneschke
:Date: $Date: 2004/08/29 09:44:53 $
:Revision: $Revision: 1.2 $

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

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

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

A BNF like notation: ::

  option   : NAME = VARIABLE
  NAME     : modulename.key
  VARIABLE : ( <string> | <integer> | <boolean> | <array> )
  <string> : "text"
  <integer>: digit*
  <boolean>: ( "enable" | "disable" )
  <array>  : "(" [ <string> "=>" ] <variable> [, [ <string> "=>" ] <variable> ]* ")"
  
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"
 


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

Most of the options can be actived at a giving condition.

The basic syntax is ::

  <field> <cond> <match> {
    <options>
  }

with
  
- <field> is the header-field to check
- <cond> is ==, !=, =~ or !~ 
- <match> is either a plain string or a regex (depends on <cond>)
- <options> is one or many options from the configfile

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.pem-file = "/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" {
    access.deny = ""
  }
  
  # deny access for all image stealers
  $HTTP["referer"] !~ "^($|http://www\.example\.org)" {
    access.deny = ""
  }

Options
=======

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

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

server.document-root
  document-root of the webserver
  
server.bind
  hostname of the server
  
server.port
  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
  bind to the IPv6 socket
  
server.errorlog
  pathname of the error-log
  if nothing is specified STDERR is used
  
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 


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 is important
  
  e.g.: ::

    server.modules            = ( "mod_rewrite", 
			          "mod_access", 
			  	  "mod_auth", 
                                  "mod_status", 
				  "mod_fastcgi",
				  "mod_cgi",
				  "mod_compress",
				  "mod_accesslog" ) 
server.event-handler
  set the event handler (see Performance_)
  
  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) (see Performance_
  for more)
  
  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





.. _Performance: performance.html

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
