doc/outdated/configuration.txt

   1 ==================
   2 Configuration File
   3 ==================
   4
   5 ------------
   6 Module: core
   7 ------------
   8
   9 :Author: Jan Kneschke
  10 :Date: $Date$
  11 :Revision: $Revision$
  12
  13 :abstract:
  14   the layout of the configuration file
  15
  16 .. meta::
  17   :keywords: lighttpd, configuration
  18
  19 .. contents:: Table of Contents
  20
  21 Description
  22 ===========
  23
  24 Basic Syntax
  25 ------------
  26
  27 A BNF like notation: ::
  28
  29   option   : NAME = VALUE
  30   merge    : NAME += VALUE
  31   NAME     : modulename.key
  32   VALUE    : ( <string> | <integer> | <boolean> | <array> | VALUE [ + VALUE ]*)
  33   <string> : "text"
  34   <integer>: digit*
  35   <boolean>: ( "enable" | "disable" )
  36   <array>  : "(" [ <string> "=>" ] <value> [, [ <string> "=>" ] <value> ]* ")"
  37   INCLUDE  : "include" VALUE
  38   INCLUDE_SHELL : "include_shell" STRING_VALUE
  39
  40 Example
  41 -------
  42
  43 ::
  44
  45   # default document-root
  46   server.document-root = "/var/www/example.org/pages/"
  47
  48   # TCP port
  49   server.port = 80
  50
  51   # selecting modules
  52   server.modules = ( "mod_access", "mod_rewrite" )
  53
  54   # variables, computed when config is read.
  55   var.mymodule = "foo"
  56   server.modules += ( "mod_" + var.mymodule )
  57   # var.PID is initialised to the pid of lighttpd before config is parsed
  58
  59   # include, relative to dirname of main config file
  60   include "mime.types.conf"
  61
  62   # read configuration from output of a command
  63   include_shell "/usr/local/bin/confmimetype /etc/mime.types"
  64
  65
  66 Conditional Configuration
  67 =========================
  68
  69 Most options can be configured conditionally by using the following syntax
  70 (including nesting).
  71
  72 ::
  73
  74   <field> <operator> <value> {
  75     ...
  76     <field> <operator> <value> {
  77       ... nesting: match only when parent match
  78     }
  79   }
  80   else <field> <operator> <value> {
  81     ... the "else if" block
  82   }
  83
  84 where <field> is one of one of the following:
  85
  86 $HTTP["cookie"]
  87   match on cookie
  88 $HTTP["scheme"]
  89   match on scheme
  90 $HTTP["host"]
  91   match on host
  92 $HTTP["useragent"]
  93 $HTTP["user-agent"]
  94   match on useragent
  95 $HTTP["referer"]
  96   match on referer
  97 $HTTP["method"]
  98   math on the http method
  99 $HTTP["url"]
 100   match on url
 101 $HTTP["query-string"]
 102   match on the (not decoded) query-string
 103 $HTTP["remoteip"]
 104 $HTTP["remote-ip"]
 105   match on the remote IP or a remote Network
 106 $HTTP["language"]
 107   match on the Accept-Language header
 108 $SERVER["socket"]
 109   match on socket. Value must be on the format "ip:port" where ip is an IP
 110   address and port a port number. Only equal match (==) is supported.
 111   It also binds the daemon to this socket. Use this if you want to do IP/port-
 112   based virtual hosts.
 113
 114 <operator> is one of:
 115
 116 ==
 117   string equal match
 118 !=
 119   string not equal match
 120 =~
 121   perl style regular expression match
 122 !~
 123   perl style regular expression not match
 124
 125 and <value> is either a quoted ("") literal string or regular expression.
 126
 127
 128 Example
 129 -------
 130
 131 ::
 132
 133   # disable directory-listings for /download/*
 134   dir-listing.activate = "enable"
 135   $HTTP["url"] =~ "^/download/" {
 136     dir-listing.activate = "disable"
 137   }
 138
 139   # handish virtual hosting
 140   # map all domains of a top-level-domain to a single document-root
 141   $HTTP["host"] =~ "(^|\.)example\.org$" {
 142     server.document-root = "/var/www/htdocs/example.org/pages/"
 143   }
 144
 145   # multiple sockets
 146   $SERVER["socket"] == "127.0.0.1:81" {
 147     server.document-root = "..."
 148   }
 149
 150   $SERVER["socket"] == "127.0.0.1:443" {
 151     ssl.pemfile = "/var/www/certs/localhost.pem"
 152     ssl.engine = "enable"
 153
 154     server.document-root = "/var/www/htdocs/secure.example.org/pages/"
 155   }
 156
 157   # deny access for all googlebot
 158   $HTTP["useragent"] =~ "Google" {
 159     url.access-deny = ( "" )
 160   }
 161
 162   # deny access for all image stealers
 163   $HTTP["referer"] !~ "^($|http://www\.example\.org)" {
 164     url.access-deny = ( ".jpg", ".jpeg", ".png" )
 165   }
 166
 167   # deny the access to www.example.org to all user which
 168   # are not in the 10.0.0.0/8 network
 169   $HTTP["host"] == "www.example.org" {
 170     $HTTP["remoteip"] != "10.0.0.0/8" {
 171      url.access-deny = ( "" )
 172     }
 173   }
 174
 175 Using variables
 176 ===============
 177
 178 You can set your own variables in the configuration to simplify your config.
 179 ::
 180
 181   var.basedir = "/home/www/servers/"
 182   $HTTP["host"] == "www.example.org" {
 183      server.name = "www.example.org"
 184      include "incl-base.conf"
 185   }
 186
 187   in incl-base.conf:
 188   server.document-root = basedir + server.name + "/pages/"
 189   accesslog.filename   = basedir + server.name + "/logs/access.log"
 190
 191 You can also use environement variables or the default variables var.PID and
 192 var.CWD: ::
 193
 194   var.basedir = env.LIGHTTPDBASE
 195
 196   $HTTP["host"] == "www.example.org" {
 197      server.name = "www.example.org"
 198      include "incl-base.conf"
 199      include "incl-fastcgi.conf"
 200   }
 201
 202   in incl-fastcgi.conf:
 203   fastcgi.server = ( ... => ((
 204      "socket" => basedir + server.name + "/tmp/fastcgi-" + PID + ".sock"
 205   )) )
 206
 207 Or like the lighttpd script for rails does:
 208
 209   var.basedir = var.CWD
 210
 211   server.document-root = basedir + "/public/"
 212
 213 Global context
 214 ==============
 215
 216 ::
 217
 218   global {
 219     ...
 220   }
 221
 222 You don't need it in the main configuration file. But you might have
 223 difficulty setting server wide configuration inside a included-file from
 224 conditionals.
 225
 226 Example
 227 -------
 228
 229 ::
 230
 231   in lighttpd.conf:
 232   server.modules = ()
 233   $HTTP["host"] == "www.example.org" {
 234     include "incl-php.conf"
 235   }
 236
 237   in incl-php.conf:
 238   global {
 239     server.modules += ("mod_fastcgi")
 240     static-file.exclude-extensions += (".php")
 241   }
 242   fastcgi.server = "..."
 243
 244 Options
 245 =======
 246
 247 server module
 248 -------------
 249
 250 main sections
 251 `````````````
 252
 253 server.document-root
 254   document-root of the webserver
 255
 256   This variable has the specified as it will be used for all requests
 257   without a Host: header and for all with a know hostname which you
 258   might have specified with one of the above conditionals.
 259
 260   Default: no default, required
 261
 262 server.bind
 263   IP address, hostname or absolute path to the unix-domain socket the server
 264   listen on.
 265
 266   Default: bind to all interfaces
 267
 268   Example: ::
 269
 270     server.bind = "127.0.0.1"
 271     server.bind = "www.example.org"
 272     server.bind = "/tmp/lighttpd.socket"
 273
 274 server.port
 275   tcp-port to bind the server to
 276
 277 .. note:: port belows 1024 require root-permissions
 278
 279   Default: 80 (443 if ssl is enabled)
 280
 281 server.use-ipv6
 282   bind to the IPv6 socket
 283
 284 server.defer-accept
 285   set TCP_DEFER_ACCEPT to the specified value on the socket if the value is > 0
 286   and TCP_DEFER_ACCEPT is available on the platform (linux2.4+)
 287
 288   Default: 0
 289
 290 server.bsd-accept-filter
 291   set SO_ACCEPTFILTER on listen sockets (*BSD systems, e.g. FreeBSD)
 292   e.g. server.bsd-accept-filter = "httpready"
 293     or server.bsd-accept-filter = "dataready"
 294
 295   Default: ""   (none)
 296
 297 server.tag
 298   set the string returned by the Server: response header
 299
 300   Default: lighttpd <current-version>
 301
 302 server.errorlog
 303   pathname of the error-log
 304
 305   Default: either STDERR or ``server.errorlog-use-syslog``
 306
 307 server.errorlog-use-syslog
 308   send errorlog to syslog
 309
 310   Default: disabled
 311
 312 server.chroot
 313   root-directory of the server
 314
 315   NOTE: requires root-permissions
 316
 317 server.username
 318   username used to run the server
 319
 320   NOTE: requires root-permissions
 321
 322 server.groupname
 323   groupname used to run the server
 324
 325   NOTE: requires root-permissions
 326
 327 server.follow-symlink
 328   allow to follow-symlinks
 329
 330   Default: enabled
 331
 332 index-file.names
 333   list of files to search for if a directory is requested
 334   e.g.: ::
 335
 336     index-file.names          = ( "index.php", "index.html",
 337                                   "index.htm", "default.htm" )
 338
 339   if a name starts with slash this file will be used a index generator
 340   for all directories.
 341
 342 server.modules
 343   modules to load
 344
 345 .. note:: the order of the modules is important.
 346
 347   The modules are executed in the order as they are specified. Loading
 348   mod_auth AFTER mod_fastcgi might disable authentication for fastcgi
 349   backends (if check-local is disabled).
 350
 351   As auth should be done first, move it before all executing modules (like
 352   proxy, fastcgi, scgi and cgi).
 353
 354   rewrites, redirects and access should be first, followed by auth and
 355   the docroot plugins.
 356
 357   Afterwards the external handlers like fastcgi, cgi, scgi and proxy and
 358   at the bottom the post-processing plugins like mod_accesslog.
 359
 360   e.g.: ::
 361
 362     server.modules          = ( "mod_rewrite",
 363                                 "mod_redirect",
 364                                 "mod_alias",
 365                                 "mod_access",
 366                                 "mod_auth",
 367                                 "mod_authn_file",
 368                                 "mod_status",
 369                                 "mod_simple_vhost",
 370                                 "mod_evhost",
 371                                 "mod_userdir",
 372                                 "mod_secdownload",
 373                                 "mod_fastcgi",
 374                                 "mod_proxy",
 375                                 "mod_cgi",
 376                                 "mod_ssi",
 377                                 "mod_compress",
 378                                 "mod_usertrack",
 379                                 "mod_expire",
 380                                 "mod_rrdtool",
 381                                 "mod_accesslog" )
 382
 383   Starting with lighttpd 1.4.0 three default modules are loaded automaticly:
 384
 385   - mod_indexfile
 386   - mod_dirlisting
 387   - mod_staticfile
 388
 389 server.event-handler
 390   set the event handler
 391
 392   Default: "poll"
 393
 394 server.pid-file
 395   set the name of the .pid-file where the PID of the server should be placed.
 396   This option is used in combination with a start-script and the daemon mode
 397
 398   Default: not set
 399
 400 server.max-request-size
 401   maximum size in kbytes of the request (header + body). Only applies to POST
 402   requests.
 403
 404   Default: 2097152 (2GB)
 405
 406 server.max-worker
 407   number of worker processes to spawn. This is usually only needed on servers
 408   which are fairly loaded and the network handler calls delay often (e.g. new
 409   requests are not handled instantaneously).
 410
 411   Default: 0
 412
 413 server.name
 414   name of the server/virtual server
 415
 416   Default: hostname
 417
 418 server.max-keep-alive-requests
 419   maximum number of request within a keep-alive session before the server
 420   terminates the connection
 421
 422   Default: 128
 423
 424 server.max-keep-alive-idle
 425   maximum number of seconds until a idling keep-alive connection is droped
 426
 427   Default: 30
 428
 429 server.max-read-idle
 430   maximum number of seconds until a waiting, non keep-alive read times out
 431   and closes the connection
 432
 433   Default: 60
 434
 435 server.max-write-idle
 436   maximum number of seconds until a waiting write call times out and closes
 437   the connection
 438
 439   Default: 360
 440
 441 server.error-handler-404
 442   uri to call if the requested file results in a 404
 443
 444   Default: not set
 445
 446   Example: ::
 447
 448     server.error-handler-404 = "/error-404.php"
 449
 450 server.protocol-http11
 451   defines if HTTP/1.1 is allowed or not.
 452
 453   Default: enabled
 454
 455 server.range-requests
 456   defines if range requests are allowed or not.
 457
 458   Default: enabled
 459
 460
 461 SSL engine
 462 ``````````
 463
 464 ssl.pemfile
 465   path to the PEM file for SSL support
 466
 467 debugging
 468 `````````
 469
 470 debug.dump-unknown-headers
 471   enables listing of internally unhandled HTTP-headers
 472
 473   e.g. ::
 474
 475     debug.dump-unknown-headers = "enable"
 476
 477 mimetypes
 478 `````````
 479
 480 mimetype.assign
 481   list of known mimetype mappings
 482   NOTE: if no mapping is given "application/octet-stream" is used
 483
 484   e.g.: ::
 485
 486     mimetype.assign   = ( ".png"  => "image/png",
 487                           ".jpg"  => "image/jpeg",
 488                           ".jpeg" => "image/jpeg",
 489                           ".html" => "text/html",
 490                           ".txt"  => "text/plain" )
 491
 492   The list is compared top down and the first match is taken. This is
 493   important if you have matches like: ::
 494
 495                           ".tar.gz" => "application/x-tgz",
 496                           ".gz" => "application/x-gzip",
 497
 498   If you want to set another default mimetype use: ::
 499
 500                           ...,
 501                           "" => "text/plain" )
 502
 503   as the last entry in the list.
 504
 505 mimetype.use-xattr
 506   If available, use the XFS-style extended attribute interface to
 507   retrieve the "Content-Type" attribute on each file, and use that as the
 508   mime type. If it's not defined or not available, fall back to the
 509   mimetype.assign assignment.
 510
 511   e.g.: ::
 512
 513     mimetype.use-xattr = "enable"
 514
 515     on shell use:
 516
 517     $ attr -s Content-Type -V image/svg svgfile.svg
 518
 519     or
 520
 521     $ attr -s Content-Type -V text/html indexfile
 522
 523
 524 debugging
 525 `````````
 526
 527 debug.log-request-header
 528   default: disabled
 529
 530 debug.log-response-header
 531   default: disabled
 532
 533 debug.log-file-not-found
 534   default: disabled
 535
 536 debug.log-request-handling
 537   default: disabled
 538
 539 debug.log-ssl-noise
 540   default: disabled