• Table of contents
• mod_dirlisting - Directory Listings
  • Description
  • Quick Start
  • Performance
  • Options
    • dir-listing.activate
    • dir-listing.cache
    • dir-listing.hide-dotfiles
    • dir-listing.external-css
    • dir-listing.external-js
    • dir-listing.exclude
    • dir-listing.encoding
    • dir-listing.show-readme
    • dir-listing.hide-readme-file
    • dir-listing.show-header
    • dir-listing.hide-header-file
    • dir-listing.set-footer
      • The following 3 options are currently available as of 1.4.23:
    • dir-listing.encode-header
    • dir-listing.encode-readme
    • dir-listing.auto-layout
  • Table sorting

mod_dirlisting - Directory Listings¶

Description¶

mod_dirlisting creates an HTML page listing the contents of the target directory.

mod_dirlisting is disabled by default; to enable: dir-listing.activate = "enable"

While lighttpd provides a handful of options to tweak how the directory listing is generated, there is no one-size-fits-all. If you want or need something custom, then you are welcome to use a custom generator (e.g. using Python or PHP) instead of using mod_dirlisting.

Quick Start¶

A directory listing is generated if a directory is requested and no index-file was found in that directory.

To enable directory listings globally:

dir-listing.activate = "enable"

If you need it only for a specific directory or directories, use conditionals:

$HTTP["url"] =~ "^/download($|/)" {
     dir-listing.activate = "enable" 
   }

Performance¶

Creating a directory listing can be expensive, using CPU and memory, and taking much more time than serving a static file, especially on large directories. If the target directory does not change frequently, it can be much more efficient to use mod_indexfile instead of mod_dirlisting. If using mod_indexfile, you can generate index.html via an external process when the contents of the directory changes (e.g. when publishing a new version of the site). Another option is to configure mod_indexfile to generate the directory listing and to potentially cache the result. Starting with lighttpd 1.4.60, a new alternative is to configure mod_dirlisting to cache the directory listing for a (short) period of time, to reduce the number of times the directory listing is generated within the caching period.
dir-listing.cache = ( "path" => "/path/to/dirlist-cache", "max-age" => 15 )
The default cache period is 15 seconds ("max-age" => 15) if not otherwise specified.

You can also use an external generator for directory listings if you use mod_indexfile.

index-file.names = ( "/dir-generator.php" )

If a directory is requested, the dir-generator.php is called instead which can take the REQUEST_URI to see which directory was requested. Note that the target dir-generator path must exist in the filesystem, or else mod_indexfile will skip it. (In other words, the dir-generator must exist, even as an empty file, for mod_indexfile even if the target is handled by mod_fastcgi or mod_scgi and configured with "check-local" => "disable")

The dir-generator.php file can be found at the bottom of this document or at:

http://www.archerseven.com/kittykatt/index.php?page=scripts&sub=lighttpdlisting

Options¶

dir-listing.activate¶

enables virtual directory listings if a directory is requested no index-file was found.
default value: disable

dir-listing.cache¶

default value: none (disabled)
Starting with lighttpd 1.4.60, mod_dirlisting can be configured to cache the directory listing for a (short) period of time, in order to reduce the number of times the directory listing is generated within the caching period.
dir-listing.cache = ( "path" => "/path/to/dirlist-cache", "max-age" => 15 )
The default cache period is 15 seconds ("max-age" => 15) if not otherwise specified.

dir-listing.hide-dotfiles¶

if enabled, does not list hidden files in directory listings generated by the dir-listing option.
default value: enable

dir-listing.external-css¶

URL to an external css stylesheet for the directory listing.

dir-listing.external-js¶

URL to an external js script, e.g. for client side directory list sorting (lighttpd 1.4.42)

dir-listing.exclude¶

list of regular expressions. Files that match any of the specified regular expressions will be excluded from directory listings.

Use inside of conditionals was broken before 1.4.14. See #1260.

dir-listing.encoding¶

set a encoding for the generated directory listing.

If your file-system is not using ASCII you have to set the encoding of the filenames as they are put into the HTML listing AS IS (with XML encoding).

Example:

dir-listing.encoding = "utf-8"

default value:

dir-listing.encoding = "iso-8859-1"

dir-listing.show-readme¶

show the contents of the README.txt file after the directory listing.
(since 1.4.43, can be user-specified filename instead of README.txt)
(since 1.4.46, path starting with '/' is treated as absolute path in filesystem)
default value: disable

dir-listing.hide-readme-file¶

hide README.txt files from the directory listing.
default value: disable

dir-listing.show-header¶

show the contents of the HEADER.txt file before the directory listing.
(since 1.4.43, can be user-specified filename instead of HEADER.txt)
(since 1.4.46, path starting with '/' is treated as absolute path in filesystem)
default value: disable

dir-listing.hide-header-file¶

hide HEADER.txt files from the directory listing.
default value: disable

dir-listing.set-footer¶

displays a string in the footer of a listing page.
default value: "<PACKAGE_NAME>/<PACKAGE_VERSION>" ie. "lighttpd/1.4.18"

The following 3 options are currently available as of 1.4.23:¶

dir-listing.encode-header¶

this option is a boolean.
It gives the ability to provide a valid html file as HEADER.txt, this file is just printed before the actual listing. See also dir-listing.encode-readme.
default value: enable

dir-listing.encode-readme¶

this option is a boolean.
It gives the ability to provide a valid html file as README.txt, this file is just printed after the actual listing. See also dir-listing.encode-header.
default value: enable

dir-listing.auto-layout¶

this option is a boolean.
When disabled, it will remove the html part lighttpd was automatically outputing as the start of the page and the end (from <DOCTYPE to <body> and </body></html>). This lets the possibility to take care of those parts in the header and readme files.
default value: enable

Table sorting¶

Since lighttpd 1.4.42, a default set of javascript is included to enable directory listing table sorting (as long as dir-listing.auto-layout = "enable", the default, and as long as the javascript is not replaced by custom code specified bydir-listing.external-js).

A partial implementation of Apache autoindex request query arguments (https://httpd.apache.org/docs/current/en/mod/mod_autoindex.html) are available to influence how the table of directory contents is initially sorted.

If query string is supplied in the URL request for the dir-listing, allow specifying initial column to sort

• ?C=N name (default)
• ?C=M last-modified, then by name
• ?C=S size, then by name
• ?C=T type, then by name
• ?C=D type, then by name

and O=[AD] can be added for descending or ascending order, e.g.

• ?C=N&O=D descending (default)
• ?C=N&O=A ascending