second pass at updating readme
This commit is contained in:
parent
bee43e234f
commit
9dee6d2ae8
72
README.md
72
README.md
@ -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
|
||||||
|
Loading…
x
Reference in New Issue
Block a user