first pass at updating readme
This commit is contained in:
parent
920cf08619
commit
bee43e234f
47
README.md
47
README.md
@ -12,25 +12,26 @@ Go tool to collect and export metrics on Fail2Ban
|
|||||||
4. Metrics
|
4. Metrics
|
||||||
|
|
||||||
## 1. How to use
|
## 1. How to use
|
||||||
|
The exporter can collect metrics from 2 locations: the fail2ban server socket, and the fail2ban server database.
|
||||||
|
|
||||||
Run the exporter by providing it with a fail2ban database to read data from.
|
|
||||||
Read access to the database is required.
|
|
||||||
Once the exporter is running, metrics are available at `localhost:9191/metrics`.
|
Once the exporter is running, metrics are available at `localhost:9191/metrics`.
|
||||||
|
|
||||||
The default port is `9191`, but this can be modified with the `-port` flag.
|
The default port is `9191`, but this can be modified with the `-port` flag.
|
||||||
|
|
||||||
**Note:** By default fail2ban stores the database file at: `/var/lib/fail2ban/fail2ban.sqlite3`
|
### 1.1. Socket
|
||||||
|
The recommended way to run the exporter is to point it at the fail2ban server socket.
|
||||||
|
This allows the exporter to communicate with the server in the same way `fail2ban-client` does and ensures the metrics it collects are exactly the same as the values reported by `fail2ban-client status <jail>`.
|
||||||
|
|
||||||
**Fail2Ban Jails**
|
The default path to the socket is: `/var/run/fail2ban/fail2ban.sock`
|
||||||
|
|
||||||
fail2ban can be configured to process different log files and use different rules for each one.
|
### 1.2. Deprecated: Database
|
||||||
These separate configurations are referred to as *jails*.
|
Reading metrics from the database has been deprecated in favour of using the socket.
|
||||||
|
The reason being that database metrics do not always align with the output of `fail2ban-client status <jail>` and cause confusion.
|
||||||
|
See [#11]() for more details.
|
||||||
|
|
||||||
For example, fail2ban can be configured to watch the system logs for failed SSH connections and Nextcloud logs for failed logins.
|
*To run the exporter in this mode:*
|
||||||
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.
|
Run the exporter with the path to the fail2ban database.
|
||||||
This can be useful to track what services are seeing more failed logins.
|
The default path to the database is: `/var/lib/fail2ban/fail2ban.sqlite3`
|
||||||
|
|
||||||
## 2. Docker
|
## 2. Docker
|
||||||
|
|
||||||
@ -46,10 +47,11 @@ See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo
|
|||||||
|
|
||||||
### 2.1. Volumes
|
### 2.1. Volumes
|
||||||
|
|
||||||
The docker image is designed to run by mounting the fail2ban sqlite3 database.
|
The docker image is designed to run by mounting either the fail2ban sqlite3 database of the fail2ban run folder.
|
||||||
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 database can be mounted with read-only permissions.
|
Both paths can be mounted with readong (`ro`) permissions.
|
||||||
|
|
||||||
### 2.2. Docker run
|
### 2.2. Docker run
|
||||||
|
|
||||||
@ -59,6 +61,7 @@ Use the following command to run the forwarder as a docker container.
|
|||||||
docker run -d \
|
docker run -d \
|
||||||
--name "fail2ban-exporter" \
|
--name "fail2ban-exporter" \
|
||||||
-v /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro \
|
-v /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro \
|
||||||
|
-v /var/run/fail2ban:/var/run/fail2ban:ro \
|
||||||
-p "9191:9191"
|
-p "9191:9191"
|
||||||
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
||||||
```
|
```
|
||||||
@ -74,6 +77,7 @@ services:
|
|||||||
image: registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
image: registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
||||||
volumes:
|
volumes:
|
||||||
- /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro
|
- /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro
|
||||||
|
- /var/run/fail2ban/:/var/run/fail2ban:ro
|
||||||
ports:
|
ports:
|
||||||
- "9191:9191"
|
- "9191:9191"
|
||||||
```
|
```
|
||||||
@ -95,7 +99,20 @@ $ fail2ban-prometheus-exporter -h
|
|||||||
|
|
||||||
Access exported metrics at `/metrics` (on the provided port).
|
Access exported metrics at `/metrics` (on the provided port).
|
||||||
|
|
||||||
**Note:** All metric names include the `fail2ban_` prefix to make sure they are unique and easier to find.
|
**Note: 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. Socket Metrics
|
||||||
|
|
||||||
|
### 4.2. Database Metrics
|
||||||
|
|
||||||
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