Project

General

Profile

Docs Configuration » History » Revision 34

Revision 33 (heavyhttpd, 2009-01-10 13:39) → Revision 34/49 (heavyhttpd, 2009-01-11 04:12)

h1. Configuration file for the core module. 

 h2. BNF like notation of the basic syntax 

 <pre> 
   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 
 </pre> 


 *Example* 

 <pre> 
  
   # 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 initialised 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" 

 </pre> 

 h2. Conditional Configuration 

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

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

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

 |_.Field name|_.Description| 
 |$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. If there are nested blocks, this must be the most inner block.| 
 |$HTTP["querystring"]|match on querystring, eg, after the ? in this type url: index.php?module=images..| 
 |$HTTP["remoteip"]|match on the remote IP or a remote Network (Warning: doesn't work with IPv6 enabled)| 
 |$HTTP["scheme"]|(Introduced in version 1.4.19) match on the scheme used by the incoming connection.    This is either "http" or "https".| 
 |$SERVER["socket"]|match on socket. Value must be on the format "ip:port", where ip is an IP address(optional) and port a port number. Only equal match (==) is supported. It also binds the daemon to this socket. Use this if you want to do IP/port-based virtual hosts.| 
 |$PHYSICAL["path"]|(Introduced in version 1.5.0) - match on the mapped physical path of the file / cgi script to be served.| 
 |$PHYSICAL["existing-path"]|(Introduced in version 1.5.0) - match on the mapped physical path of the file / cgi script to be served only if such a file exists on the local filesystem.| 


 <operator> is one of: 

 |_.Operator|_.Value| 
 |==|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:* 

 <pre> 

   # disable directory-listings for /download/* 
   dir-listing.activate = "enable" 
   $HTTP["url"] =~ "^/download/" { 
     dir-listing.activate = "disable" 
   } 
  
   # handle virtual hosting 
   # map all domains of a top-level-domain 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 (anti-hotlinking for images) 
   $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 = ( "" ) 
     } 
   } 

   # Allow only 200.19.1.5 and 210.45.2.7 to 
   # have access to www.example.org/admin/ 
   $HTTP["host"] == "www.example.org" { 
     #!~ is a perl style regular expression not match 
     $HTTP["remoteip"] !~ "^(200\.19\.1\.5|210\.45\.2\.7)$" { 
       $HTTP["url"] =~ "^/admin/" { 
         url.access-deny = ( "" ) 
       } 
     } 
   } 

 </pre> 

 h2. Troubleshooting 


 If you're not running on the default port, $HTTP["host"] will have the port appended to it, so regular expressions ending in $ (without allowing for a port) won't match.  
 To match with or without a port, change <pre>"(^|\\.)example\\.org$"</pre> to <pre>"(^|\\.)example\\.org(\\:[0-9]*)?$"</pre> 

 Note that some earlier versions of lighttpd do not support the full configuration file syntax listed here.    In particular, some versions do not support "var." variables, appending with "+=", nested conditionals, or "else" blocks.    The names of some options (for example, "server.dir-listing") have also changed (i.e. to "dir-listing.activate") between versions of lighttpd. 

 If you're having trouble configuring lighttpd, consider using the "-t" or "-p" options to debug your configuration. Note that some earlier versions of lighttpd not support the "-t" or "-p" options. 

 h2. Advanced usage 

 Check the blog: http://blog.lighttpd.net/articles/2005/05/07/advanced-configuration-in-up-upcoming-1-4-x 

 h2. Using variables 

 You can set your own variables in the configuration to simplify your config. 

 <pre> 

   var.basedir = "/home/www/servers/" 
   $HTTP["host"] == "www.example.org" { 
      server.name = "www.example.org" 
      include "incl-base.conf" 
   } 

 </pre> 

 In incl-base.conf: 

 <pre> 

   server.document-root = basedir + server.name + "/pages/" 
   accesslog.filename     = basedir + server.name + "/logs/access.log" 

 </pre> 
   
 You can also use environment variables or the default variables var.PID and var.CWD: 

 <pre> 

   var.basedir = env.LIGHTTPDBASE 

   $HTTP["host"] == "www.example.org" { 
      server.name = "www.example.org" 
      include "incl-base.conf" 
      include "incl-fastcgi.conf" 
   } 

 </pre> 

 In incl-fastcgi.conf: 

 <pre> 

   fastcgi.server = ( ... => (( 
      "socket" => basedir + server.name + "/tmp/fastcgi-" + PID + ".sock" 
   )) ) 

 </pre> 

 Or like the lighttpd script for rails does: 

 <pre> 

   var.basedir = var.CWD 
   server.document-root = basedir + "/public/" 

 </pre> 


 Some useful things that can NOT be done in lighttpd config (you need to create a script in a real programming language and than use include_shell): 

 <pre> 

   # testing if a variable has been set is NOT possible 
   var.not_sure_if_it_exists == undefined { ... set to default value ... } 

   # removing from arrays is NOT possible 
   server.modules -= ( "mod_idontwantyou" ) 

 </pre> 

 h2. Using Pattern Substitutions 

 If you use a regex conditional such as: 

 <pre> 
 $HTTP["host"] =~ "^([^.]+)\.([^.]+)\.example\.com(:[0-9]+)?$" { 
   accesslog.filename = "/var/log/www/%1.%2.example.com/access.log" 
 } 
 </pre> 

 Parenthesized subexpressions from the conditional regex can be substituted using patterns begining with "%".    %1 is replaced with the first subexpression, %2 with the second, etc.    %0 is replaced by the entire substring matching the regexp.    So if, for example, $HTTP["host"] is "foo.bar.example.com:8080" 

 <pre> 
 %1 would be "foo" 
 %2 would be "bar" 
 %3 would be "8080" 
 %0 would be "foo.bar.example.com:8080" 
 acesslog.filename would be "/var/log/www/foo.bar.example.com/access.log" 
 </pre> 

 h2. Global context 

 <pre> 

   global { 
     ... 
   } 

 </pre> 

 You don't need it in the main configuration file.  
 But you might have difficulty setting a server wide configuration inside a included-file from conditionals. 

 *Example* 

 In lighttpd.conf: 

 <pre> 

   server.modules = () 
   $HTTP["host"] == "www.example.org" { 
     include "incl-php.conf" 
   } 

 </pre> 

 In incl-php.conf: 

 <pre> 

   global { 
     server.modules += ("mod_fastcgi") 
     static-file.exclude-extensions += (".php") 
   } 
   fastcgi.server = "..." 

 </pre> 

 h2. Options 

 All Configuration Options can be found at: http://trac.lighttpd.net/trac/wiki/Docs%3AConfigurationOptions