ProFTPD module mod_deflate

## ProFTPD module `mod_deflate`

The `mod_deflate` module is designed to provide support for `MODE Z` commands, which allows FTP clients and servers to compress data for transfer.

This module is contained in the `mod_deflate.c` file for ProFTPD 1.3.x, and is not compiled by default. Installation instructions are discussed here. Detailed documentation on `mod_deflate` usage can be found here.

The most current version of `mod_deflate` 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

- DeflateEngine
- DeflatefLog

### DeflateEngine

Syntax: DeflateEngine on|off
Default: off
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_deflate
Compatibility: 1.3.0rc1 and later

The `DeflateEngine` directive enables or disables the `mod_deflate` compression functionality. If set to on, then `mod_deflate` will advertise support for `MODE Z` compression via the `FEAT` command, and handle `MODE Z` requests appropriately.

### DeflateLog

Syntax: DeflateLog path|"none"
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_deflate
Compatibility: 1.3.0rc1 and later

The `DeflateLog` directive is used to a specify a log file for `mod_deflate` reporting and debugging. The path parameter must be the full path to the file to use for logging. Note that this path must not be to a world-writable directory and, unless `AllowLogSymlinks` is explicitly set to on (generally a bad idea), the path must not be a symbolic link.

If path is "none", no logging will be done at all.

## Installation

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

      proftpd-dir/contrib/

after unpacking the latest proftpd-1.3.x source code. Then follow the usual steps for using third-party modules in proftpd:

      ./configure --with-modules=mod_deflate
      make
      make install

## Usage

Example `mod_deflate` configuration:

      <IfModule mod_deflate.c>
        DeflateEngine on
        DeflateLog /var/log/proftpd/deflate.log
      </IfModule>

Sites that run `proftpd` 1.3.0 should disable sendfile use when using `mod_deflate`, as the two features do not interoperate well:

      <IfModule mod_deflate.c>
        DeflateEngine on
        DeflateLog /var/log/proftpd/deflate.log

        UseSendfile off
      </IfModule>

Frequently Asked Questions

Question: I have compiled and configured `mod_deflate` properly in my `proftpd`, but I still can't use the MODE Z functionality. In my client, I see the following error. Why?

      501 'MODE Z' unrecognized transfer mode

Answer: The most likely culprit is that your FTP client is using an RFC 2228 protection mechanism (e.g. SSL/TLS). In the `DeflateLog`, you might see a message like:

      Jul 21 23:01:37 mod_deflate/0.3.2[31084]: declining MODE Z (RFC2228 mechanism 'TLS' in effect)

There are two reasons for the current behavior. First, the SSL/TLS ciphersuite that is negotiated can (depending on the ciphersuite) already include compression of the encrypted data -- in which case, `MODE Z` is redundant (and in effect inefficient, as it would waste CPU cycles trying to re-compress already-compressed data). Second, the internal ProFTPD APIs that `mod_deflate` uses are the same APIs that `mod_tls` uses; and that API does not currently handle chaining together of registered handlers. This would be needed in order to support `mod_deflate`'s `MODE Z` functionality and the `mod_tls` encryption at the same time.

Question: I'm uploading a file using `MODE Z`, but the upload always fails. In the `DeflateLog`, I see:

     error inflating data: [-3] Data error

What is going wrong? It is a `mod_deflate` bug?
Answer: The most common cause of this error is when the client is trying to upload a binary file (e.g. PDF, MPG, etc) in ASCII mode.

If `MODE Z` is not used in cases like this, the upload succeeds, but the uploaded file on the server is corrupted. When `MODE Z` is in effect, the corruption (translation of newlines inappropriately) is detected earlier (since `mod_deflate` can't uncompress the compressed data properly, hence the report of a "Data error"), and the upload fails.

The solution is make sure that the client uploads (and downloads) non-ASCII files as binary files, not as ASCII files.

Author: $Author: castaglia $
Last Updated: $Date: 2010/03/10 15:56:58 $

© Copyright 2006-2010 TJ Saunders
All Rights Reserved