diff options
Diffstat (limited to 'doc')
36 files changed, 576 insertions, 1010 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 792ff22..47ca576 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -35,8 +35,7 @@ trigger_b4_dl.txt \ webdav.txt \ expire.txt \ dirlisting.txt \ -evhost.txt \ -magnet.txt +evhost.txt HTMLDOCS=accesslog.html \ authentication.html \ @@ -72,8 +71,7 @@ HTMLDOCS=accesslog.html \ webdav.html \ expire.html \ dirlisting.html \ - evhost.html \ - magnet.html + evhost.html EXTRA_DIST=lighttpd.conf lighttpd.user \ rc.lighttpd rc.lighttpd.redhat sysconfig.lighttpd \ @@ -83,7 +81,7 @@ EXTRA_DIST=lighttpd.conf lighttpd.user \ newstyle.css \ oldstyle.css \ $(DOCS) - + %.html: %.txt rst2html $^ > $@ @@ -92,11 +90,11 @@ html: $(HTMLDOCS) #%.ps.gz: %.ps # gzip $^ - + #%.ps: %.dot -# dot -Tps -o $@ $^ +# dot -Tps -o $@ $^ clean-local: rm -f *.html - + diff --git a/doc/Makefile.in b/doc/Makefile.in index e177fed..fb04a84 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -137,7 +137,6 @@ SQLITE_LIBS = @SQLITE_LIBS@ SSL_LIB = @SSL_LIB@ STRIP = @STRIP@ U = @U@ -UUID_LIBS = @UUID_LIBS@ VERSION = @VERSION@ XML_CFLAGS = @XML_CFLAGS@ XML_LIBS = @XML_LIBS@ @@ -225,8 +224,7 @@ trigger_b4_dl.txt \ webdav.txt \ expire.txt \ dirlisting.txt \ -evhost.txt \ -magnet.txt +evhost.txt HTMLDOCS = accesslog.html \ authentication.html \ @@ -262,8 +260,7 @@ HTMLDOCS = accesslog.html \ webdav.html \ expire.html \ dirlisting.html \ - evhost.html \ - magnet.html + evhost.html EXTRA_DIST = lighttpd.conf lighttpd.user \ rc.lighttpd rc.lighttpd.redhat sysconfig.lighttpd \ @@ -493,7 +490,7 @@ html: $(HTMLDOCS) # gzip $^ #%.ps: %.dot -# dot -Tps -o $@ $^ +# dot -Tps -o $@ $^ clean-local: rm -f *.html diff --git a/doc/access.txt b/doc/access.txt index 042da01..acfdcb7 100644 --- a/doc/access.txt +++ b/doc/access.txt @@ -12,10 +12,10 @@ Module: mod_access :abstract: The access module is used to deny access to files with given trailing path names. - + .. meta:: :keywords: lighttpd, trailing path access control - + .. contents:: Table of Contents Description @@ -32,7 +32,7 @@ url.access-deny Default: empty Example: :: - + url.access-deny = ( "~", ".inc") will deny access to all files ended with a diacritical mark (~) or .inc diff --git a/doc/accesslog.txt b/doc/accesslog.txt index 889a4da..36584cf 100644 --- a/doc/accesslog.txt +++ b/doc/accesslog.txt @@ -11,11 +11,11 @@ Module: mod_accesslog :Revision: $Revision: 1.2 $ :abstract: - The accesslog module ... - + The accesslog module ... + .. meta:: :keywords: lighttpd, accesslog, CLF - + .. contents:: Table of Contents Description @@ -28,30 +28,30 @@ Options accesslog.use-syslog send the accesslog to syslog - + Default: disabled accesslog.filename name of the file where the accesslog should be written too if syslog is not used. - + if the name starts with a '|' the rest of the name is taken as the name of a process which will be spawn and will get the output - + e.g.: :: - + accesslog.filename = "/var/log/lighttpd.log" - + $HTTP["host"] == "mail.example.org" { accesslog.filename = "|/usr/bin/cronolog" } - + Default: disabled accesslog.format the format of the logfile - + ====== ================================ Option Description ====== ================================ @@ -60,8 +60,8 @@ accesslog.format %l ident name (not supported) %u authenticated user %t timestamp for the request-start - %r request-line - %s status code + %r request-line + %s status code %b bytes sent for the body %i HTTP-header field %a remote address @@ -86,16 +86,16 @@ accesslog.format %I bytes incomming %O bytes outgoing ====== ================================ - + If %s is written %>s or %<s the < and the > are ignored. They are support - for compat with apache. - + for compat with apache. + %i and %o expect the name of the field which should be written in curly brackets. - + e.g.: :: - + accesslog.format = "%h %l %u %t \"%r\" %b %>s \"%{User-Agent}i\" \"%{Referer}i\"" - + Default: CLF compatible output Response Header @@ -109,18 +109,18 @@ If you want to log it into the accesslog just specify the field-name within a %{...}o like :: accesslog.format = "%h %l %u %t \"%r\" %b %>s \"%{User-Agent}i\" \"%{Referer}i\" \"%{X-LIGHTTPD-SID}o\"" - + The prefix ``X-LIGHTTPD-`` is special as every response header starting with this prefix is assumed to be special for lighttpd and won't be sent out -to the client. +to the client. An example the use this functionality is provided below: :: <?php - + session_start(); - + header("X-LIGHTTPD-SID: ".session_id()); - + ?> diff --git a/doc/alias.txt b/doc/alias.txt index 1315f93..15012e3 100644 --- a/doc/alias.txt +++ b/doc/alias.txt @@ -11,11 +11,11 @@ Module: mod_alias :Revision: $Revision: 1.1 $ :abstract: - The alias module ... - + The alias module ... + .. meta:: :keywords: lighttpd, alias - + .. contents:: Table of Contents Description @@ -32,5 +32,5 @@ alias.url Default: empty Example: :: - + alias.url = ( "/cgi-bin/" => "/var/www/servers/www.example.org/cgi-bin/" ) diff --git a/doc/authentication.txt b/doc/authentication.txt index c375ece..2a11f64 100644 --- a/doc/authentication.txt +++ b/doc/authentication.txt @@ -7,15 +7,15 @@ Module: mod_auth ---------------- :Author: Jan Kneschke -:Date: $Date: 2006-10-04 15:26:23 +0200 (Wed, 04 Oct 2006) $ -:Revision: $Revision: 1371 $ +:Date: $Date: 2006-01-12 19:34:26 +0100 (Thu, 12 Jan 2006) $ +:Revision: $Revision: 940 $ :abstract: The auth module provides ... - + .. meta:: :keywords: lighttpd, authentication - + .. contents:: Table of Contents Description @@ -24,85 +24,85 @@ Description Supported Methods ----------------- -lighttpd supportes both authentication method described by -RFC 2617: +lighttpd supportes both authentication method described by +RFC 2617: basic ````` -The Basic method transfers the username and the password in -cleartext over the network (base64 encoded) and might result -in security problems if not used in conjunction with a crypted +The Basic method transfers the username and the password in +cleartext over the network (base64 encoded) and might result +in security problems if not used in conjunction with a crypted channel between client and server. digest `````` -The Digest method only transfers a hashed value over the -network which performs a lot of work to harden the +The Digest method only transfers a hashed value over the +network which performs a lot of work to harden the authentication process in insecure networks. Backends -------- -Depending on the method lighttpd provides various way to store +Depending on the method lighttpd provides various way to store the credentials used for the authentication. for basic auth: - plain_ -- htpasswd_ +- htpasswd_ - htdigest_ - ldap_ - + for digest auth: - plain_ - htdigest_ - + plain ````` -A file which contains username and the cleartext password -seperated by a colon. Each entry is terminated by a single +A file which contains username and the cleartext password +seperated by a colon. Each entry is terminated by a single newline.:: e.g.: agent007:secret - + htpasswd ```````` -A file which contains username and the crypt()'ed password -seperated by a colon. Each entry is terminated by a single +A file which contains username and the crypt()'ed password +seperated by a colon. Each entry is terminated by a single newline. :: e.g.: agent007:XWY5JwrAVBXsQ -You can use htpasswd from the apache distribution to manage +You can use htpasswd from the apache distribution to manage those files. :: - + $ htpasswd lighttpd.user.htpasswd agent007 - - + + htdigest ```````` -A file which contains username, realm and the md5()'ed -password seperated by a colon. Each entry is terminated +A file which contains username, realm and the md5()'ed +password seperated by a colon. Each entry is terminated by a single newline. :: - + e.g.: agent007:download area:8364d0044ef57b3defcfa141e8f77b65 - -You can use htdigest from the apache distribution to manage + +You can use htdigest from the apache distribution to manage those files. :: $ htdigest lighttpd.user.htdigest 'download area' agent007 - + Using md5sum can also generate the password-hash: :: #!/bin/sh @@ -118,21 +118,21 @@ To use it: $ htdigest.sh 'agent007' 'download area' 'secret' agent007:download area:8364d0044ef57b3defcfa141e8f77b65 - - - + + + ldap ```` -the ldap backend is basically performing the following steps +the ldap backend is basically performing the following steps to authenticate a user - + 1. connect anonymously (at plugin init) 2. get DN for filter = username 3. auth against ldap server 4. disconnect - -if all 4 steps are performed without any error the user is + +if all 4 steps are performed without any error the user is authenticated Configuration @@ -143,28 +143,28 @@ Configuration ## debugging # 0 for off, 1 for 'auth-ok' messages, 2 for verbose debugging auth.debug = 0 - - ## type of backend + + ## type of backend # plain, htpasswd, ldap or htdigest auth.backend = "htpasswd" - # filename of the password storage for + # filename of the password storage for # plain auth.backend.plain.userfile = "lighttpd-plain.user" - + ## for htpasswd auth.backend.htpasswd.userfile = "lighttpd-htpasswd.user" - + ## for htdigest auth.backend.htdigest.userfile = "lighttpd-htdigest.user" ## for ldap - # the $ in auth.backend.ldap.filter is replaced by the + # the $ in auth.backend.ldap.filter is replaced by the # 'username' from the login dialog auth.backend.ldap.hostname = "localhost" auth.backend.ldap.base-dn = "dc=my-domain,dc=com" auth.backend.ldap.filter = "(uid=$)" - # if enabled, startTLS needs a valid (base64-encoded) CA + # if enabled, startTLS needs a valid (base64-encoded) CA # certificate auth.backend.ldap.starttls = "enable" auth.backend.ldap.ca-file = "/etc/CAcertificate.pem" @@ -178,20 +178,20 @@ Configuration # "require" => "user=<username>" ) # ) # - # <realm> is a string to display in the dialog - # presented to the user and is also used for the - # digest-algorithm and has to match the realm in the + # <realm> is a string to display in the dialog + # presented to the user and is also used for the + # digest-algorithm and has to match the realm in the # htdigest file (if used) # - auth.require = ( "/download/" => - ( + auth.require = ( "/download/" => + ( "method" => "digest", "realm" => "download archiv", "require" => "user=agent007|user=agent008" ), - "/server-info" => - ( + "/server-info" => + ( "method" => "digest", "realm" => "download archiv", "require" => "valid-user" @@ -201,7 +201,7 @@ Configuration Limitations ============ -- The implementation of digest method is currently not +- The implementation of digest method is currently not completely compliant with the standard as it still allows a replay attack. diff --git a/doc/cgi.txt b/doc/cgi.txt index 95d187c..081d795 100644 --- a/doc/cgi.txt +++ b/doc/cgi.txt @@ -12,10 +12,10 @@ Module: mod_cgi :abstract: The cgi module provides a CGI-conforming interface. - + .. meta:: :keywords: lighttpd, cgi - + .. contents:: Table of Contents Description @@ -32,7 +32,7 @@ cgi.assign file-extensions that are handled by a CGI program e.g.: :: - + cgi.assign = ( ".pl" => "/usr/bin/perl", ".cgi" => "/usr/bin/perl" ) @@ -43,7 +43,7 @@ To setup a executable which doesn't need the help of a external program you just don't specify a handler for the extension. :: cgi.assign = ( ".sh" => "" ) - + If the file has no extension keep in mind that lighttpd matches not the extension itself but the right part of the URL: :: diff --git a/doc/cml.txt b/doc/cml.txt index 10fac70..ae69067 100644 --- a/doc/cml.txt +++ b/doc/cml.txt @@ -12,10 +12,10 @@ Module: mod_cml :abstract: CML is a Meta language to describe the dependencies of a page at one side and building a page from its fragments on the other side using LUA. - + .. meta:: :keywords: lighttpd, cml, lua - + .. contents:: Table of Contents Description @@ -31,7 +31,7 @@ CML (Cache Meta Language) wants to solves several problems: Cache Decision -------------- -A simple example should show how to a content caching the very simple way in PHP. +A simple example should show how to a content caching the very simple way in PHP. jan.kneschke.de has a very simple design: @@ -39,7 +39,7 @@ jan.kneschke.de has a very simple design: * the menu is generated from a menu.csv file * the content is coming from files on the local directory named content-1, content-2 and so on -The page content is static as long non of the those tree items changes. A change in the layout +The page content is static as long non of the those tree items changes. A change in the layout is affecting all pages, a change of menu.csv too, a change of content-x file only affects the cached page itself. @@ -58,7 +58,7 @@ If we model this in PHP we get: :: } foreach($content as $k => $v) { - if (isset($v["file"]) && + if (isset($v["file"]) && filemtime($v["file"]) > $cachemtime) { return 0; } @@ -71,7 +71,7 @@ If we model this in PHP we get: :: return 0; } } - + if (is_cachable(...), $cachefile) { readfile($cachefile); exit(); @@ -81,7 +81,7 @@ If we model this in PHP we get: :: ?> Quite simple. No magic involved. If the one of the files is new than the cached -content, the content is dirty and has to be regenerated. +content, the content is dirty and has to be regenerated. Now let take a look at the numbers: @@ -92,9 +92,9 @@ As you can see the increase is not as good as it could be. The main reason as th of the PHP interpreter to start up (a byte-code cache has been used here). Moving these decisions out of the PHP script into a server module will remove the need -to start PHP for a cache-hit. +to start PHP for a cache-hit. -To transform this example into a CML you need 'index.cml' in the list of indexfiles +To transform this example into a CML you need 'index.cml' in the list of indexfiles and the following index.cml file: :: output_contenttype = "text/html" @@ -110,7 +110,7 @@ and the following index.cml file: :: file_mtime(b .. "templates/jk.tmpl") > file_mtime(cwd .. "_cache.html") or file_mtime(b .. "content.html") > file_mtime(cwd .. "_cache.html") then return CACHE_MISS - else + else return CACHE_HIT end @@ -132,26 +132,26 @@ Sometimes the different fragment are already generated externally. You have to c readfile("spacer2.html"); readfile("news.html"); readfile("footer.html"); - ?> + ?> -We we can do the same several times faster directly in the webserver. +We we can do the same several times faster directly in the webserver. Don't forget: Webserver are built to send out static content, that is what they can do best. The index.cml for this looks like: :: output_contenttype = "text/html" - + cwd = request["CWD"] - - output_include = { cwd .. "head.html", + + output_include = { cwd .. "head.html", cwd .. "menu.html", cwd .. "spacer.html", cwd .. "db-content.html", cwd .. "spacer2.html", cwd .. "news.html", cwd .. "footer.html" } - + return CACHE_HIT Now we get about 10000 req/s instead of 600 req/s. @@ -161,7 +161,7 @@ Power Magnet Next to all the features about Cache Decisions CML can do more. Starting with lighttpd 1.4.9 a power-magnet was added which attracts each request -and allows you to manipulate the request for your needs. +and allows you to manipulate the request for your needs. We want to display a maintainance page by putting a file in a specified place: @@ -183,7 +183,7 @@ and create /home/www/power-magnet.cml with: :: For each requested file the /home/www/power-magnet.cml is executed which checks if maintainance.html exists in the docroot and displays it -instead of handling the usual request. +instead of handling the usual request. Another example, create thumbnail for requested image and serve it instead of sending the big image: :: @@ -196,7 +196,7 @@ of sending the big image: :: dr = request["DOCUMENT_ROOT"] sn = request["SCRIPT_NAME"] - ## to be continued :) ... + ## to be continued :) ... trigger_handler = '/gen_image.php' @@ -217,7 +217,7 @@ To use the plugin you have to load it: :: Options ======= -:cml.extension: +:cml.extension: the file extension that is bound to the cml-module :cml.memcache-hosts: hosts for the memcache.* functions @@ -229,7 +229,7 @@ Options Language ======== -The language used for CML is provided by `LUA <http://www.lua.org/>`_. +The language used for CML is provided by `LUA <http://www.lua.org/>`_. Additionally to the functions provided by lua mod_cml provides: :: @@ -252,10 +252,10 @@ Additionally to the functions provided by lua mod_cml provides: :: number file_mtime(string) string memcache_get_string(string) number memcache_get_long(string) - boolean memcache_exists(string) + boolean memcache_exists(string) -What ever your script does, it has to return either CACHE_HIT or CACHE_MISS. -It case a error occures check the error-log, the user will get a error 500. If you don't like +What ever your script does, it has to return either CACHE_HIT or CACHE_MISS. +It case a error occures check the error-log, the user will get a error 500. If you don't like the standard error-page use ``server.errorfile-prefix``. diff --git a/doc/compress.txt b/doc/compress.txt index a739c42..7b083e9 100644 --- a/doc/compress.txt +++ b/doc/compress.txt @@ -12,17 +12,17 @@ Module: mod_compress :abstract: a nice, short abstrace about the module - + .. meta:: :keywords: lighttpd, compress - + .. contents:: Table of Contents Description =========== Output compression reduces the network load and can improve the overall -throughput of the webserver. +throughput of the webserver. Only static content is supported up to now. @@ -36,21 +36,21 @@ compress.cache-dir name of the directory where compressed content will be cached e.g.: :: - + compress.cache-dir = "/var/www/cache/" - + # even better with virt-hosting $HTTP["host"] == "docs.example.org" { compress.cache-dir = "/var/www/cache/docs.example.org/" } - + Default: not set, compress the file for every request compress.filetype mimetypes where might get compressed - + e.g.: :: - + compress.filetype = ("text/plain", "text/html") Default: not set @@ -62,5 +62,5 @@ Compressing Dynamic Content To compress dynamic content with PHP please enable :: zlib.output_compression = 1 - + in the php.ini as PHP provides compression support by itself. diff --git a/doc/configuration.txt b/doc/configuration.txt index 416329b..2b60e58 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -7,15 +7,15 @@ Module: core ------------ :Author: Jan Kneschke -:Date: $Date: 2006-10-04 15:26:23 +0200 (Wed, 04 Oct 2006) $ -:Revision: $Revision: 1371 $ +:Date: $Date: 2006-03-09 01:10:40 +0100 (Thu, 09 Mar 2006) $ +:Revision: $Revision: 1034 $ :abstract: the layout of the configuration file - + .. meta:: :keywords: lighttpd, configuration - + .. contents:: Table of Contents Description @@ -36,21 +36,21 @@ A BNF like notation: :: <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 ) @@ -125,22 +125,22 @@ Example $HTTP["url"] =~ "^/download/" { dir-listing.activate = "disable" } - + # handish 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/" } @@ -148,19 +148,19 @@ Example $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 + # 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 = ( "" ) } - } + } Using variables =============== @@ -177,7 +177,7 @@ You can set your own variables in the configuration to simplify your config. in incl-base.conf: server.document-root = basedir + server.name + "/pages/" accesslog.filename = basedir + server.name + "/logs/access.log" - + You can also use environement variables or the default variables var.PID and var.CWD: :: @@ -248,11 +248,11 @@ server.document-root might have specified with one of the above conditionals. Default: no default, required - + server.bind IP address, hostname or absolute path to the unix-domain socket the server listen on. - + Default: bind to all interfaces Example: :: @@ -260,14 +260,14 @@ server.bind server.bind = "127.0.0.1" server.bind = "www.example.org" server.bind = "/tmp/lighttpd.socket" - + 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 @@ -275,42 +275,42 @@ server.tag set the string returned by the Server: response header Default: lighttpd <current-version> - + 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 - + NOTE: requires root-permissions - + 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.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-file.names = ( "index.php", "index.html", "index.htm", "default.htm" ) if a name starts with slash this file will be used a index generator @@ -318,17 +318,17 @@ index-file.names server.modules modules to load - + .. note:: the order of the modules is important. The modules are executed in the order as they are specified. Loading mod_auth AFTER mod_fastcgi might disable authentication for fastcgi - backends (if check-local is disabled). + backends (if check-local is disabled). - As auth should be done first, move it before all executing modules (like + As auth should be done first, move it before all executing modules (like proxy, fastcgi, scgi and cgi). - rewrites, redirects and access should be first, followed by auth and + rewrites, redirects and access should be first, followed by auth and the docroot plugins. Afterwards the external handlers like fastcgi, cgi, scgi and proxy and @@ -336,12 +336,12 @@ server.modules e.g.: :: - server.modules = ( "mod_rewrite", - "mod_redirect", + server.modules = ( "mod_rewrite", + "mod_redirect", "mod_alias", - "mod_access", - "mod_auth", - "mod_status", + "mod_access", + "mod_auth", + "mod_status", "mod_simple_vhost", "mod_evhost", "mod_userdir", @@ -363,74 +363,74 @@ server.modules - mod_staticfile server.event-handler - set the 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. + 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 daemon mode - + Default: not set - + server.max-request-size maximum size in kbytes of the request (header + body). Only applies to POST requests. - + Default: 2097152 (2GB) server.max-worker number of worker processes to spawn. This is usually only needed on servers which are fairly loaded and the network handler calls delay often (e.g. new requests are not handled instantaneously). - + 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 + 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 + 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 @@ -445,9 +445,9 @@ debugging debug.dump-unknown-headers enables listing of internally unhandled HTTP-headers - + e.g. :: - + debug.dump-unknown-headers = "enable" mimetypes @@ -456,20 +456,20 @@ 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", + + 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 + 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", + ".gz" => "application/x-gzip", If you want to set another default mimetype use: :: @@ -483,17 +483,17 @@ mimetype.use-xattr 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 @@ -501,13 +501,13 @@ debugging ````````` debug.log-request-header - default: disabled - + default: disabled + debug.log-response-header - default: disabled + default: disabled debug.log-file-not-found - default: disabled + default: disabled debug.log-request-handling - default: disabled + default: disabled diff --git a/doc/dirlisting.txt b/doc/dirlisting.txt index 3b33752..ea65ba6 100644 --- a/doc/dirlisting.txt +++ b/doc/dirlisting.txt @@ -13,10 +13,10 @@ Module: mod_dirlisting :abstract: mod_dirlisting generates HTML based directory listings with full CSS control - + .. meta:: :keywords: lighttpd, directory listings, dirlisting - + .. contents:: Table of Contents Description @@ -53,7 +53,7 @@ Options dir-listing.activate enables virtual directory listings if a directory is requested no - index-file was found + index-file was found Default: disabled @@ -78,5 +78,5 @@ dir-listing.encoding encoding) Example: :: - + dir-listing.encoding = "utf-8" diff --git a/doc/evhost.txt b/doc/evhost.txt index 441029c..9e79b03 100644 --- a/doc/evhost.txt +++ b/doc/evhost.txt @@ -12,10 +12,10 @@ Module: mod_evhost :abstract: virtual hosting - + .. meta:: :keywords: lighttpd, virtual hosting - + .. contents:: Table of Contents Description @@ -23,10 +23,10 @@ Description mod_evhost builds the document-root based on a pattern which contains wildcards. Those wildcards can represent parts if the submitted hostname - + :: - + %% => % sign %0 => domain name + tld %1 => tld @@ -39,7 +39,7 @@ wildcards. Those wildcards can represent parts if the submitted hostname Options ======= -evhost.path-pattern +evhost.path-pattern pattern with wildcards to be replace to build a documentroot - + diff --git a/doc/expire.txt b/doc/expire.txt index ca59c42..2aee938 100644 --- a/doc/expire.txt +++ b/doc/expire.txt @@ -12,17 +12,17 @@ Module: mod_expire :abstract: mod_expire controls the setting of the the Expire Response header - + .. meta:: :keywords: lighttpd, expire - + .. contents:: Table of Contents Description =========== mod_expire controls the Expire header in the Response Header of HTTP/1.0 -messages. It is usefull to set it for static files which should be cached +messages. It is usefull to set it for static files which should be cached aggressivly like images, stylesheets or similar. Options @@ -35,8 +35,8 @@ expire.url <access|modification> <number> <years|months|days|hours|minutes|seconds> following the syntax used by mod_expire in Apache 1.3.x and later. - + Example: :: - + expire.url = ( "/images/" => "access 1 hour" ) - + diff --git a/doc/fastcgi-state.txt b/doc/fastcgi-state.txt index a05d2c2..9e76a6f 100644 --- a/doc/fastcgi-state.txt +++ b/doc/fastcgi-state.txt @@ -11,13 +11,13 @@ Module: fastcgi :Revision: $Revision: 1.1 $ :abstract: - This is a short summary of the state-engine which is driving the FastCGI + This is a short summary of the state-engine which is driving the FastCGI module. It describes the basic concepts and the way the different parts of the module are connected. - + .. meta:: :keywords: lighttpd, state-engine, fastcgi - + .. contents:: Table of Contents Description @@ -27,7 +27,7 @@ States ------ The state-engine is currently made of 6 states which are walk-through on -the way each connection. +the way each connection. :init: prepare fastcgi-connection @@ -41,7 +41,7 @@ the way each connection. read fastcgi-response from network and push it to the write-queue :close: terminate the connection - + .. image:: fastcgi-state.png Delays diff --git a/doc/fastcgi.txt b/doc/fastcgi.txt index fc46385..a29cf48 100644 --- a/doc/fastcgi.txt +++ b/doc/fastcgi.txt @@ -12,72 +12,72 @@ Module: mod_fastcgi :abstract: The FastCGI interface is the fastest and most secure way - to interface external process-handlers like Perl, PHP and - your self-written applications. - + to interface external process-handlers like Perl, PHP and + your self-written applications. + .. meta:: :keywords: lighttpd, FastCGI - + .. contents:: Table of Contents Description =========== -lighttpd provides an interface to a external programs that -support the FastCGI interface. The FastCGI Interface is -defined by http://www.fastcgi.com/ and is a +lighttpd provides an interface to a external programs that +support the FastCGI interface. The FastCGI Interface is +defined by http://www.fastcgi.com/ and is a platform-independent and server independent interface between a web-application and a webserver. -This means that FastCGI programs that run with the Apache +This means that FastCGI programs that run with the Apache Webserver will run seamlessly with lighttpd and vice versa. FastCGI ------- -FastCGI is removes a lot of the limitations of CGI programs. -CGI programs have the problem that they have to be restarted -by the webserver for every request which leads to really bad +FastCGI is removes a lot of the limitations of CGI programs. +CGI programs have the problem that they have to be restarted +by the webserver for every request which leads to really bad performance values. -FastCGI removes this limitation by keeping the process running -and handling the requests by this always running process. This -removes the time used for the fork() and the overall startup -and cleanup time which is necessary to create and destroy a +FastCGI removes this limitation by keeping the process running +and handling the requests by this always running process. This +removes the time used for the fork() and the overall startup +and cleanup time which is necessary to create and destroy a process. -While CGI programs communicate to the server over pipes, -FastCGI processes use Unix-Domain-Sockets or TCP/IP to talk -with the webserver. This gives you the second advantage over +While CGI programs communicate to the server over pipes, +FastCGI processes use Unix-Domain-Sockets or TCP/IP to talk +with the webserver. This gives you the second advantage over simple CGI programs: FastCGI don't have to run on the Webserver -itself but everywhere in the network. +itself but everywhere in the network. -lighttpd takes it a little bit further by providing a internal -FastCGI load-balancer which can be used to balance the load -over multiple FastCGI Servers. In contrast to other solutions -only the FastCGI process has to be on the cluster and not the +lighttpd takes it a little bit further by providing a internal +FastCGI load-balancer which can be used to balance the load +over multiple FastCGI Servers. In contrast to other solutions +only the FastCGI process has to be on the cluster and not the whole webserver. That gives the FastCGI process more resources than a e.g. load-balancer+apache+mod_php solution. -If you compare FastCGI against a apache+mod_php solution you -should note that FastCGI provides additional security as the -FastCGI process can be run under different permissions that -the webserver and can also live a chroot which might be -different than the one the webserver is running in. +If you compare FastCGI against a apache+mod_php solution you +should note that FastCGI provides additional security as the +FastCGI process can be run under different permissions that +the webserver and can also live a chroot which might be +different than the one the webserver is running in. Options ======= -lighttpd provides the FastCGI support via the fastcgi-module +lighttpd provides the FastCGI support via the fastcgi-module (mod_fastcgi) which provides 2 options in the config-file: fastcgi.debug - a value between 0 and 65535 to set the debug-level in the - FastCGI module. Currently only 0 and 1 are used. Use 1 to + a value between 0 and 65535 to set the debug-level in the + FastCGI module. Currently only 0 and 1 are used. Use 1 to enable some debug output, 0 to disable it. -fastcgi.map-extensions +fastcgi.map-extensions map multiple extensions to the same fastcgi server Example: :: @@ -85,23 +85,23 @@ fastcgi.map-extensions fastcgi.map-extensions = ( ".php3" => ".php" ) fastcgi.server - tell the module where to send FastCGI requests to. Every - file-extension can have it own handler. Load-Balancing is + tell the module where to send FastCGI requests to. Every + file-extension can have it own handler. Load-Balancing is done by specifying multiple handles for the same extension. - + structure of fastcgi.server section: :: - - ( <extension> => - ( + + ( <extension> => + ( ( "host" => <string> , "port" => <integer> , "socket" => <string>, # either socket # or host+port - "bin-path" => <string>, # OPTIONAL - "bin-environment" => <array>, # OPTIONAL - "bin-copy-environment" => <array>, # OPTIONAL + "bin-path" => <string>, # OPTIONAL + "bin-environment" => <array>, # OPTIONAL + "bin-copy-environment" => <array>, # OPTIONAL "mode" => <string>, # OPTIONAL - "docroot" => <string> , # OPTIONAL if "mode" + "docroot" => <string> , # OPTIONAL if "mode" # is not "authorizer" "check-local" => <string>, # OPTIONAL "min-procs" => <integer>, # OPTIONAL @@ -112,54 +112,54 @@ fastcgi.server "disable-time" => <integer>, # optional "allow-x-send-file" => <boolean> # optional ), - ( "host" => ... - ) + ( "host" => ... + ) ) ) - - :<extension>: is the file-extension or prefix + + :<extension>: is the file-extension or prefix (if started with "/") :"host": is hostname/ip of the FastCGI process :"port": is tcp-port on the "host" used by the FastCGI process - :"bin-path": path to the local FastCGI binary which should be + :"bin-path": path to the local FastCGI binary which should be started if no local FastCGI is running :"socket": path to the unix-domain socket - :"mode": is the FastCGI protocol mode. - Default is "responder", also "authorizer" + :"mode": is the FastCGI protocol mode. + Default is "responder", also "authorizer" mode is implemented. - :"docroot": is optional and is the docroot on the remote - host for default "responder" mode. For - "authorizer" mode it is MANDATORY and it points + :"docroot": is optional and is the docroot on the remote + host for default "responder" mode. For + "authorizer" mode it is MANDATORY and it points to docroot for authorized requests. For security reasons it is recommended to keep this docroot outside of server.document-root tree. - :"check-local": is optional and may be "enable" (default) or - "disable". If enabled the server first check - for a file in local server.document-root tree + :"check-local": is optional and may be "enable" (default) or + "disable". If enabled the server first check + for a file in local server.document-root tree and return 404 (Not Found) if no such file. - If disabled, the server forward request to + If disabled, the server forward request to FastCGI interface without this check. - :"broken-scriptfilename": breaks SCRIPT_FILENAME in a wat that + :"broken-scriptfilename": breaks SCRIPT_FILENAME in a wat that PHP can extract PATH_INFO from it (default: disabled) :"disable-time": time to wait before a disabled backend is checked again :"allow-x-send-file": controls if X-LIGHTTPD-send-file headers - are allowed + are allowed If bin-path is set: :"min-procs": sets the minium processes to start :"max-procs": the upper limit of the processess to start :"max-load-per-proc": maximum number of waiting processes on - average per process before a new process is + average per process before a new process is spawned :"idle-timeout": number of seconds before a unused process gets terminated - :"bin-environment": put an entry into the environment of + :"bin-environment": put an entry into the environment of the started process :"bin-copy-environement": clean up the environment and copy - only the specified entries into the fresh + only the specified entries into the fresh environment of the spawn process @@ -167,9 +167,9 @@ Examples -------- Multiple extensions for the same host :: - + fastcgi.server = ( ".php" => - (( "host" => "127.0.0.1", + (( "host" => "127.0.0.1", "port" => 1026, "bin-path" => "/usr/local/bin/php" )), @@ -180,30 +180,30 @@ Examples ) Example with prefix: :: - + fastcgi.server = ( "/remote_scripts/" => (( "host" => "192.168.0.3", "port" => 9000, "check-local" => "disable", - "docroot" => "/" # remote server may use + "docroot" => "/" # remote server may use # it's own docroot )) ) - + The request `http://my.host.com/remote_scripts/test.cgi` will be forwarded to fastcgi server at 192.168.0.3 and the value "/remote_scripts/test.cgi" will be used for the SCRIPT_NAME - variable. Remote server may prepend it with its own - document root. The handling of index files is also the + variable. Remote server may prepend it with its own + document root. The handling of index files is also the resposibility of remote server for this case. - In the case that the prefix is not terminated with a slash + In the case that the prefix is not terminated with a slash the prefix will be handled as file and /test.cgi would become a PATH_INFO instead of part of SCRIPT_NAME. Example for "authorizer" mode: :: - + fastcgi.server = ( "/remote_scripts/" => (( "host" => "10.0.0.2", "port" => 9000, @@ -212,23 +212,23 @@ Examples )) ) - Note that if "docroot" is specified then its value will be + Note that if "docroot" is specified then its value will be used in DOCUMENT_ROOT and SCRIPT_FILENAME variables passed to FastCGI server. Load-Balancing ============== -The FastCGI plugin provides automaticly a load-balancing between +The FastCGI plugin provides automaticly a load-balancing between multiple FastCGI servers. :: - fastcgi.server = ( ".php" => + fastcgi.server = ( ".php" => (( "host" => "10.0.0.2", "port" => 1030 ), ( "host" => "10.0.0.3", "port" => 1030 )) ) -To understand how the load-balancing works you can enable the +To understand how the load-balancing works you can enable the fastcgi.debug option and will get a similar output as here: :: proc: 127.0.0.1 1031 1 1 1 31454 @@ -244,89 +244,89 @@ fastcgi.debug option and will get a similar output as here: :: proc: 127.0.0.1 1031 1 1 2 31454 proc: 127.0.0.1 1029 1 1 2 31447 -Even if this for multiple FastCGI children on the local machine +Even if this for multiple FastCGI children on the local machine the following explaination is valid for remote connections too. -The output shows: +The output shows: - IP, port, unix-socket (is empty here) - is-local, state (0 - unset, 1 - running, ... ) - active connections (load) - PID -As you can see the list is always sorted by the load field. +As you can see the list is always sorted by the load field. -Whenever a new connection is requested, the first entry (the one -with the lowest load) is selected, the load is increased (got proc: ...) +Whenever a new connection is requested, the first entry (the one +with the lowest load) is selected, the load is increased (got proc: ...) and the list is sorted again. -If a FastCGI request is done or the connection is dropped, the load on the +If a FastCGI request is done or the connection is dropped, the load on the FastCGI proc decreases and the list is sorted again (release proc: ...) -This behaviour is very light-weight in code and still very efficient -as it keeps the fastcgi-servers equally loaded even if they have different -CPUs. +This behaviour is very light-weight in code and still very efficient +as it keeps the fastcgi-servers equally loaded even if they have different +CPUs. Adaptive Process Spawning ========================= -.. note:: This feature is disabled in 1.3.14 again. min-procs is +.. note:: This feature is disabled in 1.3.14 again. min-procs is ignored in that release -Starting with 1.3.8 lighttpd can spawn processes on demand if +Starting with 1.3.8 lighttpd can spawn processes on demand if a bin-path is specified and the FastCGI process runs locally. -If you want to have a least one FastCGI process running and -more of the number of requests increases you can use min-procs +If you want to have a least one FastCGI process running and +more of the number of requests increases you can use min-procs and max-procs. -A new process is spawned as soon as the average number of +A new process is spawned as soon as the average number of requests waiting to be handle by a single process increases the -max-load-per-proc setting. +max-load-per-proc setting. The idle-timeout specifies how long a fastcgi-process should wait -for a new request before it kills itself. +for a new request before it kills itself. Example ------- :: - fastcgi.server = ( ".php" => + fastcgi.server = ( ".php" => (( "socket" => "/tmp/php.socket", "bin-path" => "/usr/local/bin/php", "min-procs" => 1, "max-procs" => 32, "max-load-per-proc" => 4, - "idle-timeout" => 20 + "idle-timeout" => 20 )) ) Disabling Adaptive Spawning --------------------------- -Adaptive Spawning is a quite new feature and it might misbehave -for your setup. There are several ways to control how the spawing +Adaptive Spawning is a quite new feature and it might misbehave +for your setup. There are several ways to control how the spawing is done: 1. ``"max-load-per-proc" => 1`` if that works for you, great. - + 2. If not set ``min-procs == max-procs``. - + 3. For PHP you can also use: :: - + $ PHP_FCGI_CHILDREN=384 ./lighttpd -f ./lighttpd.conf - - fastcgi.server = ( ".php" => + + fastcgi.server = ( ".php" => (( "socket" => "/tmp/php.socket", "bin-path" => "/usr/local/bin/php", "min-procs" => 1, "max-procs" => 1, "max-load-per-proc" => 4, - "idle-timeout" => 20 + "idle-timeout" => 20 )) ) - + It will create one socket and let's PHP create the 384 processes itself. 4. If you don't want lighttpd to manage the fastcgi processes, remove the @@ -334,26 +334,26 @@ is done: FastCGI and Programming Languages -================================= +================================= Preparing PHP as a FastCGI program ---------------------------------- -One of the most important application that has a FastCGI -interface is php which can be downloaded from -http://www.php.net/ . You have to recompile the php from -source to enable the FastCGI interface as it is normally +One of the most important application that has a FastCGI +interface is php which can be downloaded from +http://www.php.net/ . You have to recompile the php from +source to enable the FastCGI interface as it is normally not enabled by default in the distributions. -If you already have a working installation of PHP on a +If you already have a working installation of PHP on a webserver execute a small script which just contains :: <?php phpinfo(); ?> -and search for the line in that contains the configure call. -You can use it as the base for the compilation. +and search for the line in that contains the configure call. +You can use it as the base for the compilation. -You have to remove all occurences of `--with-apxs`, `--with-apxs2` +You have to remove all occurences of `--with-apxs`, `--with-apxs2` and the like which would build PHP with Apache support. Add the next three switches to compile PHP with FastCGI support:: @@ -361,8 +361,8 @@ next three switches to compile PHP with FastCGI support:: --enable-fastcgi \ --enable-force-cgi-redirect \ ... - -After compilation and installation check that your PHP + +After compilation and installation check that your PHP binary contains FastCGI support by calling: :: $ php -v @@ -374,7 +374,7 @@ The important part is the (cgi-fcgi). Starting a FastCGI-PHP ---------------------- -Starting with version 1.3.6 lighttpd can spawn the FastCGI +Starting with version 1.3.6 lighttpd can spawn the FastCGI processes locally itself if necessary: :: fastcgi.server = ( ".php" => @@ -391,20 +391,20 @@ handles before it kills itself. :: fastcgi.server = ( ".php" => (( "socket" => "/tmp/php-fastcgi.socket", "bin-path" => "/usr/local/bin/php", - "bin-environment" => ( + "bin-environment" => ( "PHP_FCGI_CHILDREN" => "16", "PHP_FCGI_MAX_REQUESTS" => "10000" ) )) ) -To increase the security of the started process you should only pass +To increase the security of the started process you should only pass the necessary environment variables to the FastCGI process. :: fastcgi.server = ( ".php" => (( "socket" => "/tmp/php-fastcgi.socket", "bin-path" => "/usr/local/bin/php", - "bin-environment" => ( + "bin-environment" => ( "PHP_FCGI_CHILDREN" => "16", "PHP_FCGI_MAX_REQUESTS" => "10000" ), "bin-copy-environment" => ( @@ -425,7 +425,7 @@ and the option ``broken-scriptfilename`` in your fastcgi.server config: :: fastcgi.server = ( ".php" => (( "socket" => "/tmp/php-fastcgi.socket", "bin-path" => "/usr/local/bin/php", - "bin-environment" => ( + "bin-environment" => ( "PHP_FCGI_CHILDREN" => "16", "PHP_FCGI_MAX_REQUESTS" => "10000" ), "bin-copy-environment" => ( @@ -434,17 +434,17 @@ and the option ``broken-scriptfilename`` in your fastcgi.server config: :: )) ) -Why this ? the ``cgi.fix_pathinfo = 0`` would give you a working ``PATH_INFO`` +Why this ? the ``cgi.fix_pathinfo = 0`` would give you a working ``PATH_INFO`` but no ``PHP_SELF``. If you enable it, it turns around. To fix the ``PATH_INFO`` `--enable-discard-path` needs a SCRIPT_FILENAME which is against the CGI spec, a broken-scriptfilename. With ``cgi.fix_pathinfo = 1`` in php.ini and -``broken-scriptfilename => "enable"`` you get both. +``broken-scriptfilename => "enable"`` you get both. External Spawning ----------------- -Spawning FastCGI processes directly in the webserver has some +Spawning FastCGI processes directly in the webserver has some disadvantages like - FastCGI process can only run locally @@ -456,54 +456,54 @@ take off some load from the webserver you have to control the FastCGI process by a external program like spawn-fcgi. spawn-fcgi is used to start a FastCGI process in its own -environment and set the user-id, group-id and change to +environment and set the user-id, group-id and change to another root-directory (chroot). -For convenience a wrapper script should be used which takes -care of all the necessary option. Such a script in included +For convenience a wrapper script should be used which takes +care of all the necessary option. Such a script in included in the lighttpd distribution and is call spawn-php.sh. -The script has a set of config variables you should take +The script has a set of config variables you should take a look at: :: ## ABSOLUTE path to the spawn-fcgi binary SPAWNFCGI="/usr/local/sbin/spawn-fcgi" - + ## ABSOLUTE path to the PHP binary FCGIPROGRAM="/usr/local/bin/php" - + ## bind to tcp-port on localhost FCGIPORT="1026" - + ## bind to unix domain socket # FCGISOCKET="/tmp/php.sock" - + ## number of PHP childs to spawn PHP_FCGI_CHILDREN=10 - + ## number of request server by a single php-process until ## is will be restarted PHP_FCGI_MAX_REQUESTS=1000 - + ## IP adresses where PHP should access server connections ## from FCGI_WEB_SERVER_ADDRS="127.0.0.1,192.168.0.1" - + # allowed environment variables sperated by spaces ALLOWED_ENV="ORACLE_HOME PATH USER" - + ## if this script is run as root switch to the following user USERID=wwwrun GROUPID=wwwrun -If you have set the variables to values that fit to your +If you have set the variables to values that fit to your setup you can start it by calling: :: $ spawn-php.sh spawn-fcgi.c.136: child spawned successfully: PID: 6925 -If you get "child spawned successfully: PID:" the php -processes could be started successfully. You should see them +If you get "child spawned successfully: PID:" the php +processes could be started successfully. You should see them in your processlist: :: $ ps ax | grep php @@ -511,22 +511,22 @@ in your processlist: :: 6928 ? S 0:00 /usr/local/bin/php ... -The number of processes should be PHP_FCGI_CHILDREN + 1. -Here the process 6925 is the master of the slaves which -handle the work in parallel. Number of parallel workers can -be set by PHP_FCGI_CHILDREN. A worker dies automaticly of -handling PHP_FCGI_MAX_REQUESTS requests as PHP might have +The number of processes should be PHP_FCGI_CHILDREN + 1. +Here the process 6925 is the master of the slaves which +handle the work in parallel. Number of parallel workers can +be set by PHP_FCGI_CHILDREN. A worker dies automaticly of +handling PHP_FCGI_MAX_REQUESTS requests as PHP might have memory leaks. -If you start the script as user root php processes will be -running as the user USERID and group GROUPID to drop the -root permissions. Otherwise the php processes will run as +If you start the script as user root php processes will be +running as the user USERID and group GROUPID to drop the +root permissions. Otherwise the php processes will run as the user you started script as. -As the script might be started from a unknown stage or even -directly from the command-line it cleans the environment -before starting the processes. ALLOWED_ENV contains all -the external environement variables that should be available +As the script might be started from a unknown stage or even +directly from the command-line it cleans the environment +before starting the processes. ALLOWED_ENV contains all +the external environement variables that should be available to the php-process. @@ -539,7 +539,7 @@ Skeleton for remote authorizer ============================== The basic functionality of authorizer is as follows (see -http://www.fastcgi.com/devkit/doc/fcgi-spec.html, 6.3 for +http://www.fastcgi.com/devkit/doc/fcgi-spec.html, 6.3 for details). :: #include <fcgi_stdio.h> @@ -547,25 +547,25 @@ details). :: #include <unistd.h> int main () { char* p; - - while (FCGI_Accept() >= 0) { + + while (FCGI_Accept() >= 0) { /* wait for fastcgi authorizer request */ - + printf("Content-type: text/html\r\n"); - + if ((p = getenv("QUERY_STRING")) == NULL) || <QUERY_STRING is unauthorized>) printf("Status: 403 Forbidden\r\n\r\n"); - else printf("\r\n"); + else printf("\r\n"); /* default Status is 200 - allow access */ } - + return 0; } -It is possible to use any other variables provided by -FastCGI interface for authorization check. Here is only an +It is possible to use any other variables provided by +FastCGI interface for authorization check. Here is only an example. @@ -578,22 +578,22 @@ If you get: :: (fcgi.c.274) connect delayed: 8 (fcgi.c.289) connect succeeded: 8 - (fcgi.c.745) unexpected end-of-file (perhaps the fastcgi + (fcgi.c.745) unexpected end-of-file (perhaps the fastcgi process died): 8 -the fastcgi process accepted the connection but closed it -right away. This happens if FCGI_WEB_SERVER_ADDRS doesn't +the fastcgi process accepted the connection but closed it +right away. This happens if FCGI_WEB_SERVER_ADDRS doesn't include the host where you are connection from. If you get :: (fcgi.c.274) connect delayed: 7 - (fcgi.c.1107) error: unexpected close of fastcgi connection + (fcgi.c.1107) error: unexpected close of fastcgi connection for /peterp/seite1.php (no fastcgi process on host/port ?) - (fcgi.c.1015) emergency exit: fastcgi: connection-fd: 5 + (fcgi.c.1015) emergency exit: fastcgi: connection-fd: 5 fcgi-fd: 7 -the fastcgi process is not running on the host/port you are +the fastcgi process is not running on the host/port you are connection to. Check your configuration. If you get :: @@ -601,6 +601,6 @@ If you get :: (fcgi.c.274) connect delayed: 7 (fcgi.c.289) connect succeeded: 7 -everything is fine. The connect() call just was delayed a +everything is fine. The connect() call just was delayed a little bit and is completly normal. diff --git a/doc/features.txt b/doc/features.txt index f45fe08..cfccbb1 100644 --- a/doc/features.txt +++ b/doc/features.txt @@ -7,12 +7,12 @@ progress report :Revision: $Revision: 1.2 $ :abstract: - This document tries to track the requested features and + This document tries to track the requested features and the release when they have been implemented. - + .. meta:: :keywords: lighttpd, features - + .. contents:: Table of Contents Description @@ -29,17 +29,17 @@ It is used to see what is still missing and what is already done. :: > considering installing and testing the latest version. From a > quick glance, it seems to support most/all of the features of > Premium thttpd and Zeus. - + If you think it compares to Zeus, then you've obviously never used Zeus. - + lighttpd is currently the only non-blocking open source web server to support FastCGI responders and that's worthwhile. - + The documentation is lacking. Comments in the configuration file do not make up for a complete manual. - + Constantly improving. :: - + The configuration syntax is overly complex, like Apache. There is no .htaccess support. @@ -50,34 +50,34 @@ Constantly improving. :: SSL. Works since 1.3.0. :: - + There is no SSI support. Zeus has full recursive SSI support. Output from a FastCGI program can get run through the SSI interpreter. SSI can also do virtual includes recursively. - + SSI works since 1.2.4. :: - + Request logging is not configurable. Zeus supports fully configurable access logging, plus a binary version of CLF that save space. - + 1.2.6 adds Apache-like logfile config. :: - + Access control only allows authentication via username and password. There is no way to allow or deny based in IP address. - + planed for 1.3.x :: - + The request rewriting appears to only allow regex substitutions. Zeus has a simple, yet powerful, request rewrite language. + - - + There is no support for FastCGI authorizers. These are very useful for high traffic sites that require complex authentication schemes or that store authorization information in a central database. - + since 1.1.9. :: - + There is no bandwidth throttling support. Zeus does bandwidth throttling correctly (i.e. unlike past versions of thttpd) and can throttle on a per-subserver (thttpd-style virtual hosts) basis. @@ -88,29 +88,29 @@ since 1.3.8. :: modification of web server behavior. While it isn't strictly necessary for an open source web server, it nice to have a documented, consistent API, rather than having to manually patch the server. - + If someone requests it it might be implemented. :: - + There is no web based interface. Zeus has a complete web based interface for everything, including a powerful feature of configuring multiple virtual servers at once. - + That is something that should be a special feature of Zeus. :) :: - + There is no support for mapping certain URLs to specific filesystem paths. - + since 1.2.6 :: - + There is no referring checking. This is incredibly important to prevent hotlinking of bandwidth intensive media types (images, movies, etc.). - + we have something better: mod_secdownload. And if someone wants referer checking we have a condition in the config for it since 1.2.9 :: - + Zeus has a lot of features that lighttpd doesn't have, but I only mentioned the ones I care about and use. - - -- + + -- David Phillips <david@acz.org> http://david.acz.org/ diff --git a/doc/magnet.txt b/doc/magnet.txt deleted file mode 100644 index 9d7697a..0000000 --- a/doc/magnet.txt +++ /dev/null @@ -1,429 +0,0 @@ -{{{
-#!rst
-==============
-a power-magnet
-==============
-
-------------------
-Module: mod_magnet
-------------------
-
-
-
-.. contents:: Table of Contents
-
-Requirements
-============
-
-:Version: lighttpd 1.4.12 or higher
-:Packages: lua >= 5.1
-
-Overview
-========
-
-mod_magnet is a module to control the request handling in lighty.
-
-.. note::
-
- Keep in mind that the magnet is executed in the core of lighty. EVERY long-running operation is blocking
- ALL connections in the server. You are warned. For time-consuming or blocking scripts use mod_fastcgi and friends.
-
-For performance reasons mod_magnet caches the compiled script. For each script-run the script itself is checked for
-freshness and recompile if neccesary.
-
-
-Installation
-============
-
-mod_magnet needs a lighty which is compiled with the lua-support ( --with-lua). Lua 5.1 or higher are required by
-the module. Use "--with-lua=lua5.1" to install on Debian and friends. ::
-
- server.modules = ( ..., "mod_magnet", ... )
-
-Options
-=======
-
-mod_magnet can attract a request in several stages in the request-handling.
-
-* either at the same level as mod_rewrite, before any parsing of the URL is done
-* or at a later stage, when the doc-root is known and the physical-path is already setup
-
-It depends on the purpose of the script which stage you want to intercept. Usually you want to use
-the 2nd stage where the physical-path which relates to your request is known. At this level you
-can run checks against lighty.env["physical.path"].
-
-::
-
- magnet.attract-raw-url-to = ( ... )
- magnet.attract-physical-path-to = ( ... )
-
-You can define multiple scripts when separated by a semicolon. The scripts are executed in the specified
-order. If one of them a returning a status-code, the following scripts will not be executed.
-
-Tables
-======
-
-Most of the interaction between between mod_magnet and lighty is done through tables. Tables in lua are hashes (Perl), dictionaries (Java), arrays (PHP), ...
-
-Request-Environment
--------------------
-
-Lighttpd has its internal variables which are exported as read/write to the magnet.
-
-If "http://example.org/search.php?q=lighty" is requested this results in a request like ::
-
- GET /search.php?q=lighty HTTP/1.1
- Host: example.org
-
-When you are using ``attract-raw-url-to`` you can access the following variables:
-
-* parts of the request-line
-
- * lighty.env["request.uri"] = "/search.php?q=lighty"
-
-* HTTP request-headers
-
- * lighty.request["Host"] = "example.org"
-
-Later in the request-handling, the URL is splitted, cleaned up and turned into a physical path name:
-
-* parts of the URI
-
- * lighty.env["uri.path"] = "/search.php"
- * lighty.env["uri.path-raw"] = "/search.php"
- * lighty.env["uri.scheme"] = "http"
- * lighty.env["uri.authority"] = "example.org"
- * lighty.env["uri.query"] = "q=lighty"
-
-* filenames, pathnames
-
- * lighty.env["physical.path"] = "/my-docroot/search.php"
- * lighty.env["physical.rel-path"] = "/search.php"
- * lighty.env["physical.doc-root"] = "/my-docroot"
-
-All of them are readable, not all of the are writable (or don't have an effect if you write to them).
-
-As a start, you might want to use those variables for writing: ::
-
- -- 1. simple rewriting is done via the request.uri
- lighty.env["request.uri"] = ...
- return lighty.RESTART_REQUEST
-
- -- 2. changing the physical-path
- lighty.env["physical.path"] = ...
-
- -- 3. changing the query-string
- lighty.env["uri.query"] = ...
-
-Response Headers
-----------------
-
-If you want to set a response header for your request, you can add a field to the lighty.header[] table: ::
-
- lighty.header["Content-Type"] = "text/html"
-
-Sending Content
-===============
-
-You can generate your own content and send it out to the clients. ::
-
- lighty.content = { "<pre>", { filename = "/etc/passwd" }, "</pre>" }
- lighty.header["Content-Type"] = "text/html"
-
- return 200
-
-The lighty.content[] table is executed when the script is finished. The elements of the array are processed left to right and the elements can either be a string or a table. Strings are included AS IS into the output of the request.
-
-* Strings
-
- * are included as is
-
-* Tables
-
- * filename = "<absolute-path>" is required
- * offset = <number> [default: 0]
- * length = <number> [default: size of the file - offset]
-
-Internally lighty will use the sendfile() call to send out the static files at full speed.
-
-Status Codes
-============
-
-You might have seen it already in other examples: In case you are handling the request completly in the magnet you
-can return your own status-codes. Examples are: Redirected, Input Validation, ... ::
-
- if (lighty.env["uri.scheme"] == "http") then
- lighty.header["Location"] = "https://" .. lighty.env["uri.authority"] .. lighty.env["request.uri"]
- return 302
- end
-
-You every number above and equal to 100 is taken as final status code and finishes the request. No other modules are
-executed after this return.
-
-A special return-code is lighty.RESTART_REQUEST (currently equal to 99) which is usually used in combination with
-changing the request.uri in a rewrite. It restarts the splitting of the request-uri again.
-
-If you return nothing (or nil) the request-handling just continues.
-
-Debugging
-=========
-
-To easy debugging we overloaded the print()-function in lua and redirect the output of print() to the error-log. ::
-
- print("Host: " .. lighty.request["Host"])
- print("Request-URI: " .. lighty.env["request.uri"])
-
-
-Examples
-========
-
-Sending text-files as HTML
---------------------------
-
-This is a bit simplistic, but it illustrates the idea: Take a text-file and cover it in a <pre> tag.
-
-Config-file ::
-
- magnet.attract-physical-path-to = server.docroot + "/readme.lua"
-
-readme.lua ::
-
- lighty.content = { "<pre>", { filename = "/README" }, "</pre>" }
- lighty.header["Content-Type"] = "text/html"
-
- return 200
-
-Maintainance pages
-------------------
-
-Your side might be on maintainance from time to time. Instead of shutting down the server confusing all
-users, you can just send a maintainance page.
-
-Config-file ::
-
- magnet.attract-physical-path-to = server.docroot + "/maintainance.lua"
-
-maintainance.lua ::
-
- require "lfs"
-
- if (nil == lfs.attributes(lighty.env["physical.doc-root"] .. "/maintainance.html")) then
- lighty.content = ( lighty.env["physical.doc-root"] .. "/maintainance.html" )
-
- lighty.header["Content-Type"] = "text/html"
-
- return 200
- end
-
-mod_flv_streaming
------------------
-
-Config-file ::
-
- magnet.attract-physical-path-to = server.docroot + "/flv-streaming.lua"
-
-flv-streaming.lua::
-
- if (lighty.env["uri.query"]) then
- -- split the query-string
- get = {}
- for k, v in string.gmatch(lighty.env["uri.query"], "(%w+)=(%w+)") do
- get[k] = v
- end
-
- if (get["start"]) then
- -- missing: check if start is numeric and positive
-
- -- send te FLV header + a seek into the file
- lighty.content = { "FLV\x1\x1\0\0\0\x9\0\0\0\x9",
- { filename = lighty.env["physical.path"], offset = get["start"] } }
- lighty.header["Content-Type"] = "video/x-flv"
-
- return 200
- end
- end
-
-
-selecting a random file from a directory
-----------------------------------------
-
-Say, you want to send a random file (ad-content) from a directory.
-
-To simplify the code and to improve the performance we define:
-
-* all images have the same format (e.g. image/png)
-* all images use increasing numbers starting from 1
-* a special index-file names the highest number
-
-Config ::
-
- server.modules += ( "mod_magnet" )
- magnet.attract-physical-path-to = "random.lua"
-
-random.lua ::
-
- dir = lighty.env["physical.path"]
-
- f = assert(io.open(dir .. "/index", "r"))
- maxndx = f:read("*all")
- f:close()
-
- ndx = math.random(maxndx)
-
- lighty.content = { { filename = dir .. "/" .. ndx }}
- lighty.header["Content-Type"] = "image/png"
-
- return 200
-
-denying illegal character sequences in the URL
-----------------------------------------------
-
-Instead of implementing mod_security, you might just want to apply filters on the content
-and deny special sequences that look like SQL injection.
-
-A common injection is using UNION to extend a query with another SELECT query.
-
-::
-
- if (string.find(lighty.env["request.uri"], "UNION%s")) then
- return 400
- end
-
-Traffic Quotas
---------------
-
-If you only allow your virtual hosts a certain amount for traffic each month and want to
-disable them if the traffic is reached, perhaps this helps: ::
-
- host_blacklist = { ["www.example.org"] = 0 }
-
- if (host_blacklist[lighty.request["Host"]]) then
- return 404
- end
-
-Just add the hosts you want to blacklist into the blacklist table in the shown way.
-
-Complex rewrites
-----------------
-
-If you want to implement caching on your document-root and only want to regenerate
-content if the requested file doesn't exist, you can attract the physical.path: ::
-
- magnet.attract-physical-path-to = ( server.document-root + "/rewrite.lua" )
-
-rewrite.lua ::
-
- require "lfs"
-
- attr = lfs.attributes(lighty.env["physical.path"])
-
- if (not attr) then
- -- we couldn't stat() the file for some reason
- -- let the backend generate it
-
- lighty.env["uri.path"] = "/dispatch.fcgi"
- lighty.env["physical.rel-path"] = lighty.env["uri.path"]
- lighty.env["physical.path"] = lighty.env["physical.doc-root"] .. lighty.env["physical.rel-path"]
- fi
-
-luafilesystem
-+++++++++++++
-
-We are requiring the lua-module 'lfs' (http://www.keplerproject.org/luafilesystem/).
-
-I had to compile lfs myself for lua-5.1 which required a minor patch as compat-5.1 is not needed::
-
- $ wget http://luaforge.net/frs/download.php/1487/luafilesystem-1.2.tar.gz
- $ wget http://www.lighttpd.net/download/luafilesystem-1.2-lua51.diff
- $ gzip -cd luafilesystem-1.2.tar.gz | tar xf -
- $ cd luafilesystem-1.2
- $ patch -ls -p1 < ../luafilesystem-1.2-lua51.diff
- $ make install
-
-It will install lfs.so into /usr/lib/lua/5.1/ which is where lua expects the extensions on my system.
-
-SuSE and Gentoo are known to have their own lfs packages and don't require a compile.
-
-Usertracking
-------------
-
-... or how to store data globally in the script-context:
-
-Each script has its own script-context. When the script is started it only contains the lua-functions
-and the special lighty.* name-space. If you want to save data between script runs, you can use the global-script
-context:
-
-::
-
- if (nil == _G["usertrack"]) then
- _G["usertrack"] = {}
- end
- if (nil == _G["usertrack"][lighty.request["Cookie"]]) then
- _G["usertrack"][lighty.request["Cookie"]]
- else
- _G["usertrack"][lighty.request["Cookie"]] = _G["usertrack"][lighty.request["Cookie"]] + 1
- end
-
- print _G["usertrack"][lighty.request["Cookie"]]
-
-The global-context is per script. If you update the script without restarting the server, the context will still be maintained.
-
-Counters
---------
-
-mod_status support a global statistics page and mod_magnet allows to add and update values in the status page:
-
-Config ::
-
- status.statistics-url = "/server-counters"
- magnet.attract-raw-url-to = server.docroot + "/counter.lua"
-
-counter.lua ::
-
- lighty.status["core.connections"] = lighty.status["core.connections"] + 1
-
-Result::
-
- core.connections: 7
- fastcgi.backend.php-foo.0.connected: 0
- fastcgi.backend.php-foo.0.died: 0
- fastcgi.backend.php-foo.0.disabled: 0
- fastcgi.backend.php-foo.0.load: 0
- fastcgi.backend.php-foo.0.overloaded: 0
- fastcgi.backend.php-foo.1.connected: 0
- fastcgi.backend.php-foo.1.died: 0
- fastcgi.backend.php-foo.1.disabled: 0
- fastcgi.backend.php-foo.1.load: 0
- fastcgi.backend.php-foo.1.overloaded: 0
- fastcgi.backend.php-foo.load: 0
-
-Porting mod_cml scripts
------------------------
-
-mod_cml got replaced by mod_magnet.
-
-A CACHE_HIT in mod_cml::
-
- output_include = { "file1", "file2" }
-
- return CACHE_HIT
-
-becomes::
-
- content = { { filename = "/path/to/file1" }, { filename = "/path/to/file2"} }
-
- return 200
-
-while a CACHE_MISS like (CML) ::
-
- trigger_handler = "/index.php"
-
- return CACHE_MISS
-
-becomes (magnet) ::
-
- lighty.env["request.uri"] = "/index.php"
-
- return lighty.RESTART_REQUEST
-
-}}}
\ No newline at end of file diff --git a/doc/performance.txt b/doc/performance.txt index 04d48a1..56a7ca1 100644 --- a/doc/performance.txt +++ b/doc/performance.txt @@ -115,13 +115,13 @@ Solaris sendfilev FreeBSD sendfile ========== ========== -The best backend is selected at compile time. In case you want to use -another backend set: :: +The best backend is selected at compile time. In case you want to use +another backend set: :: server.network-backend = "writev" -You can find more information about network backend in: - +You can find more information about network backend in: + http://blog.lighttpd.net/articles/2005/11/11/optimizing-lighty-for-high-concurrent-large-file-downloads diff --git a/doc/plugins.txt b/doc/plugins.txt index 22dee40..91c81fd 100644 --- a/doc/plugins.txt +++ b/doc/plugins.txt @@ -13,23 +13,23 @@ Module: core :abstract: The plugin interface is an integral part of lighttpd which provides a flexible way to add specific functionality to lighttpd. - + .. meta:: :keywords: lighttpd, plugins - + .. contents:: Table of Contents Description =========== Plugins allow you to enhance the functionality of lighttpd without -changing the core of the webserver. They can be loaded at startup time +changing the core of the webserver. They can be loaded at startup time and can change virtually any aspect of the behaviour of the webserver. Plugin Entry Points ------------------- -lighttpd has 16 hooks which are used in different states of the +lighttpd has 16 hooks which are used in different states of the execution of the request: Serverwide hooks @@ -49,7 +49,7 @@ Serverwide hooks Connectionwide hooks ```````````````````` -Most of these hooks are called in ``http_response_prepare()`` after some +Most of these hooks are called in ``http_response_prepare()`` after some fields in the connection structure are set. :handle_uri_raw_: @@ -57,13 +57,13 @@ fields in the connection structure are set. :handle_uri_clean_: called after uri.path (a clean URI without .. and %20) is set :handle_docroot_: - called at the end of the logical path handle to get a docroot + called at the end of the logical path handle to get a docroot :handle_subrequest_start_: called if the physical path is set up and checked :handle_subrequest_: called at the end of ``http_response_prepare()`` :handle_physical_path_: - called after the physical path is created and no other handler is + called after the physical path is created and no other handler is found for this request :handle_request_done_: called when the request is done @@ -73,7 +73,7 @@ fields in the connection structure are set. called after the connection_state_engine is left again and plugin internal handles have to be called :connection_reset_: - called if the connection structure has to be cleaned up + called if the connection structure has to be cleaned up Plugin Interface @@ -82,14 +82,14 @@ Plugin Interface \*_plugin_init `````````````` -Every plugin has a uniquely-named function which is called after the -plugin is loaded. It is used to set up the ``plugin`` structure with +Every plugin has a uniquely-named function which is called after the +plugin is loaded. It is used to set up the ``plugin`` structure with some useful data: - name of the plugin ``name`` -- all hooks +- all hooks -The field ``data`` and ``lib`` should not be touched in the init function. +The field ``data`` and ``lib`` should not be touched in the init function. ``lib`` is the library handler from dlopen and ``data`` will be the storage of the internal plugin data. @@ -99,9 +99,9 @@ of the internal plugin data. init ```` -The first real call of a plugin function is the init hook which is used -to set up the internal plugin data. The internal plugin is assigned the -``data`` field mentioned in the \*_plugin_init description. +The first real call of a plugin function is the init hook which is used +to set up the internal plugin data. The internal plugin is assigned the +``data`` field mentioned in the \*_plugin_init description. :returns: a pointer to the internal plugin data. @@ -109,7 +109,7 @@ to set up the internal plugin data. The internal plugin is assigned the cleanup ``````` -The cleanup hook is called just before the plugin is unloaded. It is meant +The cleanup hook is called just before the plugin is unloaded. It is meant to free all buffers allocated in ``init`` or somewhere else in the plugin which are still not freed and to close all handles which were opened and are not closed yet. @@ -120,16 +120,16 @@ are not closed yet. set_defaults ```````````` -set_defaults is your entry point into the configfile parsing. It should +set_defaults is your entry point into the configfile parsing. It should pass a list of options to ``config_insert_values`` and check if -the plugin configuration is valid. If it is not valid yet, it should +the plugin configuration is valid. If it is not valid yet, it should set useful defaults or return with HANDLER_ERROR and an error message. :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR will terminate lighttpd - + connection_reset ```````````````` @@ -137,9 +137,9 @@ called at the end of each request :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR on error - + handle_trigger `````````````` @@ -147,9 +147,9 @@ called once a second :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR on error - + handle_sighup ````````````` @@ -157,9 +157,9 @@ called if a SIGHUP is received (cycling logfiles, ...) :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR on error - + handle_uri_raw `````````````` @@ -168,9 +168,9 @@ called after uri_raw is set :returns: HANDLER_GO_ON if ok HANDLER_FINISHED if the final output is prepared - + HANDLER_ERROR on error - + handle_uri_clean ```````````````` @@ -179,9 +179,9 @@ called after uri.path is set :returns: HANDLER_GO_ON if ok HANDLER_FINISHED if the final output is prepared - + HANDLER_ERROR on error - + handle_docroot `````````````` @@ -190,9 +190,9 @@ called when a docroot is needed :returns: HANDLER_GO_ON if ok HANDLER_FINISHED if the final output is prepared - + HANDLER_ERROR on error - + handle_subrequest_start ``````````````````````` @@ -201,9 +201,9 @@ called after physical.path is set :returns: HANDLER_GO_ON if ok HANDLER_FINISHED if the final output is prepared - + HANDLER_ERROR on error - + handle_subrequest ````````````````` @@ -212,9 +212,9 @@ called if subrequest_start requested a COMEBACK or a WAIT_FOR_EVENT :returns: HANDLER_GO_ON if ok HANDLER_FINISHED if the final output is prepared - + HANDLER_ERROR on error - + handle_physical_path ```````````````````` @@ -223,9 +223,9 @@ called after physical.path is set :returns: HANDLER_GO_ON if ok HANDLER_FINISHED if the final output is prepared - + HANDLER_ERROR on error - + handle_request_done ``````````````````` @@ -234,9 +234,9 @@ called at the end of the request (logging, statistics, ...) :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR on error - + handle_connection_close ``````````````````````` @@ -244,9 +244,9 @@ called if the connection is terminated :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR on error - + handle_joblist `````````````` @@ -254,7 +254,7 @@ called if the state of the connection has changed :returns: HANDLER_GO_ON if ok - + HANDLER_ERROR on error - + diff --git a/doc/proxy.txt b/doc/proxy.txt index b8a3997..8ff5c3e 100644 --- a/doc/proxy.txt +++ b/doc/proxy.txt @@ -11,12 +11,12 @@ Module: mod_proxy :Revision: $Revision: 1.1 $ :abstract: - The proxy module a simplest way to connect lighttpd to + The proxy module a simplest way to connect lighttpd to java servers which have a HTTP-interface. - + .. meta:: :keywords: lighttpd, Proxy - + .. contents:: Table of Contents Description @@ -27,17 +27,17 @@ Description Options ======= -lighttpd provides the Proxy support via the proxy-module +lighttpd provides the Proxy support via the proxy-module (mod_proxy) which provides 2 options in the config-file: :proxy.debug: - a value between 0 and 65535 to set the debug-level in the - Proxy module. Currently only 0 and 1 are used. Use 1 to + a value between 0 and 65535 to set the debug-level in the + Proxy module. Currently only 0 and 1 are used. Use 1 to enable some debug output, 0 to disable it. :proxy.balance: might be one of 'hash', 'round-robin' or 'fair' (default). - + 'round-robin' choses another host for each request, 'hash' is generating a hash over the request-uri and makes sure that the same request URI is sent to always the same host. @@ -46,22 +46,22 @@ lighttpd provides the Proxy support via the proxy-module load-based, passive balancing. :proxy.server: - tell the module where to send Proxy requests to. Every - file-extension can have its own handler. Load-Balancing is + tell the module where to send Proxy requests to. Every + file-extension can have its own handler. Load-Balancing is done by specifying multiple handles for the same extension. - + structure of proxy.server section: :: - - ( <extension> => - ( + + ( <extension> => + ( ( "host" => <string> , "port" => <integer> ), ( "host" => <string> , "port" => <integer> ) ), - <extension> => ... + <extension> => ... ) - + :<extension>: is the file-extension or prefix (if started with "/") might empty to match all requests :"host": is ip of the proxy server @@ -69,9 +69,9 @@ lighttpd provides the Proxy support via the proxy-module server (default: 80) e.g.: :: - + proxy.server = ( ".jsp" => - ( ( + ( ( "host" => "10.0.0.242", "port" => 81 ) ) @@ -80,8 +80,8 @@ lighttpd provides the Proxy support via the proxy-module Example: ======== -Using lighttpd + mod_proxy in front of 8 Squids which handle the -caching of dynamic content for you. All requests for the host +Using lighttpd + mod_proxy in front of 8 Squids which handle the +caching of dynamic content for you. All requests for the host www.example.org should be forwarded to the proxy. All proxies listen on port 80 for requests. :: @@ -97,7 +97,7 @@ listen on port 80 for requests. :: ( "host" => "10.0.0.17" ) ) ) } -If one of the hosts goes down the all requests for this one server are +If one of the hosts goes down the all requests for this one server are moved equally to the other servers. If you want to know more about the algorithm used here google for 'Microsoft CARP'. diff --git a/doc/rc.lighttpd b/doc/rc.lighttpd index da0d244..4dd2a1e 100755 --- a/doc/rc.lighttpd +++ b/doc/rc.lighttpd @@ -11,7 +11,7 @@ # /(usr/)sbin/rcFOO # # LSB compliant service control script; see http://www.linuxbase.org/spec/ -# +# # System startup script for some example service or daemon FOO (template) # ### BEGIN INIT INFO @@ -23,7 +23,7 @@ # Description: Start FOO to allow XY and provide YZ # continued on second line by '#<TAB>' ### END INIT INFO -# +# # Note on Required-Start: It does specify the init script ordering, # not real dependencies. Depencies have to be handled by admin # resp. the configuration tools (s)he uses. @@ -64,7 +64,7 @@ rc_reset # 5 - program is not installed # 6 - program is not configured # 7 - program is not running -# +# # Note that starting an already running service, stopping # or restarting a not-running service as well as the restart # with force-reload (in case signalling is not supported) are @@ -76,7 +76,7 @@ case "$1" in ## Start daemon with startproc(8). If this fails ## the echo return value is set appropriate. - # NOTE: startproc returns 0, even if service is + # NOTE: startproc returns 0, even if service is # already running to match LSB spec. startproc $LIGHTTPD_BIN -f $LIGHTTPD_CONF_PATH @@ -94,7 +94,7 @@ case "$1" in rc_status -v ;; try-restart) - ## Stop the service and if this succeeds (i.e. the + ## Stop the service and if this succeeds (i.e. the ## service was running before), start it again. ## Note: try-restart is not (yet) part of LSB (as of 0.7.5) $0 status >/dev/null && $0 restart @@ -121,7 +121,7 @@ case "$1" in $0 start touch /var/run/lighttpd.pid rc_status -v - + ## Otherwise if it does not support reload: #rc_failed 3 #rc_status -v diff --git a/doc/redirect.txt b/doc/redirect.txt index cf7cd75..118ea8e 100644 --- a/doc/redirect.txt +++ b/doc/redirect.txt @@ -12,10 +12,10 @@ Module: mod_redirect :abstract: url redirection - + .. meta:: :keywords: lighttpd, redirect - + .. contents:: Table of Contents Description @@ -28,9 +28,9 @@ Options url.redirect redirects a set of URLs externally - + e.g. :: - + url.redirect = ( "^/show/([0-9]+)/([0-9]+)$" => "http://www.example.org/show.php?isdn=$1&page$2", "^/get/([0-9]+)/([0-9]+)$" => "http://www.example.org/get.php?isdn=$1&page$2" ) diff --git a/doc/rewrite.txt b/doc/rewrite.txt index e467022..09d4b66 100644 --- a/doc/rewrite.txt +++ b/doc/rewrite.txt @@ -12,10 +12,10 @@ Module: mod_rewrite :abstract: url rewrite - + .. meta:: :keywords: lighttpd, rewrite - + .. contents:: Table of Contents Description @@ -28,25 +28,25 @@ Options url.rewrite-once rewrites a set of URLs interally in the webserver BEFORE they are handled. - + e.g. :: - + url.rewrite-once = ( "<regex>" => "<relative-uri>" ) - + url.rewrite-repeat rewrites a set of URLs interally in the webserver BEFORE they are handled - + e.g. :: - + url.rewrite-repeat = ( "<regex>" => "<relative-uri>" ) -The options ``url.rewrite`` and ``url.rewrite-final`` were mapped to ``url.rewrite-once`` +The options ``url.rewrite`` and ``url.rewrite-final`` were mapped to ``url.rewrite-once`` in 1.3.16. Examples ======== -The regex is matching the full REQUEST_URI which is supplied by the user including +The regex is matching the full REQUEST_URI which is supplied by the user including query-string.:: url.rewrite-once = ( "^/id/([0-9]+)$" => "/index.php?id=$1", @@ -58,7 +58,7 @@ query-string.:: # * you can never change document-root by mod_rewrite # use mod_*host instead to make real mass-vhost - # request: http://any.domain.com/url/ + # request: http://any.domain.com/url/ # before rewrite: REQUEST_URI="/www/htdocs/url/" # and DOCUMENT_ROOT="/www/htdocs/" %0="www.domain.com" $1="url/" # after rewrite: REQUEST_URI="/www/htdocs/domain.com/url/" diff --git a/doc/rrdtool.txt b/doc/rrdtool.txt index 1ad5543..0e05cd3 100644 --- a/doc/rrdtool.txt +++ b/doc/rrdtool.txt @@ -50,7 +50,7 @@ Generating Graphs :: #!/bin/sh - + RRDTOOL=/usr/bin/rrdtool OUTDIR=/var/www/servers/www.example.org/pages/rrd/ INFILE=/var/www/lighttpd.rrd diff --git a/doc/scgi.txt b/doc/scgi.txt index dbb6371..eeb694c 100644 --- a/doc/scgi.txt +++ b/doc/scgi.txt @@ -13,10 +13,10 @@ Module: mod_scgi :abstract: SCGI is a fast and simplified CGI interface. It is mostly used by Python + WSGI. - + .. meta:: :keywords: lighttpd, FastCGI - + .. contents:: Table of Contents Description @@ -24,7 +24,7 @@ Description The SCGI module is heavily based on the FastCGI when it comes to configuration. Only the internal protocol between server -and client has been replaced. Please check the documentation +and client has been replaced. Please check the documentation of the FastCGI module for more information. History diff --git a/doc/secdownload.txt b/doc/secdownload.txt index bf0a481..570b911 100644 --- a/doc/secdownload.txt +++ b/doc/secdownload.txt @@ -114,19 +114,19 @@ Your application has to generate the correct URLs. The following sample code for PHP should be easily adaptable to any other language: :: <?php - + $secret = "verysecret"; $uri_prefix = "/dl/"; - + # filename $f = "/secret-file.txt"; - + # current timestamp $t = time(); - + $t_hex = sprintf("%08x", $t); $m = md5($secret.$f.$t_hex); - + # generate link printf('<a href="%s%s/%s%s">%s</a>', $uri_prefix, $m, $t_hex, $f, $f); @@ -139,7 +139,7 @@ The server has to be configured in the same way. The URI prefix and secret have to match: :: server.modules = ( ..., "mod_secdownload", ... ) - + secdownload.secret = "verysecret" secdownload.document-root = "/home/www/servers/download-area/" secdownload.uri-prefix = "/dl/" diff --git a/doc/security.txt b/doc/security.txt index 766fd34..ebbbf68 100644 --- a/doc/security.txt +++ b/doc/security.txt @@ -12,10 +12,10 @@ Module: core :abstract: lighttpd was developed with security in mind ... - + .. meta:: :keywords: lighttpd, security - + .. contents:: Table of Contents Description diff --git a/doc/setenv.txt b/doc/setenv.txt index c03474f..0238c10 100644 --- a/doc/setenv.txt +++ b/doc/setenv.txt @@ -12,10 +12,10 @@ Module: mod_setenv :abstract: mod_setenv is used to add request - + .. meta:: :keywords: lighttpd, skeleton - + .. contents:: Table of Contents Description diff --git a/doc/simple-vhost.txt b/doc/simple-vhost.txt index 4f8338f..d4b4db2 100644 --- a/doc/simple-vhost.txt +++ b/doc/simple-vhost.txt @@ -12,10 +12,10 @@ Module: mod_simple_vhost :abstract: virtual hosting - + .. meta:: :keywords: lighttpd, virtual hosting - + .. contents:: Table of Contents Description @@ -36,11 +36,11 @@ The document root for each vhost is built from three values: The complete document root is constructed either by :: server-root + hostname + document-root - + or if this path does not exist by :: server-root + default-host + document-root - + A small example should make this idea clear: :: /var/www/ @@ -52,7 +52,7 @@ A small example should make this idea clear: :: /var/www/servers/mail.example.org/ /var/www/servers/mail.example.org/lib/ /var/www/servers/mail.example.org/pages/ - + simple-vhost.server-root = "/var/www/servers/" simple-vhost.default-host = "www.example.org" simple-vhost.document-root = "pages" @@ -71,7 +71,7 @@ with one another. :: $HTTP["host"] == "news.example.org" { server.document-root = "/var/www/servers/news2.example.org/pages/" - } + } When ``news.example.org`` is requested, the ``server.document-root`` will be set to ``/var/www/servers/news2.example.org/pages/``, but @@ -91,7 +91,7 @@ To use conditionals together with simple-vhost, you should do this: :: $HTTP["host"] == "news.example.org" { server.document-root = "/var/www/servers/news2.example.org/pages/" - } + } It will enable simple vhosting for all hosts other than ``news.example.org``. @@ -100,10 +100,10 @@ Options simple-vhost.server-root root of the virtual host - + simple-vhost.default-host use this hostname if the requested hostname does not have its own directory - + simple-vhost.document-root path below the vhost directory diff --git a/doc/skeleton.txt b/doc/skeleton.txt index b1b01e6..13c6881 100644 --- a/doc/skeleton.txt +++ b/doc/skeleton.txt @@ -12,10 +12,10 @@ Module: mod_skeleton :abstract: a nice, short abstrace about the module - + .. meta:: :keywords: lighttpd, skeleton - + .. contents:: Table of Contents Description diff --git a/doc/spawn-php.sh b/doc/spawn-php.sh index 181eae2..83b7b16 100755 --- a/doc/spawn-php.sh +++ b/doc/spawn-php.sh @@ -49,6 +49,6 @@ E= for i in $ALLOWED_ENV; do E="$E $i=${!i}" done - + # clean the environment and set up a new one env - $E $EX diff --git a/doc/ssi.txt b/doc/ssi.txt index c65e7e1..8761416 100644 --- a/doc/ssi.txt +++ b/doc/ssi.txt @@ -13,10 +13,10 @@ Module: mod_ssi :abstract: The module for server-side includes provides a compatability layer for NSCA/Apache SSI. - + .. meta:: :keywords: lighttpd, ssi, Server-Side Includes - + .. contents:: Table of Contents Description @@ -73,4 +73,4 @@ which are not supported by this module for various reasons: - nested virtual - config.errmsg - echo.encoding - + diff --git a/doc/state.txt b/doc/state.txt index 5e8277b..d0768bc 100644 --- a/doc/state.txt +++ b/doc/state.txt @@ -14,10 +14,10 @@ Module: core This is a short summary of the state-engine which is driving the lighttpd webserver. It describes the basic concepts and the way the different parts of the server are connected. - + .. meta:: :keywords: lighttpd, state-engine - + .. contents:: Table of Contents Description @@ -52,72 +52,72 @@ and some may never be hit at all. reset connection (incl. close()) :close: close connection (handle lingering close) - + .. image:: state.png - + A simple GET request (green path) --------------------------------- - + The connection is idling in the 'connect' state waiting for a connection. As soon as the connection is set up we init the read-timer in 'reqstart' and start to read data from the network. As soon as we get the HTTP-request terminator (CRLFCRLF) we forward the header to the parser. - + The parsed request is handled by 'handlereq' and as soon as a decision out the request is made it is sent to 'respstart' to prepare the HTTP-response header. In the 'write' state the prepare content is sent out to the network. When everything is sent 'respend' is entered to log the -request and cleanup the environment. After the close() call the connection +request and cleanup the environment. After the close() call the connection is set back to the 'connect' state again. - + Keep-Alive (blue path) ---------------------- - + The Keep-Alive handling is implemented by going from the 'respend' directly to 'reqstart' without the close() and the accept() calls. - + POST requests (grey path) ------------------------- - + As requests might contain a request-body the state 'readpost' entered as soon as the header is parsed and we know how much data we expect. - + Pipelining ---------- - + HTTP/1.1 supportes pipelining (sending multiple requests without waiting for the response of the first request). This is handled transparently by the 'read' state. - + Unexpected errors (red path) ---------------------------- - + For really hard errors we use the 'error' state which resets the connection and can be call from every state. It is only use if there is no other way to handle the issue (e.g. client-side close of the connection). If possible we should use http-status 500 ('internal server error') and log the issue in the errorlog. - + If we have to take care of some data which is coming in after we ran into the error condition the 'close' state is used the init a half-close and read all the delay packet from the network. - + Sub-Requests (lightblue) ------------------------ - + The FastCGI, CGI, ... intergration is done by introducing a loop in 'handlereq' to handle all aspect which are neccesary to find out what has to be sent back to the client. - + Functions ========= Important functions used by the state-engine - + :state-engine: - ``connection_state_machine()`` - + :connect: - (nothing) diff --git a/doc/status.txt b/doc/status.txt index 5312176..fe3ee87 100644 --- a/doc/status.txt +++ b/doc/status.txt @@ -12,10 +12,10 @@ Module: mod_status :abstract: mod_status displays the server's status and configuration - + .. meta:: :keywords: lighttpd, server status - + .. contents:: Table of Contents Description @@ -47,8 +47,8 @@ cover it in a conditional. :: } Or require authorization: :: - - auth.require = ( "/server-status" => + + auth.require = ( "/server-status" => ( "realm" ... ) ) @@ -68,7 +68,7 @@ status-url you can get a text version which is simpler to parse. :: Uptime: 1234 BusyServers: 123 -Total Accesses is the number of handled requests, kBytes the overall outgoing +Total Accesses is the number of handled requests, kBytes the overall outgoing traffic, Uptime the uptime in seconds and BusyServers the number of currently active connections. @@ -88,7 +88,7 @@ status.status-url Example: status.status-url = "/server-status" status.enable-sort - + add JavaScript which allows client-side sorting for the connection overview Default: enable diff --git a/doc/userdir.txt b/doc/userdir.txt index 27a896a..10ba065 100644 --- a/doc/userdir.txt +++ b/doc/userdir.txt @@ -11,11 +11,11 @@ Module: mod_userdir :Revision: $Revision: 1.1 $ :abstract: - The userdir module ... - + The userdir module ... + .. meta:: :keywords: lighttpd, userdir - + .. contents:: Table of Contents Description @@ -29,7 +29,7 @@ building the classic mapping of: :: userdir.path = "public_html" - URL: http://www.example.org/~jan/index.html + URL: http://www.example.org/~jan/index.html Path: /home/jan/public_html/ To control which users should be able to use this feature you can set a list of usernames to include or exclude. @@ -48,7 +48,7 @@ Options userdir.path usually it should be set to "public_html" to take ~/public_html/ as the document root - + Default: empty (document root is the home directory) Example: :: diff --git a/doc/webdav.txt b/doc/webdav.txt index 7b5259e..b10012f 100644 --- a/doc/webdav.txt +++ b/doc/webdav.txt @@ -12,17 +12,17 @@ Module: mod_webdav :abstract: WebDAV module for lighttpd - + .. meta:: :keywords: lighttpd, webdav - + .. contents:: Table of Contents Description =========== The WebDAV module is a very minimalistic implementation of RFC 2518. -Minimalistic means that not all operations are implemented yet. +Minimalistic means that not all operations are implemented yet. So far we have @@ -32,7 +32,7 @@ So far we have * DELETE * PUT -and the usual GET, POST, HEAD from HTTP/1.1. +and the usual GET, POST, HEAD from HTTP/1.1. So far, mounting a WebDAV resource into Windows XP works and the basic litmus tests are passed. @@ -41,9 +41,9 @@ Options ======= webdav.activate - If you load the webdav module, the WebDAV functionality has to be + If you load the webdav module, the WebDAV functionality has to be enabled for the directories you want to provide to the user. - + Default: disable webdav.is-readonly |