From 3c5de44781b778f524a796f56262389527778e0e Mon Sep 17 00:00:00 2001 From: Jan Kneschke Date: Tue, 20 Dec 2005 14:02:44 +0000 Subject: [PATCH] updated the latest changes and fixed the typos and wording in the docs (Ryan Schmidt) git-svn-id: svn://svn.lighttpd.net/lighttpd/branches/lighttpd-merge-1.4.x@895 152afb58-edef-0310-8abb-c4023f1b3aa9 --- NEWS | 3 + doc/mysqlvhost.txt | 19 +++--- doc/performance.txt | 130 ++++++++++++++++++++-------------------- doc/plugins.txt | 30 +++++----- doc/rrdtool.txt | 16 ++--- doc/scgi.txt | 2 +- doc/secdownload.txt | 86 +++++++++++++------------- doc/security.txt | 4 +- doc/setenv.txt | 4 +- doc/simple-vhost.txt | 38 ++++++------ doc/ssi.txt | 6 +- doc/ssl.txt | 27 +++++---- doc/status.txt | 57 +++++++++++++++++- doc/traffic-shaping.txt | 32 +++++----- doc/trigger_b4_dl.txt | 18 +++--- doc/userdir.txt | 16 ++--- doc/webdav.txt | 14 ++--- 17 files changed, 281 insertions(+), 221 deletions(-) diff --git a/NEWS b/NEWS index 93b92d81..fdb14636 100644 --- a/NEWS +++ b/NEWS @@ -6,8 +6,11 @@ NEWS - 1.4.9 - 2005-..-.. * added server.core-files option (sandy ) + * added docs for mod_status * fixed 100% cpu loops in mod_cgi ("sandy" ) * fixed handling for secure-download.timeout (jamis@37signals.com) + * fixed IE bug in content-charset in the output of mod_dirlisting (sniper@php.net) + * fixed typos and language in the docs (ryan-2005@ryandesign.com) - 1.4.8 - 2005-11-23 diff --git a/doc/mysqlvhost.txt b/doc/mysqlvhost.txt index 93a08dc9..9a869a19 100644 --- a/doc/mysqlvhost.txt +++ b/doc/mysqlvhost.txt @@ -1,6 +1,5 @@ - ==================== -MySQL based vhosting +MySQL-based vhosting ==================== ----------------------- @@ -12,20 +11,20 @@ Module: mod_mysql_vhost :Revision: $Revision: 1.1 $ :abstract: - This module provides virtual hosts (vhosts) based on a MySQL table - + This module provides virtual hosts (vhosts) based on a MySQL table + .. meta:: :keywords: lighttpd, mysql, vhost - + .. contents:: Table of Contents Description =========== -With MySQL based vhosting you can put the information where to look for a -document-root of a given host into a MySQL database. +With MySQL-based vhosting you can store the path to a given host's +document root in a MySQL database. -.. note:: Keep in mind that only one vhost-module should be active at a time. +.. note:: Keep in mind that only one vhost module should be active at a time. Don't mix mod_simple_vhost with mod_mysql_vhost. Options @@ -38,8 +37,8 @@ Example: :: mysql-vhost.pass = "secret" mysql-vhost.sock = "/var/mysql.lighttpd.sock" mysql-vhost.sql = "SELECT docroot FROM domains WHERE domain='?'" - - + + MySQL setup: :: GRANT SELECT ON lighttpd.* TO lighttpd@localhost IDENTIFIED BY 'secret'; diff --git a/doc/performance.txt b/doc/performance.txt index eb7a8351..410532e5 100644 --- a/doc/performance.txt +++ b/doc/performance.txt @@ -12,10 +12,10 @@ Module: core :abstract: handling performance issues in lighttpd - + .. meta:: :keywords: lighttpd, performance - + .. contents:: Table of Contents Description @@ -32,9 +32,9 @@ HTTP Keep-Alive --------------- Disabling keep-alive might help your server if you suffer from a large -number of open file-descriptors. +number of open file descriptors. -The defaults fo the server is: :: +The defaults for the server are: :: server.max-keep-alive-requests = 128 server.max-keep-alive-idle = 30 @@ -42,7 +42,7 @@ The defaults fo the server is: :: server.max-write-idle = 360 handling 128 keep-alive requests in a row on a single connection, waiting 30 seconds -before a unused keep-alive connection get dropped by lighttpd. +before an unused keep-alive connection gets dropped by lighttpd. If you handle several connections at once under a high load (let's assume 500 connections in parallel for 24h) you might run into the out-of-fd problem described below. :: @@ -50,22 +50,22 @@ in parallel for 24h) you might run into the out-of-fd problem described below. : server.max-keep-alive-requests = 4 server.max-keep-alive-idle = 4 -would release the connections earlier and would free file-descriptors without a to large -performance loss. +would release the connections earlier and would free file descriptors without a +detrimental performance loss. -Disabling keep-alive completly is the last choice if you are still short in filedescriptors: :: +Disabling keep-alive completely is the last resort if you are still short on file descriptors: :: server.max-keep-alive-requests = 0 Event Handlers -------------- -The first one is the Event Handler which cares about notifying the server -that one of the connections is ready to send or to recieve. As you can see -every OS has at least the select() call which has some limitations. +The first one is the Event Handler which takes care of notifying the server +that one of the connections is ready to send or recieve. As you can see, +every OS has at least the select() call which has some limitations. ============ ========== =============== -OS Method Config-Value +OS Method Config Value ============ ========== =============== all select select Unix poll poll @@ -76,151 +76,153 @@ FreeBSD, ... kqueue freebsd-kqueue ============ ========== =============== -For more infomation in this topic take a look at http://www.kegel.com/c10k.html +For more information on this topic take a look at http://www.kegel.com/c10k.html Configuration ````````````` -The event-handler can be set by specifying the 'Config-Value' from above +The event handler can be set by specifying the 'Config Value' from above in the ``server.event-handler`` variable e.g.: :: server.event-handler = "linux-sysepoll" - + Network Handlers ---------------- The basic network interface for all platforms at the syscalls read() and -write(). Each modern OS provides its own syscall to help network servers -to transfer files as fast as possible. +write(). Every modern OS provides its own syscall to help network servers +transfer files as fast as possible. -If you want to send out a file from the webserver it does make any sense +If you want to send out a file from the webserver, it doesn't make any sense to copy the file into the webserver just to write() it back into a socket in the next step. sendfile() minimizes the work in the application and pushes a file directly -into the network card (idealy spoken). +into the network card (ideally). -lighttpd supports all major platform specific calls: +lighttpd supports all major platform-specific calls: -========== ========== -OS Method ========== ========== -all write -Unix writev -Linux 2.4+ sendfile -Linux 2.6+ sendfile64 +OS Method +========== ========== +all write +Unix writev +Linux 2.4+ sendfile +Linux 2.6+ sendfile64 Solaris sendfilev FreeBSD sendfile -========== ========== +========== ========== -They are selected automaticly on compile-time. If you have problems check +They are selected automatically at compile-time. If you have problems, check ./src/network_backend.h and disable the corresponding USE\_... define. Max Connections --------------- -As lighttpd is a single-threaded server its main resource limit is the -number of file-descriptors which is (on most systems) set to 1024 by default. +As lighttpd is a single-threaded server, its main resource limit is the +number of file descriptors, which is set to 1024 by default (on most systems). If you are running a high-traffic site you might want to increase this limit by setting :: server.max-fds = 2048 - + This only works if lighttpd is started as root. Out-of-fd condition ------------------- -As fds are used for tcp/ip sockets, files, directories, ... a simple request -for a PHP page might result in using 3 fds: +Since file descriptors are used for TCP/IP sockets, files and directories, +a simple request for a PHP page might result in using 3 file descriptors: 1. the TCP/IP socket to the client 2. the TCP/IP and Unix domain socket to the FastCGI process -3. the filehandle to the file in the document-root to check if it is really existing +3. the filehandle to the file in the document root to check if it exists -If lighttpd runs out of file-descriptors it will stop accepting new -connections for while to use the currently available fds (file-descriptors) -to handle the currently running requests. +If lighttpd runs out of file descriptors, it will stop accepting new +connections for awhile to use the existing file descriptors to handle the +currently-running requests. -If more than 90% of the fds are used the the handling of new connections is -disabled, if it dropes below 80% again new connection will accepted again. +If more than 90% of the file descriptors are used then the handling of new +connections is disabled. If it drops below 80% again new connections will +be accepted again. Under some circumstances you will see :: ... accept() failed: Too many open files -in the error-log. This tells you the you had to many new requests at once -and lighttpd could not disable the incomming connections soon enough. The -connection is drop and the client will get a error-message like 'connection -failed'. This is very rare and might only occur in test-setups. +in the error log. This tells you there were too many new requests at once +and lighttpd could not disable the incoming connections soon enough. The +connection was dropped and the client received an error message like 'connection +failed'. This is very rare and might only occur in test setups. -Increasing the ``server.max-fds`` limit will reduce the propability of this +Increasing the ``server.max-fds`` limit will reduce the probability of this problem. stat() cache ============ -A stat(2) can be expensive, caching it saves time adn context-switches.. +A stat(2) can be expensive; caching it saves time and context switches. -Instead of stat() for the existence of the file you can stat() it once and -monitor the directory the file is in for modifications. As long as the -directiry doesn't change, the files in it are all the same. +Instead of using stat() every time to check for the existence of a file +you can stat() it once and monitor the directory the file is in for +modifications. As long as the directory doesn't change, the files in it +must all still be the same. With the help of FAM or gamin you can use kernel events to assure that -your stat-cache is up to date. :: +your stat cache is up to date. :: server.stat-cache-engine = "fam" # either fam, simple or disabled -Plattform Specific Notes -======================== +Platform-Specific Notes +======================= Linux ----- -For Linux 2.4.x should should think about compiling lighttpd with the option -``--disable-lfs`` to disable the support for files larger than 2Gb. lighttpd will +For Linux 2.4.x you should think about compiling lighttpd with the option +``--disable-lfs`` to disable the support for files larger than 2GB. lighttpd will fall back to the ``writev() + mmap()`` network calls which is ok, but not as -fast as possible but support files larger than 2Gb. +fast as possible but support files larger than 2GB. Disabling the TCP options reduces the overhead of each TCP packet and might help to get the last few percent of performance out of the server. -- net.ipv4.tcp_sack = 0 +- net.ipv4.tcp_sack = 0 - net.ipv4.tcp_timestamps = 0 Increasing the TCP send and receive buffers will increase the performance a -lot if (and only if) you have a lot large files to send. +lot if (and only if) you have a lot of large files to send. - net.ipv4.tcp_wmem = 4096 65536 524288 - net.core.wmem_max = 1048576 -If you have a lot large file uploads increasing the receive buffers will help. +If you have a lot of large file uploads, increasing the receive buffers will help. - net.ipv4.tcp_rmem = 4096 87380 524288 - net.core.rmem_max = 1048576 -Keep in mind that the buffers have to multiplied by server.max-fds and be -allocated in the Kernel area. Be carefull with that. +Keep in mind that the buffers have to be multiplied by server.max-fds and be +allocated in the kernel area. Be careful with that. FreeBSD ------- -On FreeBSD you might gain some performance by enabling accept-filters. Just +On FreeBSD you might gain some performance by enabling accept filters. Just compile your kernel with: :: options ACCEPT_FILTER_HTTP -For more ideas in tuning FreeBSD read: tuning(7) +For more ideas about tuning FreeBSD read: tuning(7) Reducing the recvspace should always be ok if the server only handles HTTP requests without large uploads. Increasing the sendspace would reduce the -system-load if you have a lot large files to be sent, but keep in mind that -you to provide the memory in kernel for each connection. 1024 * 64k would mean -64M of kernel-ram. Keep this in mind. +system load if you have a lot of large files to be sent, but keep in mind that +you have to provide the memory in the kernel for each connection. 1024 * 64KB +would mean 64MB of kernel RAM. Keep this in mind. - net.inet.tcp.recvspace = 4096 diff --git a/doc/plugins.txt b/doc/plugins.txt index 8a755fea..91c81fd3 100644 --- a/doc/plugins.txt +++ b/doc/plugins.txt @@ -11,8 +11,8 @@ Module: core :Revision: $Revision: 1.1 $ :abstract: - The plugin interface is the integral part of lighttpd provide - a flexible way to add specific functionality to lighttpd. + The plugin interface is an integral part of lighttpd which + provides a flexible way to add specific functionality to lighttpd. .. meta:: :keywords: lighttpd, plugins @@ -22,9 +22,9 @@ Module: core Description =========== -Plugins allow you to enhance to functionality of lighttpd without -changing the core of the webserver. They can be loaded at startup-time -and can change hardly any aspect of the behaviour of the webserver. +Plugins allow you to enhance the functionality of lighttpd without +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 ------------------- @@ -49,17 +49,17 @@ Serverwide hooks Connectionwide hooks ```````````````````` -Most of these hooks are call in ``http_response_prepare()`` after some -field in the connection structure are set. +Most of these hooks are called in ``http_response_prepare()`` after some +fields in the connection structure are set. :handle_uri_raw_: called after uri.path_raw, uri.authority and uri.scheme are set :handle_uri_clean_: - called after uri.path (a clean uri without .. and %20) is set + 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 :handle_subrequest_start_: - called if the physical path is setup and checked + called if the physical path is set up and checked :handle_subrequest_: called at the end of ``http_response_prepare()`` :handle_physical_path_: @@ -82,9 +82,9 @@ Plugin Interface \*_plugin_init `````````````` -Every plugin has a uniquely named function which is called after the -plugin is loaded. It is used to setup the ``plugin`` structure with -some usefull data: +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 @@ -99,7 +99,7 @@ of the internal plugin data. init ```` -The first real call of a plugin function is the init-hook which is used +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. @@ -123,12 +123,12 @@ set_defaults 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 -set usefull defaults or return with HANDLER_ERROR and an error message. +set useful defaults or return with HANDLER_ERROR and an error message. :returns: HANDLER_GO_ON if ok - HANDLER_ERROR will terminated lighttpd + HANDLER_ERROR will terminate lighttpd connection_reset ```````````````` diff --git a/doc/rrdtool.txt b/doc/rrdtool.txt index ce0145c4..0e05cd36 100644 --- a/doc/rrdtool.txt +++ b/doc/rrdtool.txt @@ -12,17 +12,17 @@ Module: mod_rrdtool :abstract: mod_rrdtool is used to monitor the traffic and load on the webserver - + .. meta:: :keywords: lighttpd, skeleton - + .. contents:: Table of Contents Description =========== RRD_ is a system to store and display time-series data (i.e. network -bandwidth, machine-room temperature, server load average). +bandwidth, machine-room temperature, server load average). .. _RRD: http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/ @@ -33,17 +33,17 @@ rrdtool.binary path to the rrdtool binary e.g.: :: - + rrdtool.binary = "/usr/bin/rrdtool" rrdtool.db-name - filename of the rrd-database. Make sure that doesn't exists - before the first run as lighttpd has to create the DB for you. + filename of the rrd-database. Make sure that doesn't exist + before the first run, as lighttpd has to create the DB for you. e.g.: :: - + rrdtool.db-name = "/var/www/lighttpd.rrd" - + Generating Graphs ================= diff --git a/doc/scgi.txt b/doc/scgi.txt index ff849fe0..eeb694cd 100644 --- a/doc/scgi.txt +++ b/doc/scgi.txt @@ -25,7 +25,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 -of the fastcgi module for more information. +of the FastCGI module for more information. History ======= diff --git a/doc/secdownload.txt b/doc/secdownload.txt index fb946eda..570b9112 100644 --- a/doc/secdownload.txt +++ b/doc/secdownload.txt @@ -11,12 +11,12 @@ Module: mod_secdownload :Revision: $Revision: 1.1 $ :abstract: - authenticated file requests and a counter measurement against + authenticated file requests and a countermeasure against deep-linking can be achieved easily by using mod_secdownload - + .. meta:: :keywords: lighttpd, secure, fast, downloads - + .. contents:: Table of Contents Options @@ -32,77 +32,77 @@ Options Description =========== -there are multiple way to handle secured download mechanisms: +there are multiple ways to handle secured download mechanisms: -1. use the webserver and the internal HTTP-authentication -2. use the application to authenticate and send the file +1. use the webserver and the internal HTTP authentication +2. use the application to authenticate and send the file through the application - -Both way have limitations: + +Both ways have limitations: webserver: -- ``+`` fast download -- ``+`` no additional system load -- ``-`` unflexible authentication handling - +- ``+`` fast download +- ``+`` no additional system load +- ``-`` inflexible authentication handling + application: - ``+`` integrated into the overall layout - ``+`` very flexible permission management -- ``-`` the download occupies a application thread/process - -A simple way to combine the two way could be: +- ``-`` the download occupies an application thread/process + +A simple way to combine the two ways could be: 1. app authenticates user and checks permissions to download the file. -2. app redirectes user the file accessable by the webserver - for further downloading -3. the webserver transfers the file to the user +2. app redirects user to the file accessable by the webserver + for further downloading. +3. the webserver transfers the file to the user. As the webserver doesn't know anything about the permissions -used in the app the resulting URL would be available to every -user who knows the URL. - -mod_secdownload removes this problem by introducing a way to +used in the app, the resulting URL would be available to every +user who knows the URL. + +mod_secdownload removes this problem by introducing a way to authenticate a URL for a specified time. The application has to generate a token and a timestamp which are checked by the -webserver before it allows the file to be downloaded by the +webserver before it allows the file to be downloaded by the webserver. The generated URL has to have the format: / - is a MD5 of + is an MD5 of 1. a secret string (user supplied) -2. (startes with /) +2. (starts with /) 3. -As you can see the token is not bound to the user at all. The -only limiting factor is the timestamp which is used to +As you can see, the token is not bound to the user at all. The +only limiting factor is the timestamp which is used to invalidate the URL after a given timeout (secdownload.timeout). .. Note:: - Be sure to choose a another secret then used in the examples - as this is the only part of the token that is not known to - the user. - - - -If the user tries to fake the URL by choosing a random token + Be sure to choose a another secret than the one used in the + examples, as this is the only part of the token that is not + known to the user. + + + +If the user tries to fake the URL by choosing a random token, status 403 'Forbidden' will be sent out. -If the timeout is reached status 408 'Request Timeout' will be -sent (this not really standard conforming but should do the -trick). +If the timeout is reached, status 408 'Request Timeout' will be +sent. (This does not really conform to the standard, but should +do the trick). -If token and timeout are valid the is taken and -appended at the configured (secdownload.document-root) and -passed to the normal internal file transfer functionality. -This might lead to status 200 or 404. +If token and timeout are valid, the is appended to +the configured (secdownload.document-root) and passed to the +normal internal file transfer functionality. This might lead to +status 200 or 404. Example ======= @@ -135,8 +135,8 @@ code for PHP should be easily adaptable to any other language: :: Webserver --------- -The server has to configured in the same way. The uri-prefix and secret have -to match: :: +The server has to be configured in the same way. The URI prefix and +secret have to match: :: server.modules = ( ..., "mod_secdownload", ... ) diff --git a/doc/security.txt b/doc/security.txt index d4e9147c..ebbbf686 100644 --- a/doc/security.txt +++ b/doc/security.txt @@ -33,7 +33,7 @@ Limiting POST requests System Security --------------- -Running daemons as root will full privileges is a bad idea in general. +Running daemons as root with full privileges is a bad idea in general. lighttpd runs best without any extra privileges and runs perfectly in chroot. Change Root @@ -41,7 +41,7 @@ Change Root server.chroot = "..." -Drop root-privileges +Drop root privileges ```````````````````` server.username = "..." diff --git a/doc/setenv.txt b/doc/setenv.txt index b04b0838..0238c107 100644 --- a/doc/setenv.txt +++ b/doc/setenv.txt @@ -31,7 +31,7 @@ setenv.add-environment setenv.add-response-header - add a header to the HTTP-response sent to the client + adds a header to the HTTP response sent to the client setenv.add-request-header - add a header to the HTTP-request that was received by the client + adds a header to the HTTP request that was received from the client diff --git a/doc/simple-vhost.txt b/doc/simple-vhost.txt index b0776f02..d4b4db20 100644 --- a/doc/simple-vhost.txt +++ b/doc/simple-vhost.txt @@ -23,17 +23,17 @@ Description Simple assumption: -Every virtual host is in a direction below a base directory in a path that -is the same as the name of the vhost. Below this vhost-path might be a -extra directory which is the document-root of the vhost. +Every virtual host is in a directory below a base directory in a path that +is the same as the name of the vhost. Below this vhost path might be an +extra directory which is the document root of the vhost. -The document-root for each vhost is build from three values: +The document root for each vhost is built from three values: - server-root - hostname - document-root -Either the absolute documentroot is build by :: +The complete document root is constructed either by :: server-root + hostname + document-root @@ -41,7 +41,7 @@ or if this path does not exist by :: server-root + default-host + document-root -A small example should make this thinking clean: :: +A small example should make this idea clear: :: /var/www/ /var/www/logs/ @@ -62,7 +62,8 @@ You can use symbolic links to map several hostnames to the same directory. Conditionals vs. simple-vhost ----------------------------- -You have to keep in mind that conditionals and simple-vhost interfere. :: +You have to keep in mind that conditionals and simple-vhost interfere +with one another. :: simple-vhost.server-root = "/var/www/servers/" simple-vhost.default-host = "www.example.org" @@ -72,14 +73,15 @@ You have to keep in mind that conditionals and simple-vhost interfere. :: server.document-root = "/var/www/servers/news2.example.org/pages/" } -Even if the ``server.document-root`` will be set to ``/var/www/servers/news2.example.org/pages/`` -if ``news.example.org`` is requested simple-vhost will overwrite ``server.document-root`` shortly -afterwards. +When ``news.example.org`` is requested, the ``server.document-root`` +will be set to ``/var/www/servers/news2.example.org/pages/``, but +simple-vhost will overwrite it shortly afterwards. -If ``/var/www/servers/news.example.org/pages/`` exists it will be taken, if not -``/var/www/servers/www.example.org/pages/`` will be taken as it is the default. +If ``/var/www/servers/news.example.org/pages/`` exists, that will be +used. If not, ``/var/www/servers/www.example.org/pages/`` will be taken +because it is the default. -To get them working in parallel you should use: :: +To use conditionals together with simple-vhost, you should do this: :: $HTTP["host"] !~ "^(news\.example\.org)$" { simple-vhost.server-root = "/var/www/servers/" @@ -91,17 +93,17 @@ To get them working in parallel you should use: :: server.document-root = "/var/www/servers/news2.example.org/pages/" } -It will enable simple-vhosting for all host with are not named ``news.example.org``. +It will enable simple vhosting for all hosts other than ``news.example.org``. Options ======= simple-vhost.server-root - root of the virtual hosting + root of the virtual host simple-vhost.default-host - use this hostname if the + use this hostname if the requested hostname does not have its own directory simple-vhost.document-root - path below the vhost-directory - + path below the vhost directory + diff --git a/doc/ssi.txt b/doc/ssi.txt index c5791a24..8761416f 100644 --- a/doc/ssi.txt +++ b/doc/ssi.txt @@ -11,8 +11,8 @@ Module: mod_ssi :Revision: $Revision: 1.2 $ :abstract: - The module for server-side includes provides a compat layer for - NSCA/Apache SSI. + The module for server-side includes provides a compatability + layer for NSCA/Apache SSI. .. meta:: :keywords: lighttpd, ssi, Server-Side Includes @@ -60,7 +60,7 @@ Every ''expr'' is interpreted: Flow Control ------------ -if, elif, else and endif can be used the insert content only under special +if, elif, else and endif can only be used to insert content under special conditions. Unsupported Features diff --git a/doc/ssl.txt b/doc/ssl.txt index 81b92158..447da4e5 100644 --- a/doc/ssl.txt +++ b/doc/ssl.txt @@ -11,30 +11,30 @@ Module: core :Revision: $Revision: 1.2 $ :abstract: - How to setup SSL in lighttpd - + How to set up SSL in lighttpd + .. meta:: :keywords: lighttpd, ssl - + .. contents:: Table of Contents Description =========== -lighttpd support SSLv2 and SSLv3 if it compiled against openssl. +lighttpd supports SSLv2 and SSLv3 if it is compiled against openssl. Configuration ------------- -To enable SSL for the whole server you have to provide a valid +To enable SSL for the whole server you have to provide a valid certificate and have to enable the SSL engine.:: ssl.engine = "enable" ssl.pemfile = "/path/to/server.pem" - -As SSL and named-based virtual hosting can not work together you -have to use IP-based virtual hosting if you want to run multiple -SSL-servers with one lighttpd: :: + +The HTTPS protocol does not allow you to use name-based virtual +hosting with SSL. If you want to run multiple SSL servers with +one lighttpd instance you must use IP-based virtual hosting: :: $SERVER["socket"] == "10.0.0.1:443" { ssl.engine = "enable" @@ -44,7 +44,8 @@ SSL-servers with one lighttpd: :: server.document-root = "/www/servers/www.example.org/pages/" } -If you have a .crt and a .key file cat them together into a single PEM file: +If you have a .crt and a .key file, cat them together into a +single PEM file: :: $ cat host.key host.crt > host.pem @@ -53,9 +54,9 @@ If you have a .crt and a .key file cat them together into a single PEM file: Self-Signed Certificates ------------------------ -A self-signed SSL cerifitcate can be generated with: :: - +A self-signed SSL certificate can be generated like this: :: + $ openssl req -new -x509 \ -keyout server.pem -out server.pem \ -days 365 -nodes - + diff --git a/doc/status.txt b/doc/status.txt index 3e0acab4..ab418bf6 100644 --- a/doc/status.txt +++ b/doc/status.txt @@ -11,7 +11,7 @@ Module: mod_status :Revision: $Revision: 1.2 $ :abstract: - mod_status displays server-status and server-config + mod_status displays the server's status and configuration .. meta:: :keywords: lighttpd, server status @@ -21,15 +21,68 @@ Module: mod_status Description =========== -The server status module generates the ... +The server status module generates the status overview of the webserver. The +information covers: + +- uptime +- average throughput +- current throughput +- active connections and their state + +By default the status page is disabled to hide internal information from +unauthorized users. :: + + status.status-url = "/server-status" + +If you want to open the status page just for users from the local network +cover it in a conditional. :: + + $HTTP["remoteip"] == "10.0.0.0/8" { + status.status-url = "/server-status" + } + +Or require authorization: :: + + auth.require = ( "/server-status" => + ( "realm" ... ) ) + + +Output Format +------------- + +By default a nice looking HTML page is generated. If you append ?auto to the +status-url you can get a text version which is simpler to parse. :: + + Total Accesses: 1234 + Total kBytes: 1043 + Uptime: 1234 + BusyServers: 123 + +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. + +The naming is kept compatible to Apache even if we have another concept and +don't start new servers for each connection. + Options ======= status.status-url + relative URL which is used to retrieve the status-page + Default: unset +status.enable-sort + + add JavaScript which allows client-side sorting for the connection overview + + Default: enable + status.config-url + relative URL for the config page which displays the loaded modules + Default: unset diff --git a/doc/traffic-shaping.txt b/doc/traffic-shaping.txt index 7d16638d..1076686e 100644 --- a/doc/traffic-shaping.txt +++ b/doc/traffic-shaping.txt @@ -11,45 +11,45 @@ Module: core :Revision: $Revision: 1.2 $ :abstract: - limiting the bandwith usage - + limiting bandwidth usage + .. meta:: :keywords: lighttpd, bandwidth limit, traffic shaping - + .. contents:: Table of Contents Description =========== -Starting with 1.3.8 lighttpd supports limiting the bandwith for a single connection -or config-context like virtual-host or URL. +Starting with 1.3.8, lighttpd supports limiting the bandwidth for +a single connection or config context like a virtual host or a URL. Options ======= :connection.kbytes-per-second: - limit the through-put for each single connection to the given + limit the throughput for each single connection to the given limit in kbyte/s - + default: 0 (no limit) :server.kbytes-per-second: - limit the through-put for all connections to the given limit + limit the throughput for all connections to the given limit in kbyte/s - - if you want to specify a limit for a special virtual server + + if you want to specify a limit for a special virtual server use: :: - + $HTTP["host"] == "www.example.org" { server.kbytes-per-second = 128 } - - which will overwrite the default for this host. - + + which will override the default for this host. + default: 0 (no limit) Additional Notes ================ -Keep in mind that a limit below 32kb/s might actually limit the traffic to 32kb/s. This -is caused by by the size of the TCP-sendbuffer. +Keep in mind that a limit below 32kb/s might actually limit the traffic to 32kb/s. This +is caused by the size of the TCP send buffer. diff --git a/doc/trigger_b4_dl.txt b/doc/trigger_b4_dl.txt index ffdfb535..f5c9d299 100644 --- a/doc/trigger_b4_dl.txt +++ b/doc/trigger_b4_dl.txt @@ -11,11 +11,11 @@ Module: mod_trigger_b4_dl :Revision: $Revision: 1.2 $ :abstract: - another anti hot-linking module - + another anti-hot-linking module + .. meta:: :keywords: lighttpd, hot-linking, deep-linking - + .. contents:: Table of Contents Description @@ -23,11 +23,11 @@ Description Anti Hotlinking: - * if user requests ''download-url'' directly the request is denied and he is redirected to ''deny-url' - * if user visits ''trigger-url'' before requesting ''download-url'' access is granted - * if user visits ''download-url'' again after ''trigger-timeout'' has run down to the request is denied and he is redirected to ''deny-url'' + * if user requests ''download-url'' directly, the request is denied and he is redirected to ''deny-url' + * if user visits ''trigger-url'' before requesting ''download-url'', access is granted + * if user visits ''download-url'' again after ''trigger-timeout'' has elapsed, the request is denied and he is redirected to ''deny-url'' -The storage for the trigger information is either stored locally in a gdbm file or remotly in memcached. +The trigger information is either stored locally in a gdbm file or remotely in memcached. Requirements ------------ @@ -47,8 +47,8 @@ Options trigger-before-download.deny-url = "http://192.168.1.5:1025/index.html" trigger-before-download.trigger-timeout = 10 -If both trigger-before-download.gdbm-filename and -trigger-before-download.memcache-hosts is set gdbm will be prefered. +If both trigger-before-download.gdbm-filename and +trigger-before-download.memcache-hosts is set gdbm will take precedence. Installation ============ diff --git a/doc/userdir.txt b/doc/userdir.txt index 65cc9d03..10ba0659 100644 --- a/doc/userdir.txt +++ b/doc/userdir.txt @@ -23,8 +23,8 @@ Description The userdir module provides a simple way to link user-based directories into the global namespace of the webserver. -Requests in the form ``/~user/page.html`` are rewritten to take the file ``page.html`` from the home-directory of the user. -If ``userdir.path`` is set, the path will be appended at the home-directory +Requests in the form ``/~user/page.html`` are rewritten to take the file ``page.html`` from the home directory of the user. +If ``userdir.path`` is set, the path will be appended to the home directory building the classic mapping of: :: userdir.path = "public_html" @@ -32,9 +32,9 @@ building the classic mapping of: :: 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 include- or a exclude list for username. +To control which users should be able to use this feature you can set a list of usernames to include or exclude. -In case you mapping is independent of /etc/passwd you can use +In case your mapping is independent of /etc/passwd you can use ``userdir.basepath``: :: userdir.path = "htdocs" @@ -47,15 +47,15 @@ Options ======= userdir.path - usually it should set the "public_html" to take ~/public_html/ as the document-root + 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: empty (document root is the home directory) Example: :: userdir.path = "public_html" userdir.exclude-user - list of usernames which should not be able to use this feature + list of usernames which may not use this feature Default: empty (all users may use it) Example: :: @@ -66,7 +66,7 @@ userdir.exclude-user userdir.include-user if set, only users from this list may use the feature - Default: empty (all user may use it) + Default: empty (all users may use it) userdir.basepath if set, don't check /etc/passwd for homedir diff --git a/doc/webdav.txt b/doc/webdav.txt index 175f33f4..b10012f7 100644 --- a/doc/webdav.txt +++ b/doc/webdav.txt @@ -22,7 +22,7 @@ Description =========== The WebDAV module is a very minimalistic implementation of RFC 2518. -Minimalistic means that not all operations are implementated yet. +Minimalistic means that not all operations are implemented yet. So far we have @@ -34,15 +34,15 @@ So far we have and the usual GET, POST, HEAD from HTTP/1.1. -So far mounting a webdav resource into Windows XP works and the basic litmus +So far, mounting a WebDAV resource into Windows XP works and the basic litmus tests are passed. Options ======= webdav.activate - If you load the webdav module the WebDAV functionality has to be - enabled for the directories you want to the provide to the user. + 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 @@ -54,9 +54,9 @@ webdav.is-readonly Examples ======== -To enable WebDAV for the /dav directory you take a conditional and wrap around -your webdav options. You have to use the regex like below as you want to match -the directory /dav and everything below it, but not /davos. :: +To enable WebDAV for the /dav directory, you wrap your webdav options in +a conditional. You have to use the regex like below as you want to match +the directory /dav and everything below it, but not e.g. /davos. :: $HTTP["url"] =~ "^/dav($|/)" { webdav.activate = "enable"