From 9dee6d2ae8fd8c6d98460a8c67d2a94170966183 Mon Sep 17 00:00:00 2001
From: Hector <dev@hsmith.org>
Date: Tue, 31 Aug 2021 10:04:52 +0000
Subject: [PATCH] second pass at updating readme

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 60398e7..83d4521 100644
--- a/README.md
+++ b/README.md
@@ -5,9 +5,6 @@ Go tool to collect and export metrics on Fail2Ban
 ## Table of Contents
 1. How to use
 2. Docker
-    1. Volumes
-    2. Docker run
-    3. Docker compose
 3. CLI usage
 4. Metrics
 
@@ -51,7 +48,10 @@ The docker image is designed to run by mounting either the fail2ban sqlite3 data
 - The database should be mounted at: `/app/fail2ban.sqlite3`
 - The run folder should be mounted at: `/var/run/fail2ban`
 
-Both paths can be mounted with readong (`ro`) permissions.
+Both paths can be mounted with readonly (`ro`) permissions.
+
+**NOTE:** While it is possible to mount the `fail2ban.sock` file directly, I recommend mounting the parent folder instead.
+The `.sock` file is deleted by fail2ban on shutdown and then re-created on startup and this causes problems for the docker mount.
 
 ### 2.2. Docker run
 
@@ -88,9 +88,11 @@ services:
 $ fail2ban-prometheus-exporter -h
 
   -db string
-        path to the fail2ban sqlite database
+        path to the fail2ban sqlite database (deprecated)
   -port int
         port to use for the metrics server (default 9191)
+  -socket string
+        path to the fail2ban server socket
   -version
         show version info and exit
 ```
@@ -99,7 +101,7 @@ $ fail2ban-prometheus-exporter -h
 
 Access exported metrics at `/metrics` (on the provided port).
 
-**Note: Fail2Ban Jails**
+**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*.
@@ -112,7 +114,63 @@ This can be useful to track what services are seeing more failed logins.
 
 ### 4.1. Socket Metrics
 
-### 4.2. Database Metrics
+Exposed metrics:
+* `up` - Returns 1 if the fail2ban server is up and connection succeeds
+* `errors` - Number of errors since startup
+    * `db` - Errors connecting to the database
+    * `socket_conn` - Errors connecting to the fail2ban socket (e.g. connection refused)
+    * `socket_req` - Errors sending requests to the fail2ban server (e.g. invalid responses)
+* `jail_count` - Number of jails configured in fail2ban
+* `jail_banned_current` (per jail) - Number of IPs currently banned
+* `jail_banned_total` (per jail) - Total number of banned IPs since fail2ban startup (includes expired bans)
+* `jail_failed_current` (per jail) - Number of current failures
+* `jail_failed_total` (per jail) - Total number of failures since fail2ban startup
+
+**Sample**
+
+```
+# HELP f2b_errors Number of errors found since startup
+# TYPE f2b_errors counter
+f2b_errors{type="db"} 0
+f2b_errors{type="socket_conn"} 0
+f2b_errors{type="socket_req"} 0
+# HELP f2b_jail_banned_current Number of IPs currently banned in this jail
+# TYPE f2b_jail_banned_current gauge
+f2b_jail_banned_current{jail="recidive"} 5
+f2b_jail_banned_current{jail="sshd"} 15
+# HELP f2b_jail_banned_total Total number of IPs banned by this jail (includes expired bans)
+# TYPE f2b_jail_banned_total gauge
+f2b_jail_banned_total{jail="recidive"} 6
+f2b_jail_banned_total{jail="sshd"} 31
+# HELP f2b_jail_count Number of defined jails
+# TYPE f2b_jail_count gauge
+f2b_jail_count 2
+# HELP f2b_jail_failed_current Number of current failures on this jail's filter
+# TYPE f2b_jail_failed_current gauge
+f2b_jail_failed_current{jail="recidive"} 5
+f2b_jail_failed_current{jail="sshd"} 6
+# HELP f2b_jail_failed_total Number of total failures on this jail's filter
+# TYPE f2b_jail_failed_total gauge
+f2b_jail_failed_total{jail="recidive"} 7
+f2b_jail_failed_total{jail="sshd"} 125
+# HELP f2b_up Check if the fail2ban server is up
+# TYPE f2b_up gauge
+f2b_up 1
+```
+
+The metrics above correspond to the matching fields in the `fail2ban-client status <jail>` command:
+```
+Status for the jail: sshd|- Filter
+|  |- Currently failed: 6
+|  |- Total failed:     125
+|  `- File list:        /var/log/auth.log
+`- Actions
+   |- Currently banned: 15
+   |- Total banned:     31
+   `- Banned IP list:   ...
+```
+
+### 4.2. Database Metrics (deprecated)
 
 Exposed metrics:
 * `up` - Returns 1 if the service is up