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

remove all references to the database metrics from readme

Browse Source
This commit is contained in:
Hector 2021-10-15 18:05:50 +01:00
parent 39ec8633d5
commit 3953337ea0
1 changed files with 9 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@ -15,21 +15,10 @@ Once the exporter is running, metrics are available at `localhost:9191/metrics`.
(The default port is `9191` but can be modified with the `-port` flag) (The default port is `9191` but can be modified with the `-port` flag)
### 1.1. Socket The exporter communicates with the fail2ban server over its socket.
The recommended way to run the exporter is to point it at the fail2ban server socket. This allows the data collected by the exporter to always align with the output of the `fail2ban-client`.
This allows the exporter to communicate with the server the same way `fail2ban-client` does and ensures the metrics it collects align with the values reported by `fail2ban-client status <jail>`.
The default path to the socket is: `/var/run/fail2ban/fail2ban.sock` The default location of the socket is: `/var/run/fail2ban/fail2ban.sock`
### 1.2. Deprecated: Database
The original way to collect metrics is to read them from the fail2ban database.
This has now 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](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/issues/11) for more details.
If necessary, these metrics can still be exported by providing the database path to the exporter.
The default path to the fail2ban database is: `/var/lib/fail2ban/fail2ban.sqlite3`
## 2. Running the Exporter ## 2. Running the Exporter
@ -44,8 +33,6 @@ See the [releases page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo
``` ```
$ fail2ban-prometheus-exporter -h $ fail2ban-prometheus-exporter -h
-db string
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 -socket string
@ -64,7 +51,7 @@ $ fail2ban-prometheus-exporter -h
fail2ban-prometheus-exporter -socket /var/run/fail2ban/fail2ban.sock -port 9191 fail2ban-prometheus-exporter -socket /var/run/fail2ban/fail2ban.sock -port 9191
``` ```
Note that the exporter will need read access to the fail2ban socket or database. Note that the exporter will need read access to the fail2ban socket.
### 2.1. Compile from Source ### 2.1. Compile from Source
@ -75,7 +62,7 @@ Run `go mod download` to download all necessary dependencies before running the
## 3. Running in Docker ## 3. Running in Docker
If use of docker is desired, an official docker image is available on the Gitlab container registry. An official docker image is available on the Gitlab container registry.
Use it by pulling the following image: Use it by pulling the following image:
``` ```
@ -87,11 +74,10 @@ See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo
### 3.1. Volumes ### 3.1. Volumes
The docker image is designed to run by mounting either the fail2ban sqlite3 database of the fail2ban run folder. The docker image is designed to run by mounting the fail2ban run folder.
- The database should be mounted at: `/app/fail2ban.sqlite3` The run folder should be mounted in the container at: `/var/run/fail2ban`.
- The run folder should be mounted at: `/var/run/fail2ban`
Both paths can be mounted with readonly (`ro`) permissions. The folder can be mounted with read-only (`ro`) permissions.
**NOTE:** While it is possible to mount the `fail2ban.sock` file directly, it is recommended to mount the parent folder instead. **NOTE:** While it is possible to mount the `fail2ban.sock` file directly, it is recommended to mount the parent folder instead.
The `.sock` file is deleted by fail2ban on shutdown and re-created on startup and this causes problems for the docker mount. The `.sock` file is deleted by fail2ban on shutdown and re-created on startup and this causes problems for the docker mount.
@ -104,7 +90,6 @@ Use the following command to run the exporter 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/run/fail2ban:/var/run/fail2ban: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
@ -120,7 +105,6 @@ services:
exporter: exporter:
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/run/fail2ban/:/var/run/fail2ban:ro - /var/run/fail2ban/:/var/run/fail2ban:ro
ports: ports:
- "9191:9191" - "9191:9191"
@ -221,50 +205,7 @@ Status for the jail: sshd|- Filter
`- Banned IP list: ... `- Banned IP list: ...
``` ```
### 4.2. Database Metrics (deprecated) ### 4.2. Textfile Metrics
These are the original metrics exported by the initial release of the exporter.
They are all based on the data stored in the fail2ban sqlite3 database.
*These metrics are deprecated and will be removed in a future release.*
All metrics are prefixed with `fail2ban_`.
Exposed metrics:
* `up` - Returns 1 if the service is up
* `errors` - Returns the number of errors found since startup
* `enabled_jails` - Returns 1 for each jail that is enabled, 0 if disabled.
* `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 (Deprecated) Number of bad IPs stored in the database (per jail).
# TYPE fail2ban_bad_ips gauge
fail2ban_bad_ips{jail="recidive"} 0
fail2ban_bad_ips{jail="sshd"} 0
# HELP fail2ban_banned_ips (Deprecated) Number of banned IPs stored in the database (per jail).
# TYPE fail2ban_banned_ips gauge
fail2ban_banned_ips{jail="recidive"} 0
fail2ban_banned_ips{jail="sshd"} 0
# HELP fail2ban_enabled_jails (Deprecated) Enabled jails.
# TYPE fail2ban_enabled_jails gauge
fail2ban_enabled_jails{jail="recidive"} 1
fail2ban_enabled_jails{jail="sshd"} 1
# HELP fail2ban_errors (Deprecated) Number of errors found since startup.
# TYPE fail2ban_errors counter
fail2ban_errors{type="db"} 0
# HELP fail2ban_up (Deprecated) Was the last fail2ban query successful.
# TYPE fail2ban_up gauge
fail2ban_up 1
```
### 4.3. Textfile Metrics
For more flexibility the exporter also allows exporting metrics collected from a text file. For more flexibility the exporter also allows exporting metrics collected from a text file.