Updated: 2026-07-17

CrowdSec, the modern evolution of fail2ban, installs on Debian or Ubuntu with the official script (curl -s https://install.crowdsec.net | sudo sh followed by sudo apt install crowdsec); after that you enable the right collections and add at least one bouncer (the component that queries blocking decisions and enforces them, for example in Traefik or the firewall) to move from plain detection to real protection. CrowdSec[1] is a community WAF (web application firewall, the layer that filters malicious HTTP requests before they reach your app): it decouples detection from blocking, exposes a local API, and leans on a blocklist fed by thousands of voluntary installations around the world. This guide walks through installation and Traefik integration, explaining why each piece exists, not just which commands to copy.

Key takeaways

  • CrowdSec separates detection (agent + LAPI) from blocking (bouncers): the same decision source can feed an HTTP bouncer in Traefik and a network bouncer in iptables at the same time.
  • Acquisition is the step most often forgotten: telling the agent which logs to read, with the right labels, is critical.
  • Captcha remediation (Cloudflare Turnstile) avoids banning legitimate users in brute-force scenarios.
  • The community blocklist blocks hundreds of known IPs before they get a chance to do anything.
  • On a hobby VPS with a single layer to protect, fail2ban is still simpler; CrowdSec pays off once you have two or three layers.

Why the switch from fail2ban is worth it

The most important difference is architectural. fail2ban reads logs, decides, and runs an iptables rule in the same process. CrowdSec separates those responsibilities:

  • The agent reads logs and emits decisions to the LAPI (a local REST API that listens on 127.0.0.1:8080 by default).
  • Bouncers query the LAPI and enforce the block, whether on the firewall, on a reverse proxy, or on the web server itself.

This separation has practical consequences. You can run a bouncer on the firewall for SSH and another on Traefik for HTTP, and both act on the same decisions: you change detection without touching blocking. And if you decide to contribute your detections to the community, you get back an updated list of IPs currently attacking others.

The second difference is expressiveness. fail2ban uses regular expressions over log lines; CrowdSec uses scenarios (declarative YAML rules that combine what to detect, at what threshold, over what time window, and how to group matches). Writing a scenario for a new pattern is roughly a fifteen-minute exercise once you know the syntax.

Installing the agent

On Debian or Ubuntu:

curl -s https://install.crowdsec.net | sudo sh
sudo apt install crowdsec

The agent and the LAPI run in the same process, listening on localhost. sudo cscli version and sudo systemctl status crowdsec confirm everything started.

Collections: work saved from day one

A collection (a package that bundles parsers, the translators for a specific log format, and scenarios ready for a given technology) saves you from writing rules from scratch. For a typical stack with Traefik, WordPress and Gitea:

sudo cscli collections install crowdsecurity/traefik
sudo cscli collections install crowdsecurity/wordpress
sudo cscli collections install crowdsecurity/gitea

Each collection brings what you need: the WordPress one detects login brute force, user enumeration, and access to sensitive paths like wp-config.php. You do not need to understand every scenario on day one; within a few days you will have reviewed which ones fire on your real traffic.

Telling the agent what to read

This is the step most often forgotten. Acquisition (the configuration that tells the agent which files to read and with what label) goes in /etc/crowdsec/acquis.yaml. For a setup with Traefik in Docker and SSH via systemd:

- filenames:
    - /var/log/traefik/access.log
  labels:
    type: traefik
- source: journald
  journalctl_filter:
    - "_SYSTEMD_UNIT=sshd.service"
  labels:
    type: syslog

The type label is not arbitrary: parsers filter by it. If you set type: traefik-access when the parser expects type: traefik, nothing gets detected and there is no explicit error; this is the most common mistake among new users. After editing the file: sudo systemctl restart crowdsec. Within a few minutes, sudo cscli metrics should show lines being processed.

Diagnosis: what to look at in the first days

Three commands worth turning into a habit:

  • sudo cscli alerts list: triggered alerts (detections).
  • sudo cscli decisions list: active decisions (IPs currently blocked or under captcha).
  • sudo cscli metrics: detection rate, cache hit ratio, general state.

If the agent has been running more than 24 hours and none of these commands show activity, your acquisition is almost certainly not reading what you think it is.

Bouncers: from detection to effective blocking

CrowdSec detects, but it does not block anything on its own yet. You need at least one bouncer. For Traefik, the official plugin is maxlerebourg/crowdsec-bouncer-traefik-plugin[2], which you can install on top of the Traefik with Docker Compose guide if you do not have the reverse proxy running yet.

It is declared in Traefik’s static configuration as an experimental plugin and in the dynamic configuration as a middleware. The plugin queries the LAPI in stream mode (it caches decisions and refreshes every few seconds), so perceived latency for the visitor does not increase.

Generate the bouncer API key like this:

sudo cscli bouncers add traefik-bouncer

Copy the token shown once and put it in the middleware configuration.

For SSH, add the firewall bouncer:

sudo apt install crowdsec-firewall-bouncer-iptables

It configures itself from the decisions already active. You now have two bouncers sharing the same decision source.

Captcha remediation: not everything is a ban

The classic WAF mistake is banning everything suspicious and finding out a week later that you were blocking legitimate customers. CrowdSec lets you issue captcha-type decisions instead of ban. The Traefik bouncer knows how to interpret them: it shows a Cloudflare Turnstile[3] challenge instead of cutting the connection.

The pattern that works well in production:

  • Brute force (someone trying passwords): captcha. The legitimate user solves it and moves on.
  • Known exploits (CVEs such as CVE-2021-44228, or access to sensitive paths): direct ban. An exploit bot does not solve captchas.

Turnstile integration only requires two keys (site key and secret key) from the Cloudflare dashboard; the service is free and allows a generous request volume for normal use.

The real value of the community blocklist

Registering your installation with the central CAPI (sudo cscli capi register) puts you on CrowdSec’s community network; CrowdSec is the French company founded in late 2019 that maintains the project. You start receiving an updated list of IPs currently attacking others, and you contribute your own (anonymized): the more detections you share, the fuller the blocklist you get back. Check your metrics before and after enabling the CAPI and you will see how noise from typical endpoint-probing attempts drops.

Ethical nuance: sharing detections contributes to collective defense, but you are also sending information about your traffic. For most installations that trade-off is acceptable; for environments with strict privacy requirements, read the terms before turning it on.

Monitoring

CrowdSec exposes Prometheus metrics on a local HTTP endpoint, by default at 127.0.0.1:6060/metrics (you can check this in the official metrics documentation[4]). If you already monitor the server with something like the Netdata with Docker guide, this endpoint fits right into that dashboard too. Useful metrics:

  • cs_bucket_overflow_count: accumulated detections.
  • cs_active_decisions: currently blocked IPs.

There is an official Grafana dashboard ready to import. The most important alert is not a detection spike (that can be noisy) but the absence of metrics for more than five minutes: that is the signal that the agent stopped or acquisition broke.

Whitelists and common mistakes

Before blocking anything seriously, make sure your own IPs are whitelisted: your office, the VPN you use, the CI/CD that runs deployments, external uptime monitors. This goes in /etc/crowdsec/parsers/s02-enrich/whitelists.yaml and accepts individual IPs and CIDR ranges, for example 203.0.113.0/24 for an entire office subnet. The number of admins who have blocked themselves in the first hours easily exceeds the number of attackers they frustrated that same day.

Another frequent mistake: not restarting the agent after editing configuration. CrowdSec does not hot-reload most files; running systemctl restart crowdsec after every edit is basic discipline.

When CrowdSec does not pay off

There are scenarios where fail2ban is still simpler and more appropriate:

  • A single server with low traffic and no need to share intelligence between nodes.
  • No Traefik (no HTTP plugin) and no multiple layers to protect.

CrowdSec starts paying off once you have more than one layer (web, SSH, applications), when the community blocklist cuts noise in a measurable way, or when you want to integrate it with Ansible to manage whitelists and configuration centrally across several servers.

My recommendation

If you are going to try it, do it as a staged rollout:

  1. Install the agent, configure acquisition, and leave it a week in detection-only mode with no bouncer.
  2. Review what fires, tune scenarios if there is noise, add whitelists.
  3. Only then activate the first bouncer (Traefik).
  4. Wait another week and add captcha remediation for brute force.
  5. Finally, connect to the CAPI.

Reaching this level of maturity takes two or three weeks of living with the tool. The investment is worth it for any stack with real exposure to the internet.

Frequently asked questions

How do I know if CrowdSec is actually blocking traffic?

Run sudo cscli decisions list: if rows appear with IPs and a decision type (ban or captcha), the matching bouncer is actively enforcing blocks. If the list stays empty after several hours of normal traffic, check acquisition first before suspecting the bouncer.

Do I need Traefik to use CrowdSec?

No. The agent and the LAPI work the same way without Traefik; what changes is the bouncer. Without a reverse proxy you can use the firewall bouncer with iptables or nftables to block at the network level, and add an HTTP bouncer later if you bring in Traefik or another supported proxy.

Is CrowdSec’s community blocklist free?

Yes. Registering your install with cscli capi register gets you a basic blocklist at no cost. If you also contribute your own detections regularly, CrowdSec expands your access to a fuller community blocklist; paid plans add extra premium lists, but they are not required for the setup described in this guide.

Sources

  1. CrowdSec
  2. maxlerebourg/crowdsec-bouncer-traefik-plugin
  3. Cloudflare Turnstile
  4. official metrics documentation
  5. official CrowdSec installation documentation

Route: Self-hosting with Docker: from zero to production