NAME

Apache::Archive - Expose archive files through the Apache web server.

SYNOPSIS

 <Files ~ "\.(tar|tgz|tar\.gz)">
 SetHandler perl-script
 PerlHandler Apache::Archive
 </Files>

DESCRIPTION

Apache::Archive is a mod_perl extension that allows the Apache HTTP server to expose tar and tar.gz archives on the fly. When a client requests such an archive file, the server will return a page displaying information about the file that allows the user to view or download individual files from within the archive.

Please read the BUGS section before using this on any production server

REQUIREMENTS

Apache::Archive requires mod_perl 1.11 or later, and Archive::Tar 0.2 or later. Note that Archive::Tar itself requires Compress::Zlib. Apache 1.3.6 or later is recommended. Earlier versions may well work too.

HTTPD CONFIGURATION PARAMETERS

Apache::Archive is a straightforward replacement for Apache's normal handler routine. There are currently three optional parameters that alter the way Apache::Archive functions. All of these are set using the PerlSetVar directive.

Months

This should be a comma seperated list of month names for Apache::Archive to use when generating dates. This allows you to use names other than English ones, or to use numbers. If this option is not specified it will default English three letter abbreviations.

Template

This is the location of a template file that Apache::Archive should use to generate the information page for the archive. If none is specified then it will use a built in default. See the section below for how to create a template file.

SizeLimit

This should be a number representing size in Kb. Once Apache has handled any archive file larger than this number, that Apache process will terminate. This is because Perl does not return allocated memory to the kernel, and processes tend to grow to the size of the largest file opened. Since Archive::Tar 0.2, tar files do not have to be held entirely in memory so this is less of a problem. If set to 0 or not set, this feature is disabled. You may also want to consider using Apache::SizeLimit if you OS supports it.

EXAMPLE

 <Files ~ "\.(tar|tgz|tar\.gz)">
 SetHandler perl-script
 PerlHandler Apache::Archive
 PerlSerVar Months '1,2,3,4,5,6,7,8,9,10,11,12'
 PerlSetVar Template /any/path/template.html
 PerlSetVar SizeLimit 5000
 </Files>

TEMPLATE CONFIGURATION FILE

Apache::Archive can read in an HTML file containing special tags and use that as a template for its output. The configuration file should be readable by the httpd process. It does not need to be in the document root. The template file must contain a special section delimited by ##StartData and ##EndData. This section httpd process. It does not need to be in the document root. The template file must contain a special section delimited by ##StartData and ##EndData. This section is repeated once for each component file in the archive, with any special tags being substituted with values of the current component file. A list of possible tags and what they are substituted with is shown below.

The first four tags provide information on the tar file itself, and can be used anywhere in the template file.

##ArchiveName

The name of the archive file currently being viewed.

##ArchiveDate

The last modification date of the archive file currently being viewed.

##ArchiveSize

The size of the archive file currently being viewed.

##ArchiveLink

An absolute URL that allows the user to download the archive file.

##StartData

A file in the archive. This tag should be place on a line by itself.

##EndData

Marks the end of the repeated section. This tag should be placed on a line by itself.

The next four tags provide information about one of the component files in the archive. These tags should only be used between the ##StartData and ##EndData tags.

##FileName

The name of the archived file.

##FileDate

The last modification date of the file.

##FileSize

The size of the file.

##FileLink

An absolute URL that allows the user to download the file.

This example is the template used by default.

        <HTML><BODY BGCOLOR="#cccccc">
        <H2>
        <A HREF=##ArchiveLink>##ArchiveName</A>
        </H2>
        ##ArchiveDate<BR>
        ##ArchiveSize<BR>
        This is the contents of the archive:
        <P>
        <TABLE border=4 cellpadding=6 cellspacing=2>
        <TR>
        <TH>View item</TH><TH>Name</TH><TH>Date</TH><TH>Size</TH>
        </TR>
        ##StartData
        <TR>
                <TD><A HREF=##FileLink>View File</A></TD>
                <TD>##FileName</TD><TD>##FileDate</TD>
                <TD>##FileSize</TD>
        </TR>
        ##EndData
        </TABLE></BODY></HTML>

BUGS

MEMORY LEAK

There is a problem with memory leakage. This is greatly reduced with Archive::Tar 0.2 and later. Still, if you have a busy site, I advise checking memory consumption, and experimenting with the SizeLimit variable, or with Apache::SizeLimit. Expect processes to be 10Mb and more.

No error checking on template file

If you create a faulty template file, the server will attempt to use it regardless and may behave unpredictably.

Tar files within tar files

If an archive contains other archives, the sub-archives are not passed through the Apache::Archive handler - they are simply treated as regular files. This is not really a bug per se, more a missing feature.

No support for .zip files

This will be added later.

AUTHOR

J. Peterson, jon@snowdrift.org

COPYRIGHT

Copyright 1998-1999, J. Peterson

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

If you have questions or problems regarding use or installation of this module please feel free to email me directly.

SEE ALSO

Apache, Archive::Tar, Compress::Zlib, Apache::SizeLimit

cpanm Apache::Archive

perl -MCPAN -e shell
install Apache::Archive