Project

General

Profile

Actions
History

Docs »

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

Since lighttpd 1.4.60, an option is available 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.

Since lighttpd 1.4.74, an option is available to configure mod_dirlisting to disable server-side sorting of the directory, allowing client-side javascript (if enabled) to sort the listing on the client before displaying.
@dir-listing.sort = "disable"

Another option is to configure mod_indexfile to generate the directory listing and to potentially cache the result.
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.php 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, originally contributed from http://www.archerseven.com/kittykatt/index.php?page=scripts&sub=lighttpdlisting

JSON listing

With lighttpd 1.4.72 and later, mod_dirlisting can produce JSON output if the request contains the query string ?json
https://example.org/path/to/dir/?json

Options

dir-listing.activate

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

dir-listing.sort

(since 1.4.74) controls alphabetical sorting of directory listing on server before page is served
Historically, mod_dirlisting sorts the results on the server in case client does not have javascript enabled.
This config options allows directory sorting to be disabled on the server.
(javascript, if enabled, can still sort directory listing on the client before displaying the page)
On low-resource systems, it is recommended to disable this feature if serving directories containing a very, very large number of entries.
default value: enable

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

Sample CSS

dir-listing.external-css = "..." can be used to specify an alternative CSS for inclusion by mod_dirlisting

lighttpd mod_dirlisting default stylesheet params (if dir-listing.external-css is not configured)

a, a:active {text-decoration: none; color: blue;}
a:visited {color: #48468F;}
a:hover, a:focus {text-decoration: underline; color: red;}
body {background-color: #F5F5F5;}
h2 {margin-bottom: 12px;}
table {margin-left: 12px;}
th, td {font: 90% monospace; text-align: left;}
th {font-weight: bold; padding-right: 14px; padding-bottom: 3px;}
td {padding-right: 14px;}
td.s, th.s {text-align: right;}
div.list {background-color: white; border-top: 1px solid #646464; border-bottom: 1px solid #646464; padding-top: 10px; padding-bottom: 14px;}
div.foot {font: 90% monospace; color: #787878; padding-top: 4px;}

user-contributed CSS for directory listing (by lucianor) (https://github.com/lighttpd/lighttpd1.4/pull/126)

a, a:active {text-decoration: none; color: blue;}
a:visited {color: #48468F;}
a:hover, a:focus {text-decoration: underline; color: red;}
body {background-color: #F5F5F5;}
h2 {margin-bottom: 12px;}
table {margin-left: 12px; max-width: 100%; width: 100%;  margin-bottom: 20px; background-color: #ffffff;}
table > thead > tr > th, table > tbody > tr > th, table > tfoot > tr > th, table > thead > tr > td, table > tbody > tr > td, table > tfoot > tr > td {padding: 8px; line-height: 1.42; vertical-align: top; border-top: 1px solid #dddddd;}
table > thead > tr > th {vertical-align: bottom; border-bottom: 2px solid #dddddd;}
table > tbody + tbody {border-top: 2px solid #dddddd;}
th, td {font: 90% monospace; text-align: left;}
th {font-weight: bold; padding-right: 14px; padding-bottom: 3px;}
td {padding-right: 14px;}
td.s, th.s {text-align: right;}
div.list {background-color: white; border-top: 1px solid #646464; border-bottom: 1px solid #646464; padding-top: 10px; padding-bottom: 14px;}
div.foot {font: 90% monospace; color: #787878; padding-top: 4px;}

Updated by gstrauss about 1 year ago · 40 revisions