From bee43e234fb7e75aec0b8444decff0cd77251f96 Mon Sep 17 00:00:00 2001 From: Hector Date: Tue, 31 Aug 2021 06:03:29 +0000 Subject: [PATCH] first pass at updating readme --- README.md | 47 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 4873284..60398e7 100644 --- a/README.md +++ b/README.md @@ -12,25 +12,26 @@ Go tool to collect and export metrics on Fail2Ban 4. Metrics ## 1. How to use +The exporter can collect metrics from 2 locations: the fail2ban server socket, and the fail2ban server database. -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` +### 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 in the same way `fail2ban-client` does and ensures the metrics it collects are exactly the same as the values reported by `fail2ban-client status `. -**Fail2Ban Jails** +The default path to the socket is: `/var/run/fail2ban/fail2ban.sock` -fail2ban can be configured to process different log files and use different rules for each one. -These separate configurations are referred to as *jails*. +### 1.2. Deprecated: Database +Reading metrics from the database has 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 ` and cause confusion. +See [#11]() for more details. -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. +*To run the exporter in this mode:* -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. +Run the exporter with the path to the fail2ban database. +The default path to the database is: `/var/lib/fail2ban/fail2ban.sqlite3` ## 2. Docker @@ -46,10 +47,11 @@ See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-expo ### 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 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 database can be mounted with read-only permissions. +Both paths can be mounted with readong (`ro`) permissions. ### 2.2. Docker run @@ -59,6 +61,7 @@ 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 \ + -v /var/run/fail2ban:/var/run/fail2ban:ro \ -p "9191:9191" registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest ``` @@ -74,6 +77,7 @@ services: 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" ``` @@ -95,7 +99,20 @@ $ fail2ban-prometheus-exporter -h 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. +**Note: 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. + +### 4.1. Socket Metrics + +### 4.2. Database Metrics Exposed metrics: * `up` - Returns 1 if the service is up