ProFTPD module mod

ProFTPD module `mod_prometheus`

The purpose of the mod_prometheus module is to provide metrics for scraping by Prometheus.

Installation instructions are discussed here. Note that mod_prometheus requires ProFTPD 1.3.7a or later. Detailed notes on best practices for using this module are here.

The most current version of mod_prometheu can be found at:

  https://github.com/Castaglia/proftpd-mod_prometheus.git

Author

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

PrometheusEngine

Syntax: PrometheusEngine on|off
Default: off
Context: server config
Module: mod_prometheus
Compatibility: 1.3.7a and later

The PrometheusEngine directive controls whether the mod_prometheus module lists for Prometheus HTTP requests for scraping metrics.

PrometheusExporter

Syntax: PrometheusExporter address[:port] [username password]
Default: None
Context: server config
Module: mod_prometheus
Compatibility: 1.3.7a and later

The PrometheusExporter directive configures the mod_prometheus module to act as an exporter for scraping by Prometheus.

Note that the PrometheusExporter directive is required.

The address parameter can be an IP address or a DNS name; this parameter configures the address/port on which mod_prometheus will listen for Prometheus scrape requests. By default, a port of 9273 is assumed; use address:port to specify an alternate port, e.g.:

  PrometheusExporter 0.0.0.0:19273

Note that IPv6 addresses should be enclosed in square brackets, as they can contain colons as well, e.g.:

  PrometheusExporter [::]:19273

HTTP basic authentication can be required by providing the optional username and password parameters. The following environment variables can also be used, instead of configuring these credentials in the config file:

PROMETHEUS_USERNAME
PROMETHEUS_PASSWORD

PrometheusLog

Syntax: PrometheusLog path|"none"
Default: None
Context: server config
Module: mod_prometheus
Compatibility: 1.3.7a and later

The PrometheusLog directive is used to specify a log file for mod_prometheus's reporting. The path parameter given 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.

PrometheusTables

Syntax: PrometheusTables path
Default: None
Context: server config
Module: mod_prometheus
Compatibility: 1.3.7a and later

The PrometheusTables directive is used to specify a directory that mod_prometheus will use for storing its database files; these files are used for tracking the various statistics reported via Prometheus.

Note that the PrometheusTables directive is required.

Usage

Important Security Considerations
Do not configure mod_prometheus to listen on a public Internet address. The information provided via mod_prometheus can be used by attackers to gain more information about your running proftpd, including being able to determine whether their logins fail due to a wrong password (in which case, they know that that user name is valid) or not. It is highly recommended that you configure mod_prometheus to only listen on internal/LAN addresses. Furthermore, you should employ a firewall rule that rejects any TCP connections from the public Internet to your mod_prometheus exporter.

That said, things are a little different when running in an e.g. Kubernetes cluster, with an isolated network. In these cases, given that Kubernetes pods will have dynamic IP addresses, the recommended configuration is to listen on the wildcard address, i.e. "0.0.0.0". This works because the Kubernetes cluster network is already isolated from the public Internet by default.

Prometheus Exporter Process
When proftpd starts up with mod_prometheus enabled, the mod_prometheus module will fork a new process that acts as the Prometheus exporter, receiving and responding to all scrape requests. This exporter listening process automatically switches to the privileges configured by the User and Group directives, and will also automatically chroot itself to a subdirectory of the PrometheusTables directory, after which all root privileges are permanently dropped.

Example Configuration
The mod_prometheus module uses an HTTP server for listening for Prometheus scrape requests. Thus it does not require any separate <VirtualHost> sections, and does not interfere with the normal FTP operations.

Here is an example configuration for mod_prometheus:

  <IfModule mod_prometheus.c>
    PrometheusEngine on
    PrometheusLog /etc/proftpd/prometheus/prometheus.log

    # Configure the exporter to listen on the default port
    PrometheusExporter 0.0.0.0

    # Configure the directory that mod_prometheus will use for its database files
    PrometheusTables /var/proftpd/prometheus
  </IfModule>

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

prometheus
prometheus.db
prometheus.http
prometheus.metric
prometheus.metric.db
prometheus.registry
prometheus.text

Thus for trace logging, to aid in debugging, you would use the following in your proftpd.conf:

  TraceLog /path/to/proftpd-trace.log
  Trace prometheus:20

This trace logging can generate large files; it is intended for debugging use only, and should be removed from any production configuration.

Installation

To install mod_prometheus, go to the third-party module area in the proftpd source code and unpack the mod_prometheus source tarball:

  $ cd proftpd-dir/contrib/
  $ tar zxvf /path/to/mod_prometheus-version.tar.gz

after unpacking the latest proftpd-1.3.x source code. For including mod_prometheus as a statically linked module:

  $ ./configure --with-modules=mod_prometheus:...

To build mod_prometheus as a DSO module:

  $ ./configure --enable-dso --with-shared=mod_prometheus:...

Then follow the usual steps:

  $ make
  $ make install

Note: mod_prometheus uses the SQLite library; thus the sqlite3 development library/headers must be installed for building mod_prometheus.

It is highly recommended that SQLite 3.8.5 or later be used. Problems have been reported with mod_prometheus when SQLite 3.6.20 is used; these problems disappeared once SQLite was upgraded to a newer version. Note: mod_prometheus uses the libmicrohttpd library; thus the libmicrohttpd development library/headers must be installed for building mod_prometheus.