diff options
Diffstat (limited to 'doc/configuration.txt')
| -rw-r--r-- | doc/configuration.txt | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/doc/configuration.txt b/doc/configuration.txt new file mode 100644 index 0000000..106b008 --- /dev/null +++ b/doc/configuration.txt @@ -0,0 +1,436 @@ +================== +Configuration File +================== + +------------ +Module: core +------------ + +:Author: Jan Kneschke +:Date: $Date: 2005-11-11 13:43:16 +0100 (Fri, 11 Nov 2005) $ +:Revision: $Revision: 835 $ + +: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" ) + + # variables, computed when config is read. + var.mymodule = "foo" + server.modules += ( "mod_" + var.mymodule ) + var.PID is initized to the pid of lighttpd before config is parsed + + # 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 +$HTTP["remoteip"] + match on the remote IP or a remote Network +$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/* + dir-listing.activate = "enable" + $HTTP["url"] =~ "^/download/" { + dir-listing.activate = "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" ) + } + + # deny the access to www.example.org to all user which + # are not in the 10.0.0.0/8 network + $HTTP["host"] == "www.example.org" { + $HTTP["remoteip"] != "10.0.0.0/8" { + url.access-deny = ( "" ) + } + } + +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 + +dir-listing.activate + 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 + +index-file.names + list of files to search for if a directory is requested + e.g.: :: + + index-file.names = ( "index.php", "index.html", + "index.htm", "default.htm" ) + + if a name starts with slash this file will be used a index generator + for all directories. + +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" ) + + Starting with lighttpd 1.4.0 three default modules are loaded automaticly: + + - mod_indexfiles + - mod_dirlisting + - mod_staticfile + +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" ) + + The list is compared top down and the first match is taken. This is + important if you have matches like: :: + + ".tar.gz" => "application/x-tgz", + ".gz" => "application/x-gzip", + + If you want to set another default mimetype use: :: + + ..., + "" => "text/plain" ) + + as the last entry in the list. + +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-handling + + default: disabled |