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_status",
 368                                 "mod_simple_vhost",
 369                                 "mod_evhost",
 370                                 "mod_userdir",
 371                                 "mod_secdownload",
 372                                 "mod_fastcgi",
 373                                 "mod_proxy",
 374                                 "mod_cgi",
 375                                 "mod_ssi",
 376                                 "mod_compress",
 377                                 "mod_usertrack",
 378                                 "mod_expire",
 379                                 "mod_rrdtool",
 380                                 "mod_accesslog" )
 381
 382   Starting with lighttpd 1.4.0 three default modules are loaded automaticly:
 383
 384   - mod_indexfile
 385   - mod_dirlisting
 386   - mod_staticfile
 387
 388 server.event-handler
 389   set the event handler
 390
 391   Default: "poll"
 392
 393 server.pid-file
 394   set the name of the .pid-file where the PID of the server should be placed.
 395   This option is used in combination with a start-script and the daemon mode
 396
 397   Default: not set
 398
 399 server.max-request-size
 400   maximum size in kbytes of the request (header + body). Only applies to POST
 401   requests.
 402
 403   Default: 2097152 (2GB)
 404
 405 server.max-worker
 406   number of worker processes to spawn. This is usually only needed on servers
 407   which are fairly loaded and the network handler calls delay often (e.g. new
 408   requests are not handled instantaneously).
 409
 410   Default: 0
 411
 412 server.name
 413   name of the server/virtual server
 414
 415   Default: hostname
 416
 417 server.max-keep-alive-requests
 418   maximum number of request within a keep-alive session before the server
 419   terminates the connection
 420
 421   Default: 128
 422
 423 server.max-keep-alive-idle
 424   maximum number of seconds until a idling keep-alive connection is droped
 425
 426   Default: 30
 427
 428 server.max-read-idle
 429   maximum number of seconds until a waiting, non keep-alive read times out
 430   and closes the connection
 431
 432   Default: 60
 433
 434 server.max-write-idle
 435   maximum number of seconds until a waiting write call times out and closes
 436   the connection
 437
 438   Default: 360
 439
 440 server.error-handler-404
 441   uri to call if the requested file results in a 404
 442
 443   Default: not set
 444
 445   Example: ::
 446
 447     server.error-handler-404 = "/error-404.php"
 448
 449 server.protocol-http11
 450   defines if HTTP/1.1 is allowed or not.
 451
 452   Default: enabled
 453
 454 server.range-requests
 455   defines if range requests are allowed or not.
 456
 457   Default: enabled
 458
 459
 460 SSL engine
 461 ``````````
 462
 463 ssl.pemfile
 464   path to the PEM file for SSL support
 465
 466 debugging
 467 `````````
 468
 469 debug.dump-unknown-headers
 470   enables listing of internally unhandled HTTP-headers
 471
 472   e.g. ::
 473
 474     debug.dump-unknown-headers = "enable"
 475
 476 mimetypes
 477 `````````
 478
 479 mimetype.assign
 480   list of known mimetype mappings
 481   NOTE: if no mapping is given "application/octet-stream" is used
 482
 483   e.g.: ::
 484
 485     mimetype.assign   = ( ".png"  => "image/png",
 486                           ".jpg"  => "image/jpeg",
 487                           ".jpeg" => "image/jpeg",
 488                           ".html" => "text/html",
 489                           ".txt"  => "text/plain" )
 490
 491   The list is compared top down and the first match is taken. This is
 492   important if you have matches like: ::
 493
 494                           ".tar.gz" => "application/x-tgz",
 495                           ".gz" => "application/x-gzip",
 496
 497   If you want to set another default mimetype use: ::
 498
 499                           ...,
 500                           "" => "text/plain" )
 501
 502   as the last entry in the list.
 503
 504 mimetype.use-xattr
 505   If available, use the XFS-style extended attribute interface to
 506   retrieve the "Content-Type" attribute on each file, and use that as the
 507   mime type. If it's not defined or not available, fall back to the
 508   mimetype.assign assignment.
 509
 510   e.g.: ::
 511
 512     mimetype.use-xattr = "enable"
 513
 514     on shell use:
 515
 516     $ attr -s Content-Type -V image/svg svgfile.svg
 517
 518     or
 519
 520     $ attr -s Content-Type -V text/html indexfile
 521
 522
 523 debugging
 524 `````````
 525
 526 debug.log-request-header
 527   default: disabled
 528
 529 debug.log-response-header
 530   default: disabled
 531
 532 debug.log-file-not-found
 533   default: disabled
 534
 535 debug.log-request-handling
 536   default: disabled
 537
 538 debug.log-ssl-noise
 539   default: disabled