{"id":41790584,"url":"https://github.com/hctrdev/fail2ban-prometheus-exporter","last_synced_at":"2026-01-25T05:01:16.590Z","repository":{"id":176399873,"uuid":"352404816","full_name":"hctrdev/fail2ban-prometheus-exporter","owner":"hctrdev","description":"[MIRROR] Collect and export metrics on Fail2Ban","archived":false,"fork":false,"pushed_at":"2025-04-04T20:27:26.000Z","size":11120,"stargazers_count":52,"open_issues_count":5,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-04T20:34:38.593Z","etag":null,"topics":["fail2ban","go","golang","grafana","metrics","monitoring","prometheus"],"latest_commit_sha":null,"homepage":"https://gitlab.com/hectorjsmith/fail2ban-prometheus-exporter","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hctrdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-28T18:18:30.000Z","updated_at":"2025-04-04T20:19:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"5447ae0c-792e-466f-9f9f-add888cc429c","html_url":"https://github.com/hctrdev/fail2ban-prometheus-exporter","commit_stats":null,"previous_names":["hectorjsmith/fail2ban-prometheus-exporter","hctrdev/fail2ban-prometheus-exporter"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/hctrdev/fail2ban-prometheus-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hctrdev%2Ffail2ban-prometheus-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hctrdev%2Ffail2ban-prometheus-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hctrdev%2Ffail2ban-prometheus-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hctrdev%2Ffail2ban-prometheus-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hctrdev","download_url":"https://codeload.github.com/hctrdev/fail2ban-prometheus-exporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hctrdev%2Ffail2ban-prometheus-exporter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28744419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T02:46:29.005Z","status":"ssl_error","status_checked_at":"2026-01-25T02:44:29.968Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fail2ban","go","golang","grafana","metrics","monitoring","prometheus"],"created_at":"2026-01-25T05:00:30.734Z","updated_at":"2026-01-25T05:01:16.564Z","avatar_url":"https://github.com/hctrdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fail2Ban Prometheus Exporter\n\n[![Pipeline](https://gitlab.com/hctrdev/fail2ban-prometheus-exporter/badges/main/pipeline.svg)](https://gitlab.com/hctrdev/fail2ban-prometheus-exporter)\n[![Go Report Card](https://goreportcard.com/badge/gitlab.com/hctrdev/fail2ban-prometheus-exporter)](https://goreportcard.com/report/gitlab.com/hctrdev/fail2ban-prometheus-exporter)\n\nCollect metrics from a running fail2ban instance.\n\n## Table of Contents\n1. Quick Start\n2. Metrics\n3. Configuration\n4. Building from source\n5. Textfile metrics\n6. Troubleshooting\n\n## 1. Quick Start\n\nThe exporter can be run as a standalone binary or a docker container.\n\n### 1.1. Standalone\n\nThe following command will start collecting metrics from the `/var/run/fail2ban/fail2ban.sock` file and expose them on port `9191`.\n\n```\n$ fail2ban_exporter --collector.f2b.socket=/var/run/fail2ban/fail2ban.sock --web.listen-address=\":9191\"\n\n2022/02/20 09:54:06 fail2ban exporter version 0.8.1\n2022/02/20 09:54:06 starting server at :9191\n2022/02/20 09:54:06 reading metrics from fail2ban socket: /var/run/fail2ban/fail2ban.sock\n2022/02/20 09:54:06 metrics available at '/metrics'\n2022/02/20 09:54:06 ready\n```\n\nBinary files for each release can be found on the [releases](https://gitlab.com/hctrdev/fail2ban-prometheus-exporter/-/releases) page.\n\nThere is also an [example systemd service file](/_examples/systemd/fail2ban_exporter.service) included in the repository.\nThis is a starting point to run the exporter as a service.\n\n### 1.2. Docker\n\n**Docker run**\n```\ndocker run -d \\\n    --name \"fail2ban-exporter\" \\\n    -v /var/run/fail2ban:/var/run/fail2ban:ro \\\n    -p \"9191:9191\" \\\n    registry.gitlab.com/hctrdev/fail2ban-prometheus-exporter:latest\n```\n\n**Docker compose**\n\n```\nversion: \"2\"\nservices:\n  exporter:\n    image: registry.gitlab.com/hctrdev/fail2ban-prometheus-exporter:latest\n    volumes:\n    - /var/run/fail2ban/:/var/run/fail2ban:ro\n    ports:\n    - \"9191:9191\"\n```\n\nUse the `:latest` tag to get the latest stable release.\nSee the [registry page](https://gitlab.com/hctrdev/fail2ban-prometheus-exporter/container_registry) for all available tags.\n\n**NOTE:** While it is possible to mount the `fail2ban.sock` file directly, it is recommended to mount the parent folder instead.\nThe `.sock` file is deleted by fail2ban on shutdown and re-created on startup and this causes problems for the docker mount.\nSee [this reply](https://gitlab.com/hctrdev/fail2ban-prometheus-exporter/-/issues/11#note_665003499) for more details.\n\n## 2. Metrics\n\nThe exporter exposes the following metrics:\n\n*All metric names are prefixed with `f2b_`*\n\n| Metric                       | Description                                                                        | Example                                             |\n|------------------------------|------------------------------------------------------------------------------------|-----------------------------------------------------|\n| `up`                         | Returns 1 if the exporter is up and running                                        | `f2b_up 1`                                          |\n| `errors`                     | Count the number of errors since startup by type                                   |                                                     |\n| `errors{type=\"socket_conn\"}` | Errors connecting to the fail2ban socket (e.g. connection refused)                 | `f2b_errors{type=\"socket_conn\"} 0`                  |\n| `errors{type=\"socket_req\"}`  | Errors sending requests to the fail2ban server (e.g. invalid responses)            | `f2b_errors{type=\"socket_req\"} 0`                   |\n| `jail_count`                 | Number of jails configured in fail2ban                                             | `f2b_jail_count 2`                                  |\n| `jail_banned_current`        | Number of IPs currently banned per jail                                            | `f2b_jail_banned_current{jail=\"sshd\"} 15`           |\n| `jail_banned_total`          | Total number of banned IPs since fail2ban startup per jail (includes expired bans) | `f2b_jail_banned_total{jail=\"sshd\"} 31`             |\n| `jail_failed_current`        | Number of current failures per jail                                                | `f2b_jail_failed_current{jail=\"sshd\"} 6`            |\n| `jail_failed_total`          | Total number of failures since fail2ban startup per jail                           | `f2b_jail_failed_total{jail=\"sshd\"} 125`            |\n| `jail_config_ban_time`       | How long an IP is banned for in this jail (in seconds)                             | `f2b_config_jail_ban_time{jail=\"sshd\"} 600`         |\n| `jail_config_find_time`      | How far back the filter will look for failures in this jail (in seconds)           | `f2b_config_jail_find_time{jail=\"sshd\"} 600`        |\n| `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`        |\n| `version`                    | Version string of the exporter and fail2ban                                        | `f2b_version{exporter=\"0.5.0\",fail2ban=\"0.11.1\"} 1` |\n\nThe metrics above correspond to the matching fields in the `fail2ban-client status \u003cjail\u003e` command:\n```\nStatus for the jail: sshd\n|- Filter\n|  |- Currently failed: 6\n|  |- Total failed:     125\n|  `- File list:        /var/log/auth.log\n`- Actions\n   |- Currently banned: 15\n   |- Total banned:     31\n   `- Banned IP list:   ...\n```\n\n### 2.1. Grafana\n\nThe metrics exported by this tool are compatible with Prometheus and Grafana.\nA sample grafana dashboard can be found in the [grafana.json](/_examples/grafana/dashboard.json) file.\nJust import the contents of this file into a new Grafana dashboard to get started.\n\nThe dashboard supports displaying data from multiple exporters. Use the `instance` dashboard variable to select which ones to display.\n\n*(Sample dashboard is compatible with Grafana `9.1.8` and above)*\n\n## 3. Configuration\n\nThe exporter is configured with CLI flags and environment variables.\nThere are no configuration files.\n\n**CLI flags**\n```\n🚀 Collect prometheus metrics from a running Fail2Ban instance\n\nFlags:\n  -h, --help                          Show context-sensitive help.\n  -v, --version                       Show version info and exit\n      --dry-run                       Attempt to connect to the fail2ban socket then exit\n                                      before starting the server\n      --web.listen-address=\":9191\"    Address to use for the metrics server\n                                      ($F2B_WEB_LISTEN_ADDRESS)\n      --collector.f2b.socket=\"/var/run/fail2ban/fail2ban.sock\"\n                                      Path to the fail2ban server socket\n                                      ($F2B_COLLECTOR_SOCKET)\n      --collector.f2b.exit-on-socket-connection-error\n                                      When set to true the exporter will immediately\n                                      exit on a fail2ban socket connection error\n                                      ($F2B_EXIT_ON_SOCKET_CONN_ERROR)\n      --collector.textfile.directory=STRING\n                                      Directory to read text files with metrics from\n                                      ($F2B_COLLECTOR_TEXT_PATH)\n      --web.basic-auth.username=STRING\n                                      Username to use to protect endpoints with basic auth\n                                      ($F2B_WEB_BASICAUTH_USER)\n      --web.basic-auth.password=STRING\n                                      Password to use to protect endpoints with basic auth\n                                      ($F2B_WEB_BASICAUTH_PASS)\n```\n\n**Environment variables**\n\nEach environment variable corresponds to a CLI flag.\nIf both are specified, the CLI flag takes precedence.\n\n| Environment variable            | Corresponding CLI flag                            |\n|---------------------------------|---------------------------------------------------|\n| `F2B_COLLECTOR_SOCKET`          | `--collector.f2b.socket`                          |\n| `F2B_COLLECTOR_TEXT_PATH`       | `--collector.textfile.directory`                  |\n| `F2B_WEB_LISTEN_ADDRESS`        | `--web.listen-address`                            |\n| `F2B_WEB_BASICAUTH_USER`        | `--web.basic-auth.username`                       |\n| `F2B_WEB_BASICAUTH_PASS`        | `--web.basic-auth.password`                       |\n| `F2B_EXIT_ON_SOCKET_CONN_ERROR` | `--collector.f2b.exit-on-socket-connection-error` |\n\n## 4. Building from source\n\nBuilding from source has the following dependencies:\n- Go v1.20\n- Make\n\nFrom there, simply run `make build`\n\nThis will download the necessary dependencies and build a `fail2ban_exporter` binary in the root of the project.\n\n## 5. Textfile metrics\n\nFor more flexibility the exporter also allows exporting metrics collected from a text file.\n\nTo enable textfile metrics provide the directory to read files from with the `--collector.textfile.directory` flag.\n\nMetrics collected from these files will be exposed directly alongside the other metrics without any additional processing.\nThis means that it is the responsibility of the file creator to ensure the format is correct.\n\nBy exporting textfile metrics an extra metric is also exported with an error count for each file:\n\n```\n# HELP textfile_error Checks for errors while reading text files\n# TYPE textfile_error gauge\ntextfile_error{path=\"file.prom\"} 0\n```\n\n**NOTE:** Any file not ending with `.prom` will be ignored.\n\n**Running in Docker**\n\nTo collect textfile metrics inside a docker container, a couple of things need to be done:\n1. Mount the folder with the metrics files\n2. Set the `F2B_COLLECTOR_TEXT_PATH` environment variable\n\n*For example:*\n```\ndocker run -d \\\n    --name \"fail2ban-exporter\" \\\n    -v /var/run/fail2ban:/var/run/fail2ban:ro \\\n    -v /path/to/metrics:/app/metrics/:ro \\\n    -e F2B_COLLECTOR_TEXT_PATH=/app/metrics \\\n    -p \"9191:9191\" \\\n    registry.gitlab.com/hctrdev/fail2ban-prometheus-exporter:latest\n```\n\n## 6. Troubleshooting\n\n### 6.1. \"no such file or directory\"\n\n```\nerror opening socket: dial unix /var/run/fail2ban/fail2ban.sock: connect: no such file or directory\n```\n\nThere are a couple of potential causes for the error above.\n\n**File not found**\n\nThe first is that the file does not exist, so first check that the file path shown in the error actually exists on the system running the exporter.\nThe fail2ban server may be storing the socket file in another location on your machine.\n\nIf you are using docker, make sure the correct host folder was mounted to the correct location.\n\nIf the file is not in the expected location, you can run the exporter with the corresponding CLI flag or environment variable to use a different file path.\n\n**Permissions**\n\nIf the file does exist, the likely cause are file permissions.\nBy default, the fail2ban server runs as the `root` user and the socket file can only be accessed by the same user.\nIf you are running the exporter as a non-root user, it will not be able to open the socket file to read/write commands to the server, leading to the error above.\n\nIn this case there are a few solutions:\n1. Run the exporter as the same user as fail2ban (usually `root`)\n2. Update the fail2ban server config to run as a non-root user, then run the exporter as the same user\n3. Update the socket file permissions to be less restrictive\n\nI would recommend option `1.` since it is the simplest. Option `2.` is a bit more complex, check the [fail2ban server documentation](https://coderwall.com/p/haj28a/running-rootless-fail2ban-on-debian) for more details. And option `3.` is just a temporary fix. The socket file gets re-created each time the fail2ban server is restarted and the original permissions will be restored, so you will need to update the permissions every time the server restarts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhctrdev%2Ffail2ban-prometheus-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhctrdev%2Ffail2ban-prometheus-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhctrdev%2Ffail2ban-prometheus-exporter/lists"}