diff --git a/README.md b/README.md index 2795f9b..88ab315 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,96 @@ # Fail2Ban Prometheus Exporter -Go tool to collect and export metrics on Fail2Ban +Collect metrics from a running fail2ban instance. ## Table of Contents -1. Introduction -2. Running the Exporter -3. Running in Docker -4. Metrics +1. Quick Start +2. Metrics + +3. Running the Exporter +4. Running in Docker +5. Metrics + +## 1. Quick Start + +The exporter can be run as a standalone binary or a docker container. + +### 1.1. Standalone + +The following command will start collecting metrics from the `/var/run/fail2ban/fail2ban.sock` file and expose them on port `9191`. + +``` +$ fail2ban_exporter --collector.f2b.socket=/var/run/fail2ban/fail2ban.sock --web.listen-address=":9191" + +2022/02/20 09:54:06 fail2ban exporter version 0.5.0 +2022/02/20 09:54:06 starting server at :9191 +2022/02/20 09:54:06 reading metrics from fail2ban socket: /var/run/fail2ban/fail2ban.sock +2022/02/20 09:54:06 metrics available at '/metrics' +2022/02/20 09:54:06 ready +``` + +### 1.2. Docker + +**Docker run** +``` +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 +``` + +**Docker compose** + +``` +version: "2" +services: + exporter: + image: registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest + volumes: + - /var/run/fail2ban/:/var/run/fail2ban:ro + ports: + - "9191:9191" +``` + +## 2. Metrics + +The exporter exposes the following metrics: + +*All metric names are prefixed with `f2b_`* + +| Metric | Description | Example | +|------------------------------|------------------------------------------------------------------------------------|-----------------------------------------------------| +| `up` | Returns 1 if the exporter is up and running | `f2b_up 1` | +| `errors` | Count the number of errors since startup by type | | +| `errors{type="socket_conn"}` | Errors connecting to the fail2ban socket (e.g. connection refused) | `f2b_errors{type="socket_conn"} 0` | +| `errors{type="socket_req"}` | Errors sending requests to the fail2ban server (e.g. invalid responses) | `f2b_errors{type="socket_req"} 0` | +| `jail_count` | Number of jails configured in fail2ban | `f2b_jail_count 2` | +| `jail_banned_current` | Number of IPs currently banned per jail | `f2b_jail_banned_current{jail="sshd"} 15` | +| `jail_banned_total` | Total number of banned IPs since fail2ban startup per jail (includes expired bans) | `f2b_jail_banned_total{jail="sshd"} 31` | +| `jail_failed_current` | Number of current failures per jail | `f2b_jail_failed_current{jail="sshd"} 6` | +| `jail_failed_total` | Total number of failures since fail2ban startup per jail | `f2b_jail_failed_total{jail="sshd"} 125` | +| `jail_config_ban_time` | How long an IP is banned for in this jail (in seconds) | `f2b_config_jail_ban_time{jail="sshd"} 600` | +| `jail_config_find_time` | How far back the filter will look for failures in this jail (in seconds) | `f2b_config_jail_find_time{jail="sshd"} 600` | +| `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` | + +### 2.1. Grafana + +The metrics exported by this tool are compatible with Prometheus and Grafana. +A sample grafana dashboard can be found in the [grafana.json](/examples/grafana/dashboard.json) file. +Just import the contents of this file into a new Grafana dashboard to get started. + +*(Sample dashboard is compatible with Grafana `8.3.3` and above)* + + + + +--- + + + + + ## 1. Introduction This exporter collects metrics from a running fail2ban instance. @@ -20,11 +104,6 @@ This allows the data collected by the exporter to always align with the output o The default location of the socket is: `/var/run/fail2ban/fail2ban.sock` -## 1.1. Grafana - -The metrics exported by this tool are compatible with Prometheus and Grafana. A sample grafana dashboard can be found in the `grafana.json` file. Just import the contents of this file into a new Grafana dashboard to get started. - -*(Sample dashboard is compatible with Grafana `8.3.3` and above)* ## 2. Running the Exporter @@ -37,7 +116,7 @@ See the [releases page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo **CLI Usage** ``` -$ fail2ban-prometheus-exporter -h +$ fail2ban_exporter -h usage: fail2ban-prometheus-exporter [] Flags: @@ -119,18 +198,7 @@ docker run -d \ ### 3.3. Docker compose -The following is a simple docker-compose file to run the exporter. -``` -version: "2" -services: - exporter: - image: registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest - volumes: - - /var/run/fail2ban/:/var/run/fail2ban:ro - ports: - - "9191:9191" -``` ## 4. Metrics @@ -170,47 +238,6 @@ Exposed metrics: **Sample** ``` -# HELP f2b_errors Number of errors found since startup -# TYPE f2b_errors counter -f2b_errors{type="socket_conn"} 0 -f2b_errors{type="socket_req"} 0 -# HELP f2b_jail_banned_current Number of IPs currently banned in this jail -# TYPE f2b_jail_banned_current gauge -f2b_jail_banned_current{jail="recidive"} 5 -f2b_jail_banned_current{jail="sshd"} 15 -# HELP f2b_jail_banned_total Total number of IPs banned by this jail (includes expired bans) -# TYPE f2b_jail_banned_total gauge -f2b_jail_banned_total{jail="recidive"} 6 -f2b_jail_banned_total{jail="sshd"} 31 -# HELP f2b_jail_count Number of defined jails -# TYPE f2b_jail_count gauge -f2b_jail_count 2 -# HELP f2b_jail_failed_current Number of current failures on this jail's filter -# TYPE f2b_jail_failed_current gauge -f2b_jail_failed_current{jail="recidive"} 5 -f2b_jail_failed_current{jail="sshd"} 6 -# HELP f2b_jail_failed_total Number of total failures on this jail's filter -# TYPE f2b_jail_failed_total gauge -f2b_jail_failed_total{jail="recidive"} 7 -f2b_jail_failed_total{jail="sshd"} 125 -# HELP f2b_config_jail_ban_time How long an IP is banned for in this jail (in seconds) -# TYPE f2b_config_jail_ban_time gauge -f2b_config_jail_ban_time{jail="recidive"} 604800 -f2b_config_jail_ban_time{jail="sshd"} 600 -# HELP f2b_config_jail_find_time How far back will the filter look for failures in this jail (in seconds) -# TYPE f2b_config_jail_find_time gauge -f2b_config_jail_find_time{jail="recidive"} 86400 -f2b_config_jail_find_time{jail="sshd"} 600 -# HELP f2b_config_jail_max_retries The number of failures allowed until the IP is banned by this jail -# TYPE f2b_config_jail_max_retries gauge -f2b_config_jail_max_retries{jail="recidive"} 5 -f2b_config_jail_max_retries{jail="sshd"} 5 -# HELP f2b_up Check if the fail2ban server is up -# TYPE f2b_up gauge -f2b_up 1 -# HELP f2b_version Version of the exporter and fail2ban server -# TYPE f2b_version gauge -f2b_version{exporter="0.3.0",fail2ban="0.11.1"} 1 ``` The metrics above correspond to the matching fields in the `fail2ban-client status ` command: diff --git a/grafana.json b/examples/grafana/dashboard.json similarity index 100% rename from grafana.json rename to examples/grafana/dashboard.json