## ProFTPD module `mod_tar`

The `mod_tar` module supports on-the-fly creation of tar files. Whenever a client attempts to download a directory as a tar file, the `mod_tar` module will automatically create a tar file of that directory.

To provide this feature, the `mod_tar` module uses the `libarchive` library; see:

      http://libarchive.github.com/

This module is contained in the `mod_tar` file for ProFTPD 1.3.x, and is not compiled by default. Installation instructions are discussed here. More examples of `mod_tar` usage can be found here.

The most current version of `mod_tar` can be found at:

      http://www.castaglia.org/proftpd/

## Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

## Directives

- TarEnable
- TarEngine
- TarLog
- TarOptions
- TarTempPath

## TarEnable

Syntax: TarEnable on|off
Default: None
Context: `<Directory>`, `.ftpaccess` Module: mod_tar
Compatibility: 1.3.1rc1 and later

The `TarEnable` directive can be used to block or prevent a directory from being turned into a tar file by `mod_tar`.

## TarEngine

Syntax: TarEngine on|off
Default: off
Context: "server config", `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_tar
Compatibility: 1.3.1rc1 and later

The `TarEngine` directive enables or disables the module's support for on-the-fly tar file creation.

## TarLog

Syntax: TarLog file
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_tar
Compatibility: 1.3.1rc1 and later

The `TarLog` directive is used to a specify a log file for `mod_tar` reporting and debugging, and can be done a per-server basis. The file parameter must be the full path to the file to use for logging. Note that this path must not be to a world-writeable directory and, unless `AllowLogSymlinks` is explicitly set to on (generally a bad idea), the path must not be a symbolic link.

If file is "none", no logging will be done at all; this setting can be used to override a `TarLog` setting inherited from a `<Global>` context.

## TarOptions

Syntax: TarOptions opt1 ...
Default: None
Context: "server config", `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_tar
Compatibility: 1.3.1rc1 and later

The `TarOptions` directive is used to configure various optional behavior of `mod_tar`, usually pertaining to how the `.tar` files are constructed.

Example:

      TarOptions FollowSymlinks

The currently implemented options are:

- `FollowSymlinks`

  Instead of creating `.tar` files which include symlinks, include the files that the symlinks point to.

## TarTempPath

Syntax: TarTempPath path
Default: "./"
Context: "server config", `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_tar
Compatibility: 1.3.1rc1 and later

The `TarTempPath` directive controls the directory where `mod_tar` will writes its temporary `.tar` files. Keep in mind that the `TarTempPath` is subject to any chroot (i.e. use of `DefaultRoot` or `<Anonymous>`).

The default `TarTempPath` is "./", which means that the temporary `.tar` files are written in the current directory of the FTP session.

## Installation

To install `mod_tar`, copy the `mod_tar.c` file into:

      proftpd-dir/contrib/

after unpacking the latest proftpd-1.3.x source code. For including `mod_tar` as a staticly linked module:

      ./configure --with-modules=mod_tar

To build `mod_tar` as a DSO module:

      ./configure --enable-dso --with-shared=mod_tar

Then follow the usual steps:

      make
      make install

For those with an existing ProFTPD installation, you can use the `prxs` tool to add `mod_tar`, as a DSO module, to your existing server:

      # prxs -c -i -d -I /path/to/libarchive/include -L /path/to/libarchive/lib mod_tar.c

Note that in order to support gzip and bzip2 compression, the `mod_tar` module requires linking with the zlib (`-lz`) and bzip2 lib (`-lbz2`) libraries. You may need to install these packages on your system in order to build `mod_tar`.

## Usage

The `mod_tar` module works by watching all download requests (i.e. `RETR` commands), looking specifically for requests like:

     RETR $dir.tar.gz

The following extensions will trigger `mod_tar` to attempt on-the-fly tar file creation:

- .tar
- .tbz2
- .tgz
- .tar.gz
- .tar.bz2
- .zip

If the requested tar file already exists, then `mod_tar` does nothing, and lets the download proceed normally. If the requested tar file is not for a directory, then `mod_tar` does nothing.

Next, the `mod_tar` module checks for the existence of a "$dir/.notar" file. If this file is present, then `mod_tar` does nothing. (This provides feature compatibility with wu-ftpd's on-the-fly tar file creation feature.)

The `mod_tar` module then checks to see if `TarEnable` has been configured for the requested directory. For example, you can block certain directories from being bundled up by `mod_tar` by using:

      <Directory $dir>
        TarEnable off
      </Directory>

Once these checks have passed, a randomly generated unique filename is generated for the tar file to be created; the tar file is created in the session's current working directory (although this can be changed using the `TarTempPath` directive), and is deleted after the download finishes. This means that the client will need write privileges in that directory in order for the tar file to be created.

No external commands are used for creating the tar file. Searches for on-the-fly tar file creation will turn up reports of vulnerabilities and issues with the tar file feature in wu-ftpd. The problem there was that wu-ftpd used external commands, such as `/bin/tar`, to create the tar files. These commands take a range of command-line options; malicious FTP clients could exploit those command-line options, and wu-ftpd's on-the-fly tar file implementation, to attack the server. By contrast, the `mod_tar` module does not use any external commands; it uses the `libtar` library for creating the tar file. And `mod_tar` ensures that the requested path is indeed a directory and that that directory path is treated as-is, with no special interpolation or interpretation.

Example configuration:

      <IfModule mod_tar.c>
        TarEngine on
        TarLog /var/ftpd/tar.log
      </IfModule>

Author: $Author: tj $
Last Updated: $Date: 2009/08/20 17:07:14 $

© Copyright 2009-2012 TJ Saunders
All Rights Reserved