ProFTPD module mod_prometheus

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

## Directives

- PrometheusEngine
- PrometheusExporter
- PrometheusLog
- PrometheusTables

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

© Copyright 2021 TJ Saunders
All Rights Reserved