Project

General

Profile

Mod dirlisting » History » Revision 38

Revision 37 (gstrauss, 2021-04-07 04:17) → Revision 38/40 (gstrauss, 2023-06-03 18:43)

{{>toc}} 

 h1. mod_dirlisting - Directory Listings 


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


 h2. 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" 
    } 


 h2. 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 [[Docs_ModIndexFile|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: 

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


 h2. Options 

 h3. dir-listing.activate 

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

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

 h3. dir-listing.hide-dotfiles 

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

 h3. dir-listing.external-css 

 URL to an external css stylesheet for the directory listing. 

 h3. dir-listing.external-js 

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

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

 h3. 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" 

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

 h3. dir-listing.hide-readme-file 

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

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

 h3. dir-listing.hide-header-file 

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

 h3. 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" 



 h4. The following 3 options are currently available as of 1.4.23: 


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

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

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

 h2. Table sorting 

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

 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 

 h2. 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) 
 <pre> 
 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;} 
 </pre> 

 user-contributed CSS for directory listing (by lucianor) (https://github.com/lighttpd/lighttpd1.4/pull/126) 
 <pre> 
 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;} 
 </pre>