/ 
Apache2-Archive-0.1
River stage zero No dependents
/ Apache2::Archive

NAME

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

SYNOPSIS

<Files ~ "\.(tar|tgz|tar\.gz)">
 PerlResponseHandler Apache2::Archive
</Files>

DESCRIPTION

Apache2::Archive is a mod_perl 2 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.

Apache2::Archive is an almost fidedign port of the Apache2::Archive module by Jon Peterson.

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

HTTPD CONFIGURATION PARAMETERS

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

Months

This should be a comma seperated list of month names for Apache2::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 Apache2::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)">
PerlResponseHandler Apache2::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

Apache2::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 Apache2::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, made the original Apache::Archive module. David Moreno, david@axiombox.com, made the port to mod_perl 2.

COPYRIGHT

Copyright 1998-1999, J. Peterson Copyright 2008, David Moreno

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

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 482:

'=item' outside of any '=over'