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.

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.syslog-facility syslog facility (default: "daemon") (since 1.4.46)
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 set the name and location of the .pid-file Details
server.stat-cache-engine select stat() call caching Details stream request body to backend Details 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.port port to which to bind when IP address specified in server.bind 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.socket-perms permissions to set on listening unix domain socket, e.g. "0770" (since 1.4.46) Details #656 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) (since 1.4.40) 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.error-intercept enable/disable intercepting HTTP error pages from dynamic handlers by server.error* (since 1.4.46)
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 (no-op since 1.4.46)
server.tag set the string returned by the server 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

Core Debug Info

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

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

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

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

mod_auth - authentication

option description
auth.backend type of authentication backend
auth.require set restriction method
auth.extern-authn check REMOTE_USER (if set) against require rules prior to applying auth.backend (since 1.4.46)
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.backend.ldap.hostname hostname of ldap server
auth.backend.ldap.groupmember (since 1.4.46) (mysql default if not specified)
auth.backend.mysql.user (mysql default if not specified)
auth.backend.mysql.pass (mysql default if not specified)
auth.backend.mysql.db (mysql default if not specified)
auth.backend.mysql.port (mysql default if not specified)
auth.backend.mysql.socket (mysql default if not specified)
auth.backend.mysql.users_table database table name (required)
auth.backend.mysql.col_user (default: "user")
auth.backend.mysql.col_pass (default: "password")
auth.backend.mysql.col_realm (default: "realm")
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

option description
cache.bases directory arrays which want to save cache files
cache.enable domain pcre regex arrays which mod_cache will cache
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

mod_cgi - cgi

option description
cgi.assign assign cgi handler to an extension
cgi.execute-x-only requires +x for cgi scripts
cgi.local-redir local-redir optimization (since 1.4.46)
cgi.upgrade experimental support for Upgrade: websocket (since 1.4.46)
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

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

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)

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

option description
dir-listing.activate enables virtual directory listings if a directory is requested no index-file was found
dir-listing.external-css URL path to an external css stylesheet for the directory listing
dir-listing.external-js URL 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 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 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
server.dir-listing enable/disable directory listing (deprecated; see dir-listing.activate)

mod_evasive - evasive

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

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

mod_expire - cached expiration

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 (or Forwarded)

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

option description
extforward.forwarder set trust level of proxy ip's
extforward.hap-PROXY enable HAProxy PROXY protocol (since 1.4.46)
extforward.hap-PROXY-ssl-client-verify enable setting SSL_CLIENT_VERIFY from HAProxy PROXY protocol (since 1.4.46)
extforward.headers set of request headers to search, e.g. "Forwarded" or "X-Forwarded-For"
extforward.params configure additional values to take from "Forwarded" header (since 1.4.46)

mod_fastcgi - fastcgi

option description
fastcgi.server backend server definition(s) for hosts to which to send requests; options for each backend host
fastcgi.balance select type of balancing algorithm (fair, least-connection, round-robin, hash, sticky (since 1.4.46))
fastcgi.debug debug level (value between 0 and 65535) map multiple extensions to the same backend

mod_flv_streaming - flv streaming

mod_geoip - IP location lookup

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

option description details
index-file.names list of files to search for if a directory is requested Details

mod_magnet - a module to control request handling

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

option description
mem-cache.filetypes content-type arrays which want to put into memory
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.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

option description
mimemagic.file path of magic.mime file

mod_mysql_vhost - Mysql virtual hosting

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_openssl - TLS/SSL using openssl

part of mod_openssl (since 1.4.46), though ssl.* directives are available in earlier versions, built-in to the lighttpd core

option description details
ssl.engine enable/disable ssl engine Details
ssl.pemfile path to the PEM file for SSL support Details path to the CA file for support of chained certificates Details path to file for certificate revocation list (CRL) for client certs (since 1.4.46) Details path to file for certificate authorities (CA) (but not trusted root CAs) from which client should select client certs (since 1.4.46) Details
ssl.use-sslv2 enable/disable use of SSL version 2 Details
ssl.cipher-list Configure the allowed SSL ciphers Details enable/disable use of SSL read ahead (lighttpd 1.4.45+) (if disable, must be in global scope in lighttpd 1.4.45) 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

mod_proxy - proxy

option description
proxy.server backend server definition(s) for hosts to which to send requests; options for each backend host
proxy.balance select type of balancing algorithm (fair, least-connection, round-robin, hash, sticky (since 1.4.44))
proxy.debug debug level (value between 0 and 65535) map multiple extensions to the same backend (since 1.4.46)
proxy.forwarded append "Forwarded" header (RFC7239) to proxied requests (since 1.4.46)
proxy.replace-http-host enable/disable replacing Host header in request to backend with proxy.server label (since 1.4.44)
proxy.header options to perform simple remapping of host and URL paths in proxied HTTP headers (since 1.4.46)
proxy.server-option description
host ip of host to send requests
port listening port of host

mod_redirect - redirect

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

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

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

mod_scgi - SCGI

option description
scgi.server backend server definition(s) for hosts to which to send requests; options for each backend host
scgi.balance select type of balancing algorithm (fair, least-connection, round-robin, hash, sticky (since 1.4.46))
scgi.debug debug level (value between 0 and 65535) map multiple extensions to the same backend (since 1.4.46)
scgi.protocol protocol between lighttpd and backend server ("scgi" (default) or "uwsgi") (since 1.4.42)

mod_secdownload - secure and fast download

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"
secdownload.path-segments include only given number of path segments in hash digest calculation (since 1.4.46)
secdownload.hash-querystr include the query string in the hash digest calculation ("enable" or "disable") (since 1.4.46)

mod_setenv - set HTTP Environment

option description
setenv.add-request-header adds a value to the HTTP request received from the client
setenv.set-request-header sets a value to the HTTP request received from the client (since 1.4.46)
setenv.add-environment adds a value to the process environment passed to external (backend) applications
setenv.set-environment sets a value to the process environment passed to external (backend) applications (since 1.4.46)
setenv.add-response-header adds a header to the HTTP response sent to the client
setenv.set-response-header sets a header to the HTTP response sent to the client (since 1.4.46)

mod_simple_vhost - simple virtual host

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

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="..."
ssi.recursion-max max recursion depth for #include virtual="..." SSI processing (0 is disabled (default)) (since 1.4.44)

mod_status - server status

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

option description
trigger-before-download.trigger-url url for trigger pages
trigger-before-download.trigger-timeout time for download link to live 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)

mod_userdir - user directories

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

mod_usertrack - user track (cookies)

option description
usertrack.cookie-name default "TRACKID"
usertrack.cookie-attrs cookie attributes (path, domain, max-age, secure, HttpOnly, etc) (since 1.4.46)
~'_usertrack.cookiename_'~ (deprecated)
usertrack.cookie-domain (deprecated; subsumed by usertrack.cookie-attrs since lighttpd 1.4.46)
usertrack.cookie-max-age (deprecated; subsumed by usertrack.cookie-attrs since lighttpd 1.4.46)

mod_vhostdb - virtual host database

option description
vhostdb.backend "dbi", "ldap", "mysql", or "pgsql"

mod_webdav - WebDAV

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

mod_wstunnel - WebSocket tunnel

option description
wstunnel.server backend server definition(s) for hosts to which to send requests; options for each backend host
wstunnel.balance load-balancing algorithm for backends ("fair", "least-connection", "round-robin", "hash", or "sticky")
wstunnel.debug debug level (value between 0 and 65535)
wstunnel.frame-type websocket frame type: "text" or "binary" map multiple extensions to the same backend list of permitted origins in Origin request header (optional) send websocket PING frame at given interval in sec (default 0; none sent)

gw_backend - gateway *.server host options

  • (e.g. dynamic backends fastcgi.server, scgi.server, proxy.server, wstunnel.server)
*.server option description
host ip of the backend process (DNS name is resolved to first IP at lighttpd startup (since 1.4.46))
port tcp-port on the "host" used by the backend process
socket path to the unix-domain socket
bin-path path to the local backend binary which should be started if no local backend is running
bin-environment set environment of backend binary
bin-copy-environment copy environment from server for backend binary
disable-time time to wait before a disabled backend is checked again
idle-timeout number of seconds before a unused process gets terminated
kill-signal signal to send backend on server shutdown (for backend daemons started by lighttpd) (since 1.4.46; since 1.4.14 for mod_fastcgi)
listen-backlog listen backlog queue size (for backend daemons started by lighttpd) (since 1.4.40)
max-load-per-proc maximum number of waiting processes on average per process before a new process is spawned (since 1.4.46)
max-procs upper limit of processes to start (default: 4)
min-procs sets the minimum processes to start (default: same as max-procs) (since 1.4.46)
  • (e.g. dynamic backends (HTTP-like) fastcgi.server, scgi.server, proxy.server)
*.server option description
x-sendfile controls if X-Sendfile header is allowed (since 1.4.40)
x-sendfile-docroot limits the directory trees permitted for use with X-Sendfile response header (since 1.4.40)
  • (e.g. dynamic backends (CGI-like) fastcgi.server, scgi.server)
*.server option description
check-local enable/disable check for requested file in document root (default: enabled)
docroot docroot on the remote host
broken-scriptfilename breaks SCRIPT_FILENAME in a way that PHP can extract PATH_INFO from it
fix-root-scriptname use this for backends with extension "/" (and check-local is disabled) (since 1.4.23)
strip-request-uri strip part of request-uri
mode FastCGI protocol mode. Default is "responder", also "authorizer" mode is implemented (since 1.4.46; available in mod_fastcgi in earlier versions)