NAME

jail_exporter — Prometheus exporter for jail metrics

SYNOPSIS

jail_exporter [-hV] [--help] [--version] [--rc-script]

jail_exporter [--output.file-path=path] [--web.auth-config=path] [--web.listen-address=addr:port] [--web.telemetry-path=path]

jail_exporter bcrypt [--random] [--cost=cost] [--length=length] [password]

DESCRIPTION

Command Line Arguments

jail_exporter is a Prometheus exporter for jail metrics. The options are as follows:

-h, --help: Prints help information
-V, --version: Prints version information
--rc-script: Dumps the jail_exporter rc(8) script to stdout. This crate feature is disabled by default when installed from pkg(8) or ports(7) as they supply a suitable rc(8) script already.
--output.file-path=path: Specify a path to write collected metrics to. When jail_exporter is given a path it will exit immediately after writing the metrics and the HTTPd will not be started. This option is designed to be paired with the Node Exporter Textfile Collector. Giving a path of “-” will output collected metrics to stdout.
--web.auth-config=path: Specify a path to load HTTP Basic Authentication configuration from. The configuration is in the YAML format and is documented in the EXAMPLES section. There is no default location for this configuration file, but a location such as /usr/local/etc/jail_exporter.yaml or /usr/local/etc/jail_exporter/config.yaml is suggested.
--web.listen-address=addr:port: Specify an addr:port on which to expose the metrics and web interface. Defaults to “127.0.0.1:9452”. If specifying an IPv6 addr:port the address portion should be enclosed within square brackets, for example: “[::1]:9452”.
--web.telemetry-path=path: Specify a path under which to expose the metrics. Defaults to “/metrics”.

Sub-Commands

jail_exporter also features a bcrypt sub-command, useful for hashing the passwords used for HTTP Basic authentication. This sub-command features the following arguments:

--random: Generates a random password and outputs both the plaintext and hashed values.
--cost=cost: Specifies the bcrypt cost of the hash. Defaults to “12”.
--length=length: Specifies the password length to generate when used with the --random flag. Defaults to “32”.
password: Optionally specify a password to hash. If a password is not specified, it is interactively prompted for.

HTTP Basic Authentication Configuration

HTTP basic authentication is configured via a YAML configuration file. The format of this file follows the suggestions of the Prometheus exporter-toolkit. This authentication configuration consists of a “basic_auth_users” key which is a map of usernames to bcrypt hashed passwords. These hashes can be generated with the jail_exporter bcrypt sub-command or any other utility capable of generating bcrypt hashes. Any keys in the file other than “basic_auth_users” are ignored.

An example HTTP basic authentication configuration can be found in the EXAMPLES section.

USAGE

jail_exporter must be run as “root” in order to access the required rctl(8) APIs. Although FreeBSD ships with RACCT/RCTL support in the kernel, it is disabled by default. It can be enabled by setting kern.racct.enable="1" in /boot/loader.conf. After setting this, a reboot will be required to enable RACCT/RCTL.

METRICS

The metrics that are exported are those listed in the RESOURCES section of rctl(8), and the following additional metrics:

exporter_build_info: The version of the currently running exporter, and the version of Rust used to build the exporter. The version is given in the “version” label on the metric, while the Rust version used to build the exporter is given in the “rustversion” label. Does not possess a “name” label.
id: The ID of the named jail
num: The current number of jails running. Does not possess a “name” label.

All metrics are prefixed with the string “jail_” and in most cases (except for the metrics mentioned above) possess a “name” label containing the name of the jail. An example of a metric output by the exporter would be:

# HELP jail_cputime_seconds_total CPU time, in seconds
# TYPE jail_cputime_seconds_total counter
jail_cputime_seconds_total{name="test"} 300

ENVIRONMENT VARIABLES

jail_exporter can also take its configuration from environment variables. In the event that both command line options and environment variables are specified, the command line options will win.

OUTPUT_FILE_PATH: is equivalent to setting the --output.file-path option.
WEB_AUTH_CONFIG: is equivalent to setting the --web.auth-config option.
WEB_LISTEN_ADDRESS: is equivalent to setting the --web.listen-address option.
WEB_TELEMETRY_PATH: is equivalent to setting the --web.telemetry-path option.

FILES

/usr/local/etc/rc.d/jail_exporter: the rc(8) script
/usr/local/sbin/jail_exporter: the exporter daemon

EXAMPLES

HTTP Basic Authentication

Simple configuration file for two users:

---

basic_auth_users:

  foo:
  '$2b$12$cGBwrALG2Crkm5jPdvzlG.R8.j8LMeCEecm4y/So6YVd4YiIrfqsW'

  bar:
  '$2b$12$8c6yHGFexzAvbtNSHV3WNO0zJoaWfDy9WqX7s8vCAajV08LE/cW06'

Sub-Commands

Generating a bcrypt password hash by specifying the password on the command line using the default bcrypt cost:

$ jail_exporter bcrypt
  foopass

Generating a random bcrypt password hash with an increased cost and custom length:

$ jail_exporter bcrypt --random
  --cost 14 --length 48

Generating a bcrypt password via the interactive prompt:

$ jail_exporter bcrypt

HISTORY

jail_exporter was started during the summer of 2018 on FreeBSD 11.1.

AUTHORS

jail_exporter was developed by David O'Rourke with contributions from
Fabian Freyer.

BUGS

Please report bugs, issues, and feature requests to https://github.com/phyber/jail_exporter/issues