volker.raschek/prometheus-fail2ban-exporter
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

first pass at updating readme

Browse Source
This commit is contained in:
Hector 2021-08-31 06:03:29 +00:00
parent 920cf08619
commit bee43e234f
1 changed files with 32 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
README.md
View File

@ -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