From 3953337ea0ffe3e90112ff9da64978720ce0c784 Mon Sep 17 00:00:00 2001
From: Hector <dev@hsmith.org>
Date: Fri, 15 Oct 2021 18:05:50 +0100
Subject: [PATCH] remove all references to the database metrics from readme
---
README.md | 77 +++++++------------------------------------------------
1 file changed, 9 insertions(+), 68 deletions(-)
diff --git a/README.md b/README.md
index ac10265..7cd99bc 100644
--- a/README.md
+++ b/README.md
@@ -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)
-### 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 the same way `fail2ban-client` does and ensures the metrics it collects align with the values reported by `fail2ban-client status <jail>`.
+The exporter communicates with the fail2ban server over its socket.
+This allows the data collected by the exporter to always align with the output of the `fail2ban-client`.
-The default path to 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`
+The default location of the socket is: `/var/run/fail2ban/fail2ban.sock`
## 2. Running the Exporter
@@ -44,8 +33,6 @@ See the [releases page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo
```
$ fail2ban-prometheus-exporter -h
- -db string
- path to the fail2ban sqlite database (deprecated)
-port int
port to use for the metrics server (default 9191)
-socket string
@@ -64,7 +51,7 @@ $ fail2ban-prometheus-exporter -h
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
@@ -75,7 +62,7 @@ Run `go mod download` to download all necessary dependencies before running the
## 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:
```
@@ -87,11 +74,10 @@ See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo
### 3.1. Volumes
-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 run folder should be mounted at: `/var/run/fail2ban`
+The docker image is designed to run by mounting the fail2ban run folder.
+The run folder should be mounted in the container 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.
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 \
--name "fail2ban-exporter" \
- -v /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro \
-v /var/run/fail2ban:/var/run/fail2ban:ro \
-p "9191:9191" \
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
@@ -120,7 +105,6 @@ services:
exporter:
image: registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
volumes:
- - /var/lib/fail2ban/fail2ban.sqlite3:/app/fail2ban.sqlite3:ro
- /var/run/fail2ban/:/var/run/fail2ban:ro
ports:
- "9191:9191"
@@ -221,50 +205,7 @@ Status for the jail: sshd|- Filter
`- Banned IP list: ...
```
-### 4.2. Database Metrics (deprecated)
-
-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
+### 4.2. Textfile Metrics
For more flexibility the exporter also allows exporting metrics collected from a text file.