finish rewriting readme file
This commit is contained in:
Hector
parent
2bffd3b9d4
commit
7899e4db25
181
README.md
181
README.md
@ -5,10 +5,9 @@ Collect metrics from a running fail2ban instance.
|
||||
## Table of Contents
|
||||
1. Quick Start
|
||||
2. Metrics
|
||||
|
||||
3. Running the Exporter
|
||||
4. Running in Docker
|
||||
5. Metrics
|
||||
3. Configuration
|
||||
4. Building
|
||||
5. Textfile metrics
|
||||
|
||||
## 1. Quick Start
|
||||
|
||||
@ -52,6 +51,10 @@ services:
|
||||
- "9191:9191"
|
||||
```
|
||||
|
||||
**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.
|
||||
See [this reply](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/issues/11#note_665003499) for more details.
|
||||
|
||||
## 2. Metrics
|
||||
|
||||
The exporter exposes the following metrics:
|
||||
@ -74,6 +77,18 @@ The exporter exposes the following metrics:
|
||||
| `jail_config_max_retry` | The max number of failures allowed before banning an IP in this jail | `f2b_config_jail_max_retries{jail="sshd"} 5` |
|
||||
| `version` | Version string of the exporter and fail2ban | `f2b_version{exporter="0.5.0",fail2ban="0.11.1"} 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: ...
|
||||
```
|
||||
|
||||
### 2.1. Grafana
|
||||
|
||||
The metrics exported by this tool are compatible with Prometheus and Grafana.
|
||||
@ -82,42 +97,14 @@ Just import the contents of this file into a new Grafana dashboard to get starte
|
||||
|
||||
*(Sample dashboard is compatible with Grafana `8.3.3` and above)*
|
||||
|
||||
## 3. Configuration
|
||||
|
||||
The exporter is configured with CLI flags and environment variables.
|
||||
There are no configuration files.
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 1. Introduction
|
||||
This exporter collects metrics from a running fail2ban instance.
|
||||
|
||||
Once the exporter is running, metrics are available at `localhost:9191/metrics`.
|
||||
|
||||
(The default port is `9191` but can be modified with the `--web.listen-address` flag)
|
||||
|
||||
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 location of the socket is: `/var/run/fail2ban/fail2ban.sock`
|
||||
|
||||
|
||||
## 2. Running the Exporter
|
||||
|
||||
The exporter is compiled and released as a single binary.
|
||||
This makes it very easy to run in any environment.
|
||||
No additional runtime dependencies are required.
|
||||
|
||||
Compiled binaries for various platforms are provided in each release.
|
||||
See the [releases page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/releases) for more information.
|
||||
|
||||
**CLI Usage**
|
||||
**CLI flags**
|
||||
```
|
||||
$ fail2ban_exporter -h
|
||||
usage: fail2ban-prometheus-exporter [<flags>]
|
||||
usage: fail2ban_exporter [<flags>]
|
||||
|
||||
Flags:
|
||||
-h, --help Show context-sensitive help (also try --help-long and --help-man).
|
||||
@ -136,123 +123,25 @@ Flags:
|
||||
|
||||
**Environment variables**
|
||||
|
||||
The tool can also be configured using environment variables. Each CLI parameter has a corresponding environment variable.
|
||||
Each environment variable corresponds to a CLI flag.
|
||||
If both are specified, the CLI flag takes precedence.
|
||||
|
||||
```
|
||||
F2B_COLLECTOR_SOCKET
|
||||
F2B_COLLECTOR_TEXT_PATH
|
||||
F2B_WEB_LISTEN_ADDRESS
|
||||
F2B_WEB_BASICAUTH_USER
|
||||
F2B_WEB_BASICAUTH_PASS
|
||||
```
|
||||
| Environment variable | CLI flag |
|
||||
|---------------------------|----------------------------------|
|
||||
| `F2B_COLLECTOR_SOCKET` | `--collector.f2b.socket` |
|
||||
| `F2B_COLLECTOR_TEXT_PATH` | `--collector.textfile.directory` |
|
||||
| `F2B_WEB_LISTEN_ADDRESS` | `--web.listen-address` |
|
||||
| `F2B_WEB_BASICAUTH_USER` | `--web.basic-auth.username` |
|
||||
| `F2B_WEB_BASICAUTH_PASS` | `--web.basic-auth.password` |
|
||||
|
||||
**Example**
|
||||
|
||||
```
|
||||
fail2ban-prometheus-exporter --collector.f2b.socket=/var/run/fail2ban/fail2ban.sock --web.listen-address=":9191"
|
||||
```
|
||||
|
||||
Note that the exporter will need read access to the fail2ban socket.
|
||||
|
||||
### 2.1. Compile from Source
|
||||
## 4. Building
|
||||
|
||||
The code can be compiled from source by running `go build` inside the `src/` folder.
|
||||
Go version `1.15` or greater is required.
|
||||
|
||||
Run `go mod download` to download all necessary dependencies before running the build.
|
||||
|
||||
## 3. Running in 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 latest stable release. Or use the `:nightly` tag for the latest (unstable) version.
|
||||
See the [registry page](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/container_registry) for all available tags.
|
||||
|
||||
### 3.1. Volumes
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
See [this reply](https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter/-/issues/11#note_665003499) for more details.
|
||||
|
||||
### 3.2. Docker run
|
||||
|
||||
Use the following command to run the exporter as a docker container.
|
||||
|
||||
```
|
||||
docker run -d \
|
||||
--name "fail2ban-exporter" \
|
||||
-v /var/run/fail2ban:/var/run/fail2ban:ro \
|
||||
-p "9191:9191" \
|
||||
registry.gitlab.com/hectorjsmith/fail2ban-prometheus-exporter:latest
|
||||
```
|
||||
|
||||
### 3.3. Docker compose
|
||||
|
||||
|
||||
|
||||
## 4. Metrics
|
||||
|
||||
Access exported metrics at the `/metrics` path on the configured port.
|
||||
|
||||
**Note on 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. Fail2Ban Metrics
|
||||
|
||||
These are the metrics exported by reading data from the fail2ban server socket.
|
||||
All metrics are prefixed with `f2b_`.
|
||||
|
||||
Exposed metrics:
|
||||
* `up` - Returns 1 if the fail2ban server is up and connection succeeds
|
||||
* `errors` - Number of errors since startup
|
||||
* `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
|
||||
* `jail_config_ban_time` (per jail) - How long an IP is banned for in this jail (in seconds)
|
||||
* `jail_config_find_time` (per jail) - How far back the filter will look for failures in this jail (in seconds)
|
||||
* `jail_config_max_retry` (per jail) - The max number of failures allowed before banning an IP in this jail
|
||||
* `version` - Version string of the exporter and fail2ban
|
||||
|
||||
**Sample**
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
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. Textfile Metrics
|
||||
## 5. Textfile metrics
|
||||
|
||||
For more flexibility the exporter also allows exporting metrics collected from a text file.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user