Special files and URLs for directory listings

fhttpd uses special files in directories to determine the way, directories are displayed. Also some set of URLs is used to request dome form of directory listing and may be affected or overridden by special files.

Index files and trailing slash convention

URL, terminated by '/'(slash) is considered as a request for directory listing in its default form. If URL is requested without a trailing slash, but it corresponds to directory, redirection reply is sent to the client with target location equal to the requested URL with trailing slash added. Note that the redirection rule corresponds only to URLs that are mapped to filesystem, either using preloaded files or fhttpd-file module, URLs that are served by other modules can be redirected only by their modules regardless of filesystem. URLs, terminated by "/index.html" or "file_index.html" are also considered as requests for directory, however their processing differs from trailing slash URLs.

"index.html" and "file_index.html" are index files that are returned if the directory is requested. If none of them is present, generated directory listing is sent to the client. If one of them is present, it's sent as the response to all three requests: trailing slash, "index.html" and "file_index.html". If both are present, "file_index.html" is sent.

Generated directory listings

Directory listings are generated if either there is no index file, or client explicitly requested a generated listing.

Any request with URL, terminated by "file_index.html", but not "/file_index.html" and unless the file with such name really exists, is considered to be a request for a generated directory listing, with the directory wildcard-matching pattern as the URL without terminating "file_index.html". For example, http://host.domain.com/archive/*.tar.*file_index.html will request the generated listing of all files, matching the pattern "/home/ftp/archive/*.tar.*".

Note: in some cases it's unacceptable to allow listings of all directories on the HTTP server to be visible. To achieve that two solutions can be used:

1. Remove read permission for the user, used for the HTTP server. This will work also with FTP, if anonymous FTP and HTTP directory trees are the same.
   
   
2. Define restrictions in AccessRight line in the fhttpd configuration file. The lines

   AccessRights *file_index.html restrict
   AccessRights */file_index.html allow

   disallow all explicit directory requests. Additional lines like

   AccessRights /home/ftp/engineering/*file_index.html engineering :all:

   can be used to allow site maintainers to see directory listings over HTTP (in the example request for listing of any directory under /home/ftp/engineering/ will require an account in password file, used for realm "engineering").
   
   

Configuration file statements, used for generated directory listings

DefaultHeader defines the default header that is placed before the directory listing. It may contain any HTML markup, however following translation rules are used:

1. Spaces and tabs are prohibited.
2. Underscores ('_') are translated to spaces.
3. Backslash ('\') before any character passes that character literally, unless the character is a dollar sign ('$'), where backslash has no effect.
4. Dollar signs ('$') are translated in sequences as:
   • "$$" - dollar sign ('$'),
   • "$H" or "$h" - full hostname of the server,
   • "$D" or "$d" - directory, as in URL.
   In any other sequence dollar sign is ignored. Dollar sign translation is performed after backslash one, so "$\H" and "$H" sequences produce the same output.

DefaultFooter defines the default footer that is placed after the directory listing. Translation rules are the same as for DefaultHeader.

Type, AbsType, DirType and AbsDirType define, how files and subdirectories are represented in the directory listings. All four keywords have the same format of arguments - they should be followed by three arguments: wildcards mask, prefix, and suffix.

Wildcards mask defines the set of filenames, the statement is applied to.

• Type applies to files (not directories), and mask is checked against the path in URL.
• AbsType applies to files (not directories), and mask is checked against the real file path.
• DirType applies to directories, and mask is checked against the path in URL.
• AbsDirType applies to directories, and mask is checked against the real file path.

Matching is performed against statements in the order in the configuration file, so earlier records override later ones, and default records (with the mask "*") should be placed after other records for its class of filenames (files and directories).

Special files, used for generated directory listings

• If .header.html file in present in the directory, it is used as header for the directory listing.
• If .footer.html file in present in the directory, it is used as header for the directory listing.
• If .index.html file is present in the directory, it is used as an index file. Despite .html extension it's not really HTML file but a text that may contain the following types of lines:
  1. Lines that start with whitespace.

     Those lines are continuations of previous lines that do not start with whitespace (if such lines are present in the file).

  2. Lines that don't start with whitespace.

     First word (a string until the first whitespace or end of line) in the line is a filename, and the rest of the line and all subsequent lines contain the HTML comment for that filename.

  Comments are displayed only for files that are present in the directory.

  For example, the directory for raw mailing list archives has .index.html with:

  fhttpd.archive.9904 <FONT COLOR="#800000"><I>April 1999</I></FONT> fhttpd.archive.9905 <FONT COLOR="#800000"><I>May 1999</I></FONT> fhttpd.archive.9906 <FONT COLOR="#800000"><I>June 1999</I></FONT> fhttpd.archive.9907 <FONT COLOR="#800000"><I>July 1999</I></FONT> fhttpd.archive.9908 <FONT COLOR="#800000"><I>August 1999</I></FONT> fhttpd.archive.9909 <FONT COLOR="#800000"><I>September 1999</I></FONT> fhttpd.archive.9910 <FONT COLOR="#800000"><I>October 1999</I></FONT> fhttpd.archive.9911 <FONT COLOR="#800000"><I>November 1999</I></FONT> fhttpd.archive.9912 <FONT COLOR="#800000"><I>December 1999</I></FONT>

  and the corresponding generated HTML is:

  <DT><IMG SRC="/pictures/text.gif" ALIGN=TOP ALT=""> <A HREF="/ml/fhttpd/fhttpd.archive.9904">fhttpd.archive.9904</A> Sat Apr 10 02:21 (8079 bytes) <FONT COLOR="#800000"><I>April 1999</I></FONT>

  that looks like:

  fhttpd.archive.9904 Sat Apr 10 02:21 (8079 bytes) April 1999

Executables as index files

If the directory URL is covered by ExecMask, and the directory contains executable file exec_index, any request to the directory URL (with trailing slash, "/index.html" or "/file_index.html") will cause that file to be executed as regular CGI.

This rule overrides both index.html and file_index.html - if exec_index is present in such conditions, requests for both index files will call it even if real files with such names exist.