d6ad09341b
Update the project README file to include information on what the project does and how to run it.
123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# Fail2Ban Prometheus Exporter
|
|
|
|
Go tool to collect and export metrics on Fail2Ban
|
|
|
|
## Table of Contents
|
|
1. How to use
|
|
2. Docker
|
|
1. Environment variables
|
|
2. Docker run
|
|
3. Docker compose
|
|
3. CLI usage
|
|
4. Metrics
|
|
|
|
## 1. How to use
|
|
|
|
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`.
|
|
|
|
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`
|
|
|
|
**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.
|
|
|
|
## 2. Docker
|
|
|
|
An official docker image is available on the Gitlab container registry.
|
|
Use it by pulling the following image:
|
|
|
|
```
|
|
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
|
```
|
|
|
|
Use the `:latest` tag to get the most up to date code (less stable) or use one of the version tagged images to use a specific release.
|
|
See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/container_registry) for all available tags.
|
|
|
|
### 2.1. Volumes
|
|
|
|
The docker image is designed to run by mounting the fail2ban sqlite3 database.
|
|
The database should be mounted at: `/app/fail2ban.sqlite3`
|
|
|
|
The database can be mounted with read-only permissions.
|
|
|
|
### 2.2. Docker run
|
|
|
|
Use the following command to run the forwarder as a docker container.
|
|
|
|
```
|
|
docker run -d \
|
|
--name "fail2ban-exporter" \
|
|
-v /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro \
|
|
-p "9191:9191"
|
|
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
|
```
|
|
|
|
### 2.3. Docker compose
|
|
|
|
The following is a simple docker-compose file to run the exporter.
|
|
|
|
```
|
|
version: "2"
|
|
services:
|
|
exporter:
|
|
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
|
volumes:
|
|
- /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro
|
|
ports:
|
|
- "9191:9191"
|
|
```
|
|
|
|
## 3. CLI usage
|
|
|
|
```
|
|
$ fail2ban-prometheus-exporter -h
|
|
|
|
-db string
|
|
path to the fail2ban sqlite database
|
|
-port int
|
|
port to use for the metrics server (default 9191)
|
|
-version
|
|
show version info and exit
|
|
```
|
|
|
|
## 4. Metrics
|
|
|
|
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.
|
|
|
|
Exposed metrics:
|
|
* `up` - Returns 1 if the service is up
|
|
* `bad_ips` (per jail)
|
|
* A *bad IP* is defined as an IP that has been banned at least once in the past
|
|
* Bad IPs are counted per jail
|
|
* `banned_ips` (per jail)
|
|
* A *banned IP* is defined as an IP that is currently banned on the firewall
|
|
* Banned IPs are counted per jail
|
|
|
|
**Sample**
|
|
|
|
```
|
|
# HELP fail2ban_bad_ips Number of bad IPs stored in the database (per jail).
|
|
# TYPE fail2ban_bad_ips gauge
|
|
fail2ban_bad_ips{jail="jail1"} 6
|
|
fail2ban_bad_ips{jail="jail2"} 8
|
|
# HELP fail2ban_banned_ips Number of banned IPs stored in the database (per jail).
|
|
# TYPE fail2ban_banned_ips gauge
|
|
fail2ban_banned_ips{jail="jail1"} 3
|
|
fail2ban_banned_ips{jail="jail2"} 2
|
|
# HELP fail2ban_up Was the last fail2ban query successful.
|
|
# TYPE fail2ban_up gauge
|
|
fail2ban_up 1
|
|
```
|