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:


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



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.


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 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.


The mod_deflate module is distributed with ProFTPD. Follow the usual steps for using third-party modules in ProFTPD:
  $ ./configure --with-modules=mod_deflate
To build mod_deflate as a DSO module:
  $ ./configure --enable-dso --with-shared=mod_deflate
Then follow the usual steps:
  $ make
  $ make install

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

  $ prxs -c -i -d mod_deflate.c


Example mod_deflate configuration:

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

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

The mod_deflate module supports different forms of logging. The main module logging is done via the DeflateLog directive. For debugging purposes, the module also uses trace logging, via the module-specific log channels:

Thus for trace logging, to aid in debugging, you would use the following in your proftpd.conf:
  TraceLog /path/to/ftpd/trace.log
  Trace deflate:20
This trace logging can generate large files; it is intended for debugging use only, and should be removed from any production configuration.

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.

© Copyright 2006-2014 TJ Saunders
All Rights Reserved