Configuration File Options¶

Here you will find a list of all available configuration lighttpd. They are grouped by module, and a link to each module configuration will provide with more detail information about each option, as well as examples, and other guidelines.

• Table of contents
• Configuration File Options
  • Lighttpd Core
    • SSL
    • Core Debug Info
  • mod_access - access restrictions
  • mod_accesslog - access log files
  • mod_alias - directory aliases
  • mod_auth - authentication
  • mod_cache - web accelerating
  • mod_cgi - cgi
  • mod_cml - Cache Meta Language
  • mod_compress - compress output
  • mod_deflate - dynamic compression (1.4.42)
  • mod_dirlisting - directory listing
  • mod_evasive - evasive
  • mod_evhost - enhanced virtual host
  • mod_expire - cached expiration
  • mod_extforward - use X-Forwarded-For
  • mod_fastcgi - fastcgi
  • mod_flv_streaming - flv streaming
  • mod_geoip - IP location lookup
  • mod_indexfile - Precautions and documentation
  • mod_magnet - a module to control request handling
  • mod_mem_cache - local file accelerating
  • mod_mimemagic - determines the MIME type of a file by looking at a few bytes of its contents
  • mod_mysql_vhost - Mysql virtual hosting
  • mod_proxy - proxy
  • mod_redirect - redirect
  • mod_rewrite - rewriting
  • mod_rrdtool - rrdtool
  • mod_scgi - SCGI
  • mod_secdownload - secure and fast download
  • mod_setenv - set HTTP Environment
  • mod_simple_vhost - simple virtual host
  • mod_ssi - server side includes
  • mod_status - server status
  • mod_trigger_b4_dl - trigger before download
  • mod_userdir - user directories
  • mod_uploadprogress - upload progress
  • mod_usertrack - user track (cookies)
  • mod_webdav - WebDAV

Lighttpd Core¶

option	description	details
connection.kbytes-per-second	limit the throughput for each single connection to the given limit in kbyte/s	Details
server.chroot	root-directory of the server	Details
server.core-files	enable core files	Details
server.errorlog	pathname of the error-log	Details
server.errorlog-use-syslog*	send errorlog to syslog	Details
server.breakagelog	open as stderr, so all forked applications will write their errors to this (if stderr isn't handled otherwise via a pipe); needed to see mod_cgi stderr in 1.4
server.event-handler	set the event handler	Details
server.follow-symlink	allow to follow-symlinks	Details
server.force-lowercase-filenames	enable force all filenames to lowercase
server.groupname	groupname used to run the server	Details
server.kbytes-per-second	limit the throughput for all connections to the given limit in kbyte/s	Details
server.max-connections	maximum connections	Details
server.max-fds	maximum number of file descriptors	Details
server.max-keep-alive-idle	maximum number of seconds until a idling keep-alive connection is dropped	Details
server.max-keep-alive-requests	maximum number of request within a keep-alive session	Details
server.max-read-idle	maximum number of seconds until a waiting, non keep-alive read times out and closes the connection	Details
server.max-request-size	maximum size in kbytes of the request	Details
server.max-request-field-size	maximum size of the request header (in bytes)
server.max-worker	number of worker processes to spawn	Details
server.max-write-idle	maximum number of seconds until a waiting write call times out	Details
server.modules	modules to load	Details
server.pid-file	set the name and location of the .pid-file	Details
server.stat-cache-engine	select stat() call caching	Details
server.stream-request-body	stream request body to backend	Details
server.stream-response-body	stream response body to client	Details
server.upload-dirs	path to upload directory	Details
server.username	username used to run the server	Details

server.bind	IP address, hostname or absolute path to the unix-domain socket	Details
server.network-backend	basic network interface for all platforms at the syscalls read() and write()	Details
server.listen-backlog	listen backlog queue size	Details 71ed1912
server.bsd-accept-filter	listen socket *BSD accept() filter ("httpready" or "dataready")	Details 4eeeb8fc
server.defer-accept	listen socket Linux TCP_DEFER_ACCEPT ("enable" or "disable")
server.use-ipv6	bind to the IPv6 socket	Details

server.name	name of the server/virtual server	Details
server.document-root	document-root of the webserver	Details
server.error-handler	uri to call if non-dynamic (not CGI or proxy) request results in http status >= 400 (overrides error-handler-404)	Details dbdab5db
server.error-handler-404	uri to call if non-dynamic (not CGI or proxy) request results in a 403 or 404	Details
server.errorfile-prefix	path prefix for special status codes pages	Details
server.http-parseopt-header-strict	restrict chars permitted in HTTP headers	Details b47494d4
server.http-parseopt-host-strict	restrict chars permitted in HTTP Host header	Details b47494d4
server.http-parseopt-host-normalize	normalize HTTP Host header	Details b47494d4
server.protocol-http11	defines if HTTP/1.1 is allowed or not	Details
server.range-requests	defines if range requests are allowed or not	Details
server.reject-expect-100-with-417	setting to disable returning of a 417 if "Expect: 100-continue" header
server.tag	set the string returned by the server	Details

index-file.names	list of files to search for if a directory is requested	Details
server.dir-listing	enable/disable dir listing	Details

etag.use-inode	Determines if inode-value is used in ETag generation	Details
etag.use-mtime	Determines if mtime-value is used in ETag generation	Details
etag.use-size	Determines if size-value is used in ETag generation	Details
static-file.etags	Determines if ETags are generated or not
static-file.exclude-extensions	forbid access to the source of some types of files by extension

mimetype.assign	list of known mimetype mappings	Details
mimetype.use-xattr	try to use XFS-style extended attribute interface for retreiving the Content-Type	Details
mimetype.xattr-name	name of XFS-style extended attribute to use for retreiving the Content-Type	Details

SSL¶

option	description	details
ssl.engine	enable/disable ssl engine	Details
ssl.pemfile	path to the PEM file for SSL support	Details
ssl.ca-file	path to the CA file for support of chained certificates	Details
ssl.use-sslv2	enable/disable use of SSL version 2	Details
ssl.cipher-list	Configure the allowed SSL ciphers	Details
ssl.honor-cipher-order	enable/disable honoring the order of ciphers set in ssl.cipher-list (set by default when ssl.cipher-list is set)	Details
ssl.disable-client-renegotiation	enable/disable mitigation of client triggered re-negotiation (see CVE-2009-3555)	Details
ssl.verifyclient.activate	enable/disable client verification	Details
ssl.verifyclient.enforce	enable/disable enforcing client verification	Details
ssl.verifyclient.depth	certificate depth for client verification	Details
ssl.verifyclient.exportcert	enable/disable client certificate export to env:SSL_CLIENT_CERT	Details
ssl.verifyclient.username	client certificate entity to export as env:REMOTE_USER (eg. SSL_CLIENT_S_DN_emailAddress, SSL_CLIENT_S_DN_UID, etc.)	Details

Core Debug Info¶

• Debug Variable Information

option	description
debug.log-request-header	log all request headers
debug.log-file-not-found	log if a file wasn't found
debug.log-condition-handling	log conditionals handling for debugging
debug.log-request-header-on-error	log request header, but only when there is an error
debug.log-request-handling	log request handling inside lighttpd
debug.log-state-handling	log state handling inside lighttpd
debug.log-response-header	log the header we send out to the client
debug.log-ssl-noise	log some ssl warnings we hide by default (ssl handshake, unknown/bad certificate)

mod_access - access restrictions¶

• mod_access documentation

option	description
url.access-allow	Allows access only to files with any of given trailing path names (since 1.4.40)
url.access-deny	Denies access to all files with any of given trailing path names

mod_accesslog - access log files¶

• mod_accesslog documentation

option	description
accesslog.format	the format of the logfile
accesslog.filename	name of the file where the accesslog should be written to if syslog is not used
accesslog.use-syslog	send the accesslog to syslog
accesslog.syslog-level	numerical value used as syslog log level

mod_alias - directory aliases¶

• mod_alias documentation

option	description
alias.url	rewrites the document-root for a URL-subset

mod_auth - authentication¶

• mod_auth documentation

option	description
auth.debug	enable/disable authentication module debug information
auth.backend	type of authentication backend
auth.require	set restriction method
auth.backend.gssapi.keytab
auth.backend.gssapi.principal
auth.backend.ldap.hostname	hostname of ldap server
auth.backend.ldap.starttls
auth.backend.ldap.filter
auth.backend.ldap.bind-pw
auth.backend.ldap.ca-file
auth.backend.ldap.base-dn
auth.backend.ldap.bind-dn
auth.backend.plain.userfile	path to plain userfile
auth.backend.plain.groupfile	path to plain groupfile
auth.backend.htdigest.userfile	path to htdigest userfile
auth.backend.htpasswd.userfile	path to htpassword userfile

auth.require option	description
method	type of authentication ("digest" or "basic")
realm	authentication realm
require	"valid-user" to allow any valid user, or a list of user=username separated by pipe symbols

mod_cache - web accelerating¶

• mod_cache documentation

option	description
cache.bases	directory arrays which want to save cache files
cache.enable
cache.domains	domain pcre regex arrays which mod_cache will cache
cache.support-queries
cache.debug	writes mod_cache debuging messages to error.log or not
cache.purge-host	pcre regex hosts ip which are allowed to PURGE cache file
cache.refresh-pattern

mod_cgi - cgi¶

• mod_cgi documentation

option	description
cgi.assign	assign cgi handler to an extension
cgi.execute-x-only	requires +x for cgi scripts
cgi.x-sendfile	controls if X-Sendfile header is allowed
cgi.x-sendfile-docroot	limits the directory trees permitted for use with X-Sendfile response header

mod_cml - Cache Meta Language¶

• mod_cml documentation

option	description
cml.memcache-namespace	(not used yet)
cml.power-magnet	a cml file that is executed for each request
cml.memcache-hosts	hosts for the memcache.* functions
cml.extension	the file extension that is bound to the cml-module

mod_compress - compress output¶

• mod_compress documentation

option	description
compress.max-filesize	maximum size of the original file to be compressed kBytes
compress.cache-dir	name of the directory where compressed content will be cached
compress.filetype	mimetypes which might get compressed
compress.allowed-encodings	encodings enabled ("gzip", "bzip2", "deflate")
compress.max-loadavg	max system loadavg before bypassing compression, e.g. "3.50" (since 1.4.43)

mod_deflate - dynamic compression (1.4.42)¶

• mod_deflate documentation

option	description
deflate.mimetypes	mimetype listing to be compressed, matched to prefix of Content-Type
deflate.allowed-encodings	encodings enabled ("gzip", "bzip2", "deflate")
deflate.max-compress-size	maximum size document to compress
deflate.min-compress-size	minimum size document before compressing
deflate.compression-level	level of compression
deflate.output-buffer-size	size of buffer for compression
deflate.work-block-size	minimum block size for compression
deflate.max-loadavg	max system loadavg before bypassing compression, e.g. "3.50" (since 1.4.43)

mod_dirlisting - directory listing¶

• mod_dirlisting documentation

option	description
server.dir-listing*: enable/disable directory listing
dir-listing.activate	enables virtual directory listings if a directory is requested no index-file was found
dir-listing.external-css	path to an external css stylesheet for the directory listing
dir-listing.external-js	path to an external js script, e.g. for client side directory list sorting (lighttpd 1.4.42)
dir-listing.encoding	set a encoding for the generated directory listing
dir-listing.hide-dotfiles	if enabled, does not list hidden files in directory listings generated by the dir-listing option
dir-listing.show-header	include HEADER.txt files above the directory listing (since 1.4.43: user-specified file name)
dir-listing.hide-header-file	enables hide header file from directory listing
dir-listing.show-readme	include README.txt files below the directory listing (since 1.4.43: user-specified file name)
dir-listing.hide-readme-file	enables displaying readme file in directory listing
dir-listing.exclude	files that match any of the specified regular expressions will be excluded from listings
dir-listing.set-footer	displays a string in the footer of a listing page

mod_evasive - evasive¶

• mod_evasive documentation

option	description
evasive.max-conns-per-ip	upper limit of number of connections per ip allowed
evasive.silent	no logging

mod_evhost - enhanced virtual host¶

• mod_evhost documentation

option	description
evhost.path-pattern	pattern with wildcards to be replace to build a documentroot

mod_expire - cached expiration¶

• mod_expire documentation

option	description
expire.url	assignes an expiration to all files below the specified path
expire.mimetypes	assignes an expiration to all responses with Content-Type prefix matching the listed mimetypes (since 1.4.43)

mod_extforward - use X-Forwarded-For¶

• mod_extforward documentation

extract the client's "real" IP from X-Forwarded-For header

option	description
extforward.forwarder	set trust level of proxy ip's

mod_fastcgi - fastcgi¶

• mod_fastcgi documentation

option	description
fastcgi.map-extensions	map multiple extensions to the same fastcgi server
fastcgi.debug	a value between 0 and 65535 to set the debug-level in the FastCGI module
fastcgi.server	tell the module where to send FastCGI requests to

fastcgi.server-option	description
host	is ip of the FastCGI process
port	is tcp-port on the "host" used by the FastCGI process
socket	path to the unix-domain socket
bin-path	path to the local FastCGI binary which should be started if no local FastCGI is running
bin-environment	set environment of FastCGI binary
bin-copy-environment	copy environment from server for FastCGI binary
listen-backlog	listen backlog queue size (for backend daemons started by mod_fastcgi)
mode	is the FastCGI protocol mode. Default is "responder", also "authorizer" mode is implemented
docroot	docroot on the remote host
x-sendfile	controls if X-Sendfile header is allowed
x-sendfile-docroot	limits the directory trees permitted for use with X-Sendfile response header
broken-scriptfilename	breaks SCRIPT_FILENAME in a way that PHP can extract PATH_INFO from it
max-procs	upper limit of processes to start
check-local	enable/disable check for requested file in document root
disable-time	time to wait before a disabled backend is checked again
strip-request-uri	strip part of request-uri
fix-root-scriptname	use this for backends with extension "/" (and check-local is disabled), only works > 1.4.22

mod_flv_streaming - flv streaming¶

flv-streaming.extensions: extensions of flv files

Blog Entry

Additional Information

Flash Video Player 3.5

mod_geoip - IP location lookup¶

• mod_geoip documentation

option	description
geoip.db-filename	path to the geoip or geocity database
geoip.memory-cache	enable or disable GeoIP memory cache (default disabled)

mod_indexfile - Precautions and documentation¶

• mod_indexfile documentation

mod_magnet - a module to control request handling¶

• mod_magnet documentation

option	description
magnet.attract-raw-url-to	attract request before lighttpd tries to find a physical file (but after rewrite)
magnet.attract-physical-path-to	attract request after doc-root is known and the physical-path is already setup

mod_mem_cache - local file accelerating¶

• mod_mem_cache documentation

option	description
mem-cache.filetypes	content-type arrays which want to put into memory
mem-cache.enable
mem-cache.max-memory	maxium memory in Mbytes mod-mem-cache can use
mem-cache.max-file-size	maxium file size in Kbytes of single file to cache in memory
mem-cache.lru-remove-count
mem-cache.expire-time	memory cache's expire time in minutes
mem-cache.slru-thresold	slru threshold (against hit counter)

mod_mimemagic - determines the MIME type of a file by looking at a few bytes of its contents¶

• mod_mimemagic documentation

option	description
mimemagic.file	path of magic.mime file
mimemagic.override-global-mimetype

mod_mysql_vhost - Mysql virtual hosting¶

• mod_mysql_vhost documentation

option	description
mysql-vhost.hostname	hostname of mysql server
mysql-vhost.db	database name
mysql-vhost.user	username to access database
mysql-vhost.pass	password to access database
mysql-vhost.sql	SQL statement to execute to obtain docroot
mysql-vhost.port	port where to connect to database
mysql-vhost.sock	socket where to connect to database

mod_proxy - proxy¶

• mod_proxy documentation

option	description
proxy.balance	select type of balancing algorithm (round-robin, hash, fair)
proxy.debug	enable/disable proxy debug information
proxy.server	where to send Proxy requests

proxy.server-option	description
host	ip of host to send requests
port	listening port of host

mod_redirect - redirect¶

• mod_redirect documentation

option	description	note
url.redirect	redirects a set of URLs externally
url.redirect-code	defines the http code that is sent with the redirect URL	Added in 1.4.31

mod_rewrite - rewriting¶

• mod_rewrite documentation

option	description
url.rewrite-once	rewrites a set of URLs internally and skip the rest
url.rewrite-repeat	rewrites a set of URLs internally in the webserver, continue applying rewrite rules
url.rewrite	same as url.rewrite-once
url.rewrite-final	same as url.rewrite-once
url.rewrite-[repeat-]if-not-file	rewrites a set of urls internally and checks if files do not exist

mod_rrdtool - rrdtool¶

• mod_rrdtool documentation

option	description
rrdtool.db-name	filename of the rrd-database
rrdtool.binary	path to the rrdtool binary

mod_scgi - SCGI¶

• mod_scgi documentation

option	description
scgi.debug	a value between 0 and 65535 to set the debug-level in the SCGI module
scgi.server	tell the module where to send SCGI requests to
scgi.protocol	protocol between lighttpd and backend server ("scgi" (default) or "uwsgi")	Added in 1.4.42

scgi.server-option	description
host	is ip of the SCGI process
port	is tcp-port on the "host" used by the SCGI process
socket	path to the unix-domain socket
bin-path	path to the local SCGI binary which should be started if no local SCGI is running
bin-environment	set environment of SCGI binary
bin-copy-environment	copy environment from server for SCGI binary
listen-backlog	listen backlog queue size (for backend daemons started by mod_scgi)
docroot	docroot on the remote host
x-sendfile	controls if X-Sendfile header is allowed
x-sendfile-docroot	limits the directory trees permitted for use with X-Sendfile response header
broken-scriptfilename	breaks SCRIPT_FILENAME in a way that PHP can extract PATH_INFO from it
idle-timeout	number of seconds before a unused process gets terminated
max-procs	upper limit of processes to start
min-procs	sets the minium processes to start
min-procs-not-working
max-load-per-proc	maximum number of waiting processes on average per process before a new process is spawned
check-local	enable/disable check for requested file in document root (default: enabled)
disable-time	time to wait before a disabled backend is checked again
strip-request-uri	strip part of request-uri

mod_secdownload - secure and fast download¶

• mod_secdownload documentation

option	description
secdownload.document-root	path to the download area
secdownload.timeout	how long in seconds is the secret valid
secdownload.uri-prefix	prefix to url for download
secdownload.secret	Secret string that will be used for the checksum calculation
secdownload.algorithm	hash algorithm: "md5", "hmac-sha1", or "hmac-sha256"

mod_setenv - set HTTP Environment¶

• mod_setenv documentation

option	description
setenv.add-response-header	adds a value to the process environment that is passed to the external applications
setenv.add-request-header	adds a header to the HTTP response sent to the client
setenv.add-environment	adds a value to the process environment that is passed to the external applications

mod_simple_vhost - simple virtual host¶

• mod_simple_vhost documentation

option	description
simple-vhost.document-root	path below the vhost directory
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.debug	debug simple vhosts module

mod_ssi - server side includes¶

• mod_ssi documentation

option	description
ssi.extension	extension of files processed by mod_ssi
ssi.content-type	specify Content-Type response header for SSI pages
ssi.conditional-requests	enable/disable conditional request caching including generating ETag and Last-Modified response headers
ssi.exec	enable/disable #exec cmd="..."

mod_status - server status¶

• mod_status documentation

option	description
status.config-url	relative URL for the config page which displays the loaded modules
status.statistics-url	relative URL for a plain-text page containing the internal statistics
status.enable-sort	add JavaScript which allows client-side sorting for the connection overview
status.status-url	relative URL which is used to retrieve the status-page

mod_trigger_b4_dl - trigger before download¶

• mod_trigger_b4_dl documentation

option	description
trigger-before-download.trigger-url	url for trigger pages
trigger-before-download.trigger-timeout	time for download link to live
trigger-before-download.download-url	url for downloads
trigger-before-download.deny-url	url to show when visitor denied a download
trigger-before-download.gdbm-filename	path to gdm file
trigger-before-download.memcache-hosts	hosts for the memcache.* functions
trigger-before-download.memcache-namespace	(not used yet)
trigger-before-download.debug

mod_userdir - user directories¶

• mod_userdir documentation

option	description
userdir.basepath	if set, don't check /etc/passwd for homedir
userdir.exclude-user	list of usernames which may not use this feature
userdir.path	usually it should be set to "public_html" to take ~/public_html/ as the document root
userdir.include-user	if set, only users from this list may use the feature

mod_uploadprogress - upload progress¶

option	description
upload-progress.progress-url

mod_usertrack - user track (cookies)¶

• mod_usertrack documentation

option	description
usertrack.cookie-name
~'_usertrack.cookiename_'~	(deprecated)
usertrack.cookie-domain
usertrack.cookie-max-age

mod_webdav - WebDAV¶

• mod_webdav documentation

option	description
webdav.activate	enable/disable WebDAV
webdav.is-readonly	enable/disable read only
webdav.sqlite-db-name	pathname to SQLite database
webdav.log-xml	Log the XML Request bodies for debugging