NAME

download.cgi -- Organize a download directory

SYNOPSIS

RULES file example syntax:

  printfile MyHtmlTopStuff.html

  print <h2>tar files:</h2>
  list .*\.tar\.(gz|bz2)

  print <h2>zip files:</h2>
  list .*\.zip

  ignore *~

INSTALLING

Typically this can be installed by simply copying it to the directory it should serve and renaming it to index.cgi (e.g. /var/www/my-server/download/index.cgi) . Make sure to make it executable and make sure to create a RULES file for it to read.

You may need to set the ExecCGI option in an apache .htaccess file as well:

  Options +ExecCGI

RULES FILE PROCESSING

The script works by first reading in the RULES. file and caching the results. Each line is expected to be a comment (prefixed by a #), a blank line or a configuration token (described in the next section) followed by argument(s) to the end of the line.

The download.cgi script will then read in the directory in which it was placed and process each file according to the ordered set of rules loaded. The first matching rule will win and the output will be generated based on that rule.

CREATING RULES

There are a few different types of syntax lines can go into the RULES file. Per typical configuration files, lines starting with a # will be ignore as a comment.

Note: Configuration lines must not start with white-space, as this will be used to add optional configuration tokens to the rules in the future and the code already treats white-space starting lines differently.

Rule Options

Rule options can be created by prefixing a line with a white-space character. Thus, the following is a valid single rule definition that adds the "versionspaces" option to the rule:

    list .*.rpm
        versionspaces 1

Rules

printfile FILE

The printefile directive takes a single argument and simply dumps that file out. It's functionally equivelent to a "include" statement.

print TEXT

The print token simply prints the rest of the line to the output page. It is useful especially for quick header syntax above a list.

list REGEXP

This is the real power behind the download.cgi script. This allows you to group files in a directory by regular expression matching. The list will be printed using HTML <ul> and <li> style tags [future versions will allow for a more flexible output style].

The list will be sorted by version numbers as best as possible. The first number after a - will be considered the start of a version number and high version numbers will be sorted to higher in the displayed list (so 1.7.1 will be above 1.7). The version sorting algorithm treats .preN and .rcN suffixes differently so that 1.7.1.pre1 will be sorted below 1.7.1. [future versions will allow for a more flexible output style].

Note: make sure you realize that a regular expression is required and typical unix globbing is not supported (yet). IE, "*.tar.gz" is not a valid argument.

Extra options:

versionspaces 1

This adds a verical space between files of different versions. This is most useful for grouping file sets together such as multilpe RPMs that make up a single version set.

    list mypackage.*.rpm
        versionspaces 1

versionheaders 1

This adds version headers ahead of each section with different versions so the results look something like:

    + 1.3
      + dnssec-tools-1.3.rpm
      + dnssec-tools-libs-1.3.rpm

    + 1.2
      + dnssec-tools-1.2.rpm
      + dnssec-tools-libs-1.2.rpm

ignore REGEXP

This allows files to be ignored so that error messages about unknown files don't get printed to the web server's error log.

NOTES

This will likely only work with apache as the script expects the SCRIPT_FILENAME environment variable to be set, which may be an apache-ism.

TODO

The following features would be 'nice to haves:'

- sort by various other methods - suffix printing (ie, tar.gz, md5, sha, gpg, ...) - URL prefix other than current - generic list formatting mechanism - hover notes - caching of data for speed (based on directory modification time)

AUTHOR

Wes Hardaker <opensource@hardakers.net