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 libtar library; see:

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:


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



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.


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.


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.


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.


  TarOptions dereference

The currently implemented options are:


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.


To install mod_tar, copy the mod_tar.c file into:
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 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/libtar/include -L /path/to/libtar/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.


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:

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

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

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

© Copyright 2009 TJ Saunders
All Rights Reserved