second pass at updating readme

This commit is contained in:
Hector 2021-08-31 10:04:52 +00:00
parent bee43e234f
commit 9dee6d2ae8

View File

@ -5,9 +5,6 @@ Go tool to collect and export metrics on Fail2Ban
## Table of Contents ## Table of Contents
1. How to use 1. How to use
2. Docker 2. Docker
1. Volumes
2. Docker run
3. Docker compose
3. CLI usage 3. CLI usage
4. Metrics 4. Metrics
@ -51,7 +48,10 @@ The docker image is designed to run by mounting either the fail2ban sqlite3 data
- The database should be mounted at: `/app/fail2ban.sqlite3` - The database should be mounted at: `/app/fail2ban.sqlite3`
- The run folder should be mounted at: `/var/run/fail2ban` - The run folder should be mounted at: `/var/run/fail2ban`
Both paths can be mounted with readong (`ro`) permissions. Both paths can be mounted with readonly (`ro`) permissions.
**NOTE:** While it is possible to mount the `fail2ban.sock` file directly, I recommend mounting the parent folder instead.
The `.sock` file is deleted by fail2ban on shutdown and then re-created on startup and this causes problems for the docker mount.
### 2.2. Docker run ### 2.2. Docker run
@ -88,9 +88,11 @@ services:
$ fail2ban-prometheus-exporter -h $ fail2ban-prometheus-exporter -h
-db string -db string
path to the fail2ban sqlite database path to the fail2ban sqlite database (deprecated)
-port int -port int
port to use for the metrics server (default 9191) port to use for the metrics server (default 9191)
-socket string
path to the fail2ban server socket
-version -version
show version info and exit show version info and exit
``` ```
@ -99,7 +101,7 @@ $ fail2ban-prometheus-exporter -h
Access exported metrics at `/metrics` (on the provided port). Access exported metrics at `/metrics` (on the provided port).
**Note: Fail2Ban Jails** **Fail2Ban Jails**
fail2ban can be configured to process different log files and use different rules for each one. fail2ban can be configured to process different log files and use different rules for each one.
These separate configurations are referred to as *jails*. These separate configurations are referred to as *jails*.
@ -112,7 +114,63 @@ This can be useful to track what services are seeing more failed logins.
### 4.1. Socket Metrics ### 4.1. Socket Metrics
### 4.2. Database Metrics Exposed metrics:
* `up` - Returns 1 if the fail2ban server is up and connection succeeds
* `errors` - Number of errors since startup
* `db` - Errors connecting to the database
* `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
**Sample**
```
# HELP f2b_errors Number of errors found since startup
# TYPE f2b_errors counter
f2b_errors{type="db"} 0
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_up Check if the fail2ban server is up
# TYPE f2b_up gauge
f2b_up 1
```
The metrics above correspond to the matching fields in the `fail2ban-client status <jail>` 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. Database Metrics (deprecated)
Exposed metrics: Exposed metrics:
* `up` - Returns 1 if the service is up * `up` - Returns 1 if the service is up