10 files changed, 605 insertions, 450 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6be113b..cfe4033 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -86,7 +86,7 @@ EXTRA_DIST=lighttpd.conf lighttpd.user \
 	oldstyle.css \
 	$(DOCS)
 
-%.html: %.txt
+.txt.html:
 	rst2html $^ > $@
 
 
diff --git a/doc/Makefile.in b/doc/Makefile.in
index aa2761d..bba1e9f 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -1,8 +1,8 @@
-# Makefile.in generated by automake 1.10 from Makefile.am.
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
 # @configure_input@
 
 # Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004, 2005, 2006  Free Software Foundation, Inc.
+# 2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
 # This Makefile.in is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
 # with or without modifications, as long as this notice is preserved.
@@ -72,6 +72,7 @@ CYGPATH_W = @CYGPATH_W@
 DEFS = @DEFS@
 DEPDIR = @DEPDIR@
 DL_LIB = @DL_LIB@
+DSYMUTIL = @DSYMUTIL@
 ECHO = @ECHO@
 ECHO_C = @ECHO_C@
 ECHO_N = @ECHO_N@
@@ -106,6 +107,7 @@ MKDIR_P = @MKDIR_P@
 MYSQL_CONFIG = @MYSQL_CONFIG@
 MYSQL_INCLUDE = @MYSQL_INCLUDE@
 MYSQL_LIBS = @MYSQL_LIBS@
+NMEDIT = @NMEDIT@
 OBJEXT = @OBJEXT@
 PACKAGE = @PACKAGE@
 PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
@@ -118,6 +120,7 @@ PCRECONFIG = @PCRECONFIG@
 PCRE_LIB = @PCRE_LIB@
 PKG_CONFIG = @PKG_CONFIG@
 RANLIB = @RANLIB@
+SED = @SED@
 SENDFILE_LIB = @SENDFILE_LIB@
 SET_MAKE = @SET_MAKE@
 SHELL = @SHELL@
@@ -275,6 +278,7 @@ EXTRA_DIST = lighttpd.conf lighttpd.user \
 all: all-am
 
 .SUFFIXES:
+.SUFFIXES: .html .txt
 $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am  $(am__configure_deps)
 	@for dep in $?; do \
 	  case '$(am__configure_deps)' in \
@@ -488,7 +492,7 @@ uninstall-man: uninstall-man1
 	ps ps-am uninstall uninstall-am uninstall-man uninstall-man1
 
 
-%.html: %.txt
+.txt.html:
 	rst2html $^ > $@
 
 html: $(HTMLDOCS)
diff --git a/doc/authentication.txt b/doc/authentication.txt
index c375ece..edc2b2b 100644
--- a/doc/authentication.txt
+++ b/doc/authentication.txt
@@ -7,8 +7,8 @@ Module: mod_auth
 ----------------
 
 :Author: Jan Kneschke
-:Date: $Date: 2006-10-04 15:26:23 +0200 (Wed, 04 Oct 2006) $
-:Revision: $Revision: 1371 $
+:Date: $Date$
+:Revision: $Revision$
 
 :abstract:
   The auth module provides ...
diff --git a/doc/compress.txt b/doc/compress.txt
index a739c42..14fbc2d 100644
--- a/doc/compress.txt
+++ b/doc/compress.txt
@@ -6,12 +6,6 @@ Output Compression
 Module: mod_compress
 --------------------
 
-:Author: Jan Kneschke
-:Date: $Date: 2004/08/29 09:43:49 $
-:Revision: $Revision: 1.1 $
-
-:abstract:
-  a nice, short abstrace about the module
 
 .. meta::
   :keywords: lighttpd, compress
@@ -22,16 +16,57 @@ Description
 ===========
 
 Output compression reduces the network load and can improve the overall
-throughput of the webserver.
+throughput of the webserver. All major http-clients support compression by
+announcing it in the Accept-Encoding header. This is used to negotiate the
+most suitable compression method. We support deflate, gzip and bzip2.
+
+deflate (RFC1950, RFC1951) and gzip (RFC1952) depend on zlib while bzip2
+depends on libbzip2. bzip2 is only supported by lynx and some other console
+text-browsers.
+
+We currently limit to compression support to static files.
+
+Caching
+-------
+
+mod_compress can store compressed files on disk to optimize the compression
+on a second request away. As soon as compress.cache-dir is set the files are
+compressed.
+
+(You will need to create the cache directory if it doesn't already exist. The web server will not do this for you.  The directory will also need the proper ownership.  For Debian/Ubuntu the user and group ids should both be www-data.)
+
+The names of the cache files are made of the filename, the compression method
+and the etag associated to the file.
 
-Only static content is supported up to now.
+Cleaning the cache is left to the user. A cron job deleting files older than
+10 days could do it: ::
 
-The server negotiates automaticly which compression method is used.
-Supported are gzip, deflate, bzip.
+  find /var/www/cache -type f -mtime +10 | xargs -r rm
+
+Limitations
+-----------
+
+The module limits the compression of files to files smaller than 128 MByte and
+larger than 128 Byte.
+
+The lower limit is set as small files tend to become larger by compressing due
+to the compression headers, the upper limit is set to work sensibly with
+memory and cpu-time.
+
+Directories containing a tilde ('~') are not created automatically (See ticket
+#113). To enable compression for user dirs you have to create the directories
+by hand in the cache directory.
 
 Options
 =======
 
+compress.allowed-encodings
+  override default set of allowed encodings
+
+  e.g.: ::
+
+    compress.allowed-encodings = ("bzip2", "gzip", "deflate")
+
 compress.cache-dir
   name of the directory where compressed content will be cached
 
@@ -47,20 +82,111 @@ compress.cache-dir
   Default: not set, compress the file for every request
 
 compress.filetype
-  mimetypes where might get compressed
+  mimetypes which might get compressed
 
   e.g.: ::
 
     compress.filetype           = ("text/plain", "text/html")
 
+  Keep in mind that compressed JavaScript and CSS files are broken in some
+  browsers. Not setting any filetypes will result in no files being compressed.
+
+  NOTE: You have to specify the full mime-type! If you also define a charset, for example, you have to use "text/plain; charset=utf-8" instead of just "text/plain".
+
   Default: not set
 
+compress.max-filesize
+  maximum size of the original file to be compressed kBytes.
+
+  This is meant to protect the server against DoSing as compressing large
+  (let's say 1Gbyte) takes a lot of time and would delay the whole operation
+  of the server.
+
+  There is a hard upper limit of 128Mbyte.
+
+  Default: unlimited (== hard-limit of 128MByte)
+
+Display compressed files
+========================
+
+If you enable mod_compress, and you want to force clients to uncompress and display compressed text files, please force mimetype to nothing.
+Exemple :
+If you want to add headers for uncompress and display diff.gz files , add this section in your conf : ::
+
+  $HTTP["url"] =~ "\.diff\.gz" {
+    setenv.add-response-header = ( "Content-Encoding" => "gzip" )
+    mimetype.assign = ()
+  }
+
 
 Compressing Dynamic Content
 ===========================
 
+PHP
+---
+
 To compress dynamic content with PHP please enable ::
 
   zlib.output_compression = 1
+  zlib.output_handler = On
 
 in the php.ini as PHP provides compression support by itself.
+
+mod_compress of lighttpd 1.5 r1992 may not set correct Content-Encoding with php-fcgi. A solution to that problem would be:
+
+1.disable mod_compress when request a php file::
+
+    $HTTP["url"] !~ "\.php$" {
+    	compress.filetype = ("text/plain", "text/html", "text/javascript", "text/css", "text/xml")
+    }
+
+2.enable mod_setenv of your lighttpd::
+
+    server.modules  += ( "mod_setenv" )
+
+3.manually set Content-Encoding::
+
+    $HTTP["url"] =~ "\.php$" {
+  	setenv.add-response-header  = ( "Content-Encoding" => "gzip")
+    }
+
+
+TurboGears
+----------
+
+To compress dynamic content with TurboGears please enable ::
+
+  [/]
+  gzip_filter.on = True
+  gzip_filter.mime_types = ["application/x-javascript", "text/javascript", "text/html", "text/css", "text/plain"]
+
+in the config/app.cfg file in your TurboGears application.  The above lines should already be in the file.  You just need to remove the comment symbol in front of the lines to make them active.
+
+Django
+------
+
+To compress dynamic content with Django please enable the GZipMiddleware ::
+
+  MIDDLEWARE_CLASSES = (
+      'django.middleware.gzip.GZipMiddleware',
+      ...
+  )
+
+in the settings.py file in your Django project.
+
+Catalyst
+--------
+
+To compress dynamic content with Perl/Catalyst, simply use the Catalyst::Plugin::Compress::Gzip module available on CPAN ::
+
+  use Catalyst qw(
+      Compress::Gzip
+      ...
+  );
+
+in your main package (MyApp.pm). Further configuration is not required.
+
+}}}
+
+
+
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 8aac874..ed836ec 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -7,8 +7,8 @@ Module: core
 ------------
 
 :Author: Jan Kneschke
-:Date: $Date: 2007-11-04 17:53:17 +0100 (Sun, 04 Nov 2007) $
-:Revision: $Revision: 2012 $
+:Date: $Date$
+:Revision: $Revision$
 
 :abstract:
   the layout of the configuration file
@@ -90,13 +90,21 @@ $HTTP["scheme"]
 $HTTP["host"]
   match on host
 $HTTP["useragent"]
+$HTTP["user-agent"]
   match on useragent
 $HTTP["referer"]
   match on referer
+$HTTP["method"]
+  math on the http method
 $HTTP["url"]
   match on url
+$HTTP["query-string"]
+  match on the (not decoded) query-string
 $HTTP["remoteip"]
+$HTTP["remote-ip"]
   match on the remote IP or a remote Network
+$HTTP["language"]
+  match on the Accept-Language header
 $SERVER["socket"]
   match on socket. Value must be on the format "ip:port" where ip is an IP
   address and port a port number. Only equal match (==) is supported.
@@ -513,3 +521,6 @@ debug.log-file-not-found
 
 debug.log-request-handling
   default: disabled
+
+debug.log-ssl-noise
+  default: disabled
diff --git a/doc/lighttpd.conf b/doc/lighttpd.conf
index 7fa7471..028a75b 100644
--- a/doc/lighttpd.conf
+++ b/doc/lighttpd.conf
@@ -174,6 +174,8 @@ static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
 
 ## virtual directory listings
 #dir-listing.activate       = "enable"
+## select encoding for directory listings
+#dir-listing.encoding        = "utf-8"
 
 ## enable debugging
 #debug.log-request-header   = "enable"
diff --git a/doc/magnet.txt b/doc/magnet.txt
index 9d7697a..0559174 100644
--- a/doc/magnet.txt
+++ b/doc/magnet.txt
@@ -1,429 +1,429 @@
-{{{
-#!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
+{{{
+#!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
+
+}}}
diff --git a/doc/redirect.txt b/doc/redirect.txt
index cf7cd75..ec54731 100644
--- a/doc/redirect.txt
+++ b/doc/redirect.txt
@@ -39,3 +39,9 @@ url.redirect
     $HTTP["host"] =~ "^www\.(.*)" {
       url.redirect = ( "^/(.*)" => "http://%1/$1" )
     }
+
+Warning
+=======
+
+Do NOT use mod_redirect to protect specific urls, as the original url passed from the client
+is matched against your rules, for example strings like "/abc/../xyz%2f/path".
diff --git a/doc/rewrite.txt b/doc/rewrite.txt
index e467022..a139069 100644
--- a/doc/rewrite.txt
+++ b/doc/rewrite.txt
@@ -43,6 +43,12 @@ url.rewrite-repeat
 The options ``url.rewrite`` and ``url.rewrite-final`` were mapped to ``url.rewrite-once``
 in 1.3.16.
 
+Warning
+=======
+
+Do NOT use mod_rewrite to protect specific urls, as the original url passed from the client
+is matched against your rules, for example strings like "/abc/../xyz%2f/path".
+
 Examples
 ========
 
diff --git a/doc/userdir.txt b/doc/userdir.txt
index 27a896a..7a62f06 100644
--- a/doc/userdir.txt
+++ b/doc/userdir.txt
@@ -46,10 +46,10 @@ In case your mapping is independent of /etc/passwd you can use
 Options
 =======
 
-userdir.path
+userdir.path (required option)
   usually it should be set to "public_html" to take ~/public_html/ as the document root
 
-  Default: empty (document root is the home directory)
+  Default: unset (mod_userdir disabled; set it to "" if you want the home directory to be the document root as it was the default before 1.4.19)
   Example: ::
 
     userdir.path = "public_html"