Merge branch 'docs/add-usage-instructions-to-readme-file' into 'main'
Docs/add usage instructions to readme file See merge request hectorjsmith/fail2ban-prometheus-exporter!12
This commit is contained in:
commit
26da913294
120
README.md
120
README.md
@ -1,3 +1,123 @@
|
||||
# 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
|
||||
```
|
||||
|
Loading…
Reference in New Issue
Block a user