start rewrite of readme file & move grafana.json
This commit is contained in:
Hector
parent
0eb4880286
commit
2bffd3b9d4
153
README.md
153
README.md
@ -1,12 +1,96 @@
|
|||||||
# Fail2Ban Prometheus Exporter
|
# Fail2Ban Prometheus Exporter
|
||||||
|
|
||||||
Go tool to collect and export metrics on Fail2Ban
|
Collect metrics from a running fail2ban instance.
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
1. Introduction
|
1. Quick Start
|
||||||
2. Running the Exporter
|
2. Metrics
|
||||||
3. Running in Docker
|
|
||||||
4. 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
|
## 1. Introduction
|
||||||
This exporter collects metrics from a running fail2ban instance.
|
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`
|
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
|
## 2. Running the Exporter
|
||||||
|
|
||||||
@ -37,7 +116,7 @@ See the [releases page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo
|
|||||||
|
|
||||||
**CLI Usage**
|
**CLI Usage**
|
||||||
```
|
```
|
||||||
$ fail2ban-prometheus-exporter -h
|
$ fail2ban_exporter -h
|
||||||
usage: fail2ban-prometheus-exporter [<flags>]
|
usage: fail2ban-prometheus-exporter [<flags>]
|
||||||
|
|
||||||
Flags:
|
Flags:
|
||||||
@ -119,18 +198,7 @@ docker run -d \
|
|||||||
|
|
||||||
### 3.3. Docker compose
|
### 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
|
## 4. Metrics
|
||||||
|
|
||||||
@ -170,47 +238,6 @@ Exposed metrics:
|
|||||||
**Sample**
|
**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 <jail>` command:
|
The metrics above correspond to the matching fields in the `fail2ban-client status <jail>` command:
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user