ProFTPD module mod

ProFTPD module `mod_autohost`

For sites that run a large number of <VirtualHost> sections for ProFTPD, it can be cumbersome to configure them all in the proftpd.conf file. Adding or removing virtual server configurations requires restarting the daemon, as do changes to one of the server configurations. The daemon also consumes memory for each server configuration, and the memory footprint for the daemon process can grow large for large numbers of servers.

The mod_autohost module allows for server configurations to be configured in individual files, and for those configuration to be used in an on demand fashion. Rather than loading the configurations into memory when the daemon starts up, the daemon will check the IP address and port being contacted by a connecting client, check in the filesystem for a mod_autohost configuration file for that address/port, dynamically parse the configuration, and insert the configuration into the session's process space. Thus changes to the configuration are seen whenever a client connects, without requiring a daemon restart. The memory footprint is reduced because ProFTPD, via mod_autohost, only reads and uses the needed configuration.

This module is contained in the mod_autohost file for ProFTPD 1.3.x, and is not compiled by default. Installation instructions are discussed here.

The most current version of mod_autohost can be found at:

    https://github.com/Castaglia/proftpd-mod_autohost

Author

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

AutoHostConfig

Syntax: AutoHostConfig path
Default: None
Context: "server config"
Module: mod_autohost
Compatibility: 1.3.0rc1 and later

The AutoHostConfig directive specifies the path that mod_autohost checks for, when handling incoming connections. The given path must be an absolute path, and may contain the following variables, which will be interpolated:

%0

The entire IP address

%1

The first octet of an IPv4 address
%2

The second octet of an IPv4 address
%3

The third octet of an IPv4 address
%4

The fourth octet of an IPv4 address
%n

The name used by the client, either via TLS SNI or FTP HOST command
%p

The port number

Note: This directive is required for mod_autohost to function.

Examples
With an AutoHostConfig of:

  /etc/ftpd/vhosts/%0/autohost.conf

and a client connecting to 1.2.3.4, the above path would expand into:

  /etc/ftpd/vhosts/1.2.3.4/autohost.conf

Given a path of:

  /etc/ftpd/vhosts/%1/%2/%3/%4/%p/vhost.conf

and a client connecting to 1.2.3.4, port 2121, mod_autohost would check for the following file:

  /etc/ftpd/vhosts/1/2/3/4/2121/vhost.conf

AutoHostEngine

Syntax: AutoHostEngine on|off
Default: None
Context: "server config"
Module: mod_autohost
Compatibility: 1.3.0rc1 and later

The AutoHostEngine directive enables or disables the module's runtime checks for dynamic server configuration files. If it is set to off this module does no checking.

Use this directive to disable the module instead of commenting out all mod_autohost directives.

AutoHostLog

Syntax: AutoHostLog path
Default: None
Context: "server config"
Module: mod_autohost
Compatibility: 1.3.0rc1 and later

The AutoHostLog directive is used to a specify a log file for mod_autohost 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-writeable directory and, unless AllowLogSymlinks is explicitly set to on (generally a bad idea), the path must not be a symbolic link.

AutoHostPorts

Syntax: AutoHostPorts port1 ... portN
Default: None
Context: "server config"
Module: mod_autohost
Compatibility: 1.3.2rc1 and later

The AutoHostPorts directive is used to specify a list of port numbers on which proftpd should listen. By default, proftpd listens on a wildcard socket, which means that a single socket can be used to listen for all address for a given port. But there is no such thing as a socket which can listen on all ports. Thus mod_autohost needs to know when to listen on other ports.

Note that the AutoHostPorts directive is only needed if your AutoHostConfig path uses the "%p" variable (i.e. uses the port number to which the client connected as part of the path to the matching configuration).

For example, if your AutoHostConfig path included configurations for servers on non-standard ports, you would need to use the AutoHostPorts directive to list those ports, so that proftpd could handles connections to them:

  <IfModule mod_autohost.c>
    AutoHostEngine on
    AutoHostLog /etc/ftpd/var/autohost.log

    # This is required for mod_autohost to work
    AutoHostConfig /etc/ftpd/vhosts/%0/%p/autoconf.conf

    # Define the other non-standard ports for which we have config files
    AutoHostPorts 2121 2222 4444
  </IfModule>

Installation

To install mod_autohost, copy the mod_autohost.c file into:

  proftpd-dir/contrib/

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

  $ ./configure --with-modules=mod_autohost

Alternatively, mod_autohost could be built as a DSO module:

  $ ./configure --enable-dso --with-shared=mod_autohost

Then follow the usual steps:

  $ make
  $ make install

Usage

Example configuration:

  <IfModule mod_autohost.c>
    AutoHostEngine on
    AutoHostLog /etc/ftpd/var/autohost.log

    # This is required for mod_autohost to work
    AutoHostConfig /etc/ftpd/vhosts/%0/autoconf.conf
  </IfModule>

With this configuration, a client connecting to 1.2.3.4 would cause mod_autohost to look for the following path:

  /etc/ftpd/vhosts/1.2.3.4/autohost.conf

If the file is not present, proftpd handles the connection as it normally would.

Caveats
The SocketBindTight directive cannot be "on" if mod_autohost is to work directly. With SocketBindTight being off by default, proftpd listens for incoming connections on a wildcard socket, which will receive connections to all IP addresses on that port. mod_autohost relies on this behavior. If SocketBindTight is set to on, then proftpd will listen only to the addresses of the servers configured in proftpd.conf, and any autohost.conf files will be useless.

The DefaultServer directive will have no effect if it appears in an autohost.conf file.

The mod_tls module will not be able to properly prompt for passphrases for keys in an autohost.conf file on server startup.