From 7899e4db2588c69c710f8f8e4f08760ce7e0da43 Mon Sep 17 00:00:00 2001 From: Hector Date: Sun, 20 Feb 2022 12:46:50 +0000 Subject: [PATCH] finish rewriting readme file --- README.md | 181 +++++++++++------------------------------------------- 1 file changed, 35 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 88ab315..c195e1f 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,9 @@ Collect metrics from a running fail2ban instance. ## Table of Contents 1. Quick Start 2. Metrics - -3. Running the Exporter -4. Running in Docker -5. Metrics +3. Configuration +4. Building +5. Textfile metrics ## 1. Quick Start @@ -52,6 +51,10 @@ services: - "9191:9191" ``` +**NOTE:** While it is possible to mount the `fail2ban.sock` file directly, it is recommended to mount the parent folder instead. +The `.sock` file is deleted by fail2ban on shutdown and re-created on startup and this causes problems for the docker mount. +See [this reply](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/issues/11#note_665003499) for more details. + ## 2. Metrics The exporter exposes the following metrics: @@ -74,6 +77,18 @@ The exporter exposes the following metrics: | `jail_config_max_retry` | The max number of failures allowed before banning an IP in this jail | `f2b_config_jail_max_retries{jail="sshd"} 5` | | `version` | Version string of the exporter and fail2ban | `f2b_version{exporter="0.5.0",fail2ban="0.11.1"} 1` | +The metrics above correspond to the matching fields in the `fail2ban-client status ` command: +``` +Status for the jail: sshd|- Filter +| |- Currently failed: 6 +| |- Total failed: 125 +| `- File list: /var/log/auth.log +`- Actions + |- Currently banned: 15 + |- Total banned: 31 + `- Banned IP list: ... +``` + ### 2.1. Grafana The metrics exported by this tool are compatible with Prometheus and Grafana. @@ -82,42 +97,14 @@ Just import the contents of this file into a new Grafana dashboard to get starte *(Sample dashboard is compatible with Grafana `8.3.3` and above)* +## 3. Configuration +The exporter is configured with CLI flags and environment variables. +There are no configuration files. - ---- - - - - - - -## 1. Introduction -This exporter collects metrics from a running fail2ban instance. - -Once the exporter is running, metrics are available at `localhost:9191/metrics`. - -(The default port is `9191` but can be modified with the `--web.listen-address` flag) - -The exporter communicates with the fail2ban server over its socket. -This allows the data collected by the exporter to always align with the output of the `fail2ban-client`. - -The default location of the socket is: `/var/run/fail2ban/fail2ban.sock` - - -## 2. Running the Exporter - -The exporter is compiled and released as a single binary. -This makes it very easy to run in any environment. -No additional runtime dependencies are required. - -Compiled binaries for various platforms are provided in each release. -See the [releases page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/releases) for more information. - -**CLI Usage** +**CLI flags** ``` -$ fail2ban_exporter -h -usage: fail2ban-prometheus-exporter [] +usage: fail2ban_exporter [] Flags: -h, --help Show context-sensitive help (also try --help-long and --help-man). @@ -136,123 +123,25 @@ Flags: **Environment variables** -The tool can also be configured using environment variables. Each CLI parameter has a corresponding environment variable. +Each environment variable corresponds to a CLI flag. +If both are specified, the CLI flag takes precedence. -``` -F2B_COLLECTOR_SOCKET -F2B_COLLECTOR_TEXT_PATH -F2B_WEB_LISTEN_ADDRESS -F2B_WEB_BASICAUTH_USER -F2B_WEB_BASICAUTH_PASS -``` +| Environment variable | CLI flag | +|---------------------------|----------------------------------| +| `F2B_COLLECTOR_SOCKET` | `--collector.f2b.socket` | +| `F2B_COLLECTOR_TEXT_PATH` | `--collector.textfile.directory` | +| `F2B_WEB_LISTEN_ADDRESS` | `--web.listen-address` | +| `F2B_WEB_BASICAUTH_USER` | `--web.basic-auth.username` | +| `F2B_WEB_BASICAUTH_PASS` | `--web.basic-auth.password` | -**Example** - -``` -fail2ban-prometheus-exporter --collector.f2b.socket=/var/run/fail2ban/fail2ban.sock --web.listen-address=":9191" -``` - -Note that the exporter will need read access to the fail2ban socket. - -### 2.1. Compile from Source +## 4. Building The code can be compiled from source by running `go build` inside the `src/` folder. Go version `1.15` or greater is required. Run `go mod download` to download all necessary dependencies before running the build. -## 3. Running in Docker - -An official docker image is available on the Gitlab container registry. -Use it by pulling the following image: - -``` -registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest -``` - -Use the `:latest` tag to get the latest stable release. Or use the `:nightly` tag for the latest (unstable) version. -See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/container_registry) for all available tags. - -### 3.1. Volumes - -The docker image is designed to run by mounting the fail2ban run folder. -The run folder should be mounted in the container at: `/var/run/fail2ban`. - -The folder can be mounted with read-only (`ro`) permissions. - -**NOTE:** While it is possible to mount the `fail2ban.sock` file directly, it is recommended to mount the parent folder instead. -The `.sock` file is deleted by fail2ban on shutdown and re-created on startup and this causes problems for the docker mount. -See [this reply](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/issues/11#note_665003499) for more details. - -### 3.2. Docker run - -Use the following command to run the exporter as a docker container. - -``` -docker run -d \ - --name "fail2ban-exporter" \ - -v /var/run/fail2ban:/var/run/fail2ban:ro \ - -p "9191:9191" \ - registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest -``` - -### 3.3. Docker compose - - - -## 4. Metrics - -Access exported metrics at the `/metrics` path on the configured port. - -**Note on Fail2Ban Jails** - -fail2ban can be configured to process different log files and use different rules for each one. -These separate configurations are referred to as *jails*. - -For example, fail2ban can be configured to watch the system logs for failed SSH connections and Nextcloud logs for failed logins. -In this configuration, there will be two jails - one for IPs banned from the SSH logs, and one for IPs banned from the Nextcloud logs. - -This tool exports several metrics *per jail*, meaning that it is possible to track how many IPs are being banned in each jail as well as the overall total. -This can be useful to track what services are seeing more failed logins. - -### 4.1. Fail2Ban Metrics - -These are the metrics exported by reading data from the fail2ban server socket. -All metrics are prefixed with `f2b_`. - -Exposed metrics: -* `up` - Returns 1 if the fail2ban server is up and connection succeeds -* `errors` - Number of errors since startup - * `socket_conn` - Errors connecting to the fail2ban socket (e.g. connection refused) - * `socket_req` - Errors sending requests to the fail2ban server (e.g. invalid responses) -* `jail_count` - Number of jails configured in fail2ban -* `jail_banned_current` (per jail) - Number of IPs currently banned -* `jail_banned_total` (per jail) - Total number of banned IPs since fail2ban startup (includes expired bans) -* `jail_failed_current` (per jail) - Number of current failures -* `jail_failed_total` (per jail) - Total number of failures since fail2ban startup -* `jail_config_ban_time` (per jail) - How long an IP is banned for in this jail (in seconds) -* `jail_config_find_time` (per jail) - How far back the filter will look for failures in this jail (in seconds) -* `jail_config_max_retry` (per jail) - The max number of failures allowed before banning an IP in this jail -* `version` - Version string of the exporter and fail2ban - -**Sample** - -``` -``` - -The metrics above correspond to the matching fields in the `fail2ban-client status ` command: -``` -Status for the jail: sshd|- Filter -| |- Currently failed: 6 -| |- Total failed: 125 -| `- File list: /var/log/auth.log -`- Actions - |- Currently banned: 15 - |- Total banned: 31 - `- Banned IP list: ... -``` - -### 4.2. Textfile Metrics +## 5. Textfile metrics For more flexibility the exporter also allows exporting metrics collected from a text file.