How to Use CrowdSec: The Beginner's Guide (First Install, First Bouncer, the Allowlist Rule, and Reading cscli)

CodexFuse Team · 2026-10-31T10:14:07.795Z · 16 min read

Learn how to use CrowdSec: install the open-source IPS engine, add your first firewall bouncer, allowlist your own IPs before blocking starts, and read cscli metrics, alerts, and decisions.

Learning how to use CrowdSec is the natural upgrade after you outgrow a single-host ban engine: your server still reads its own logs and blocks attackers at the firewall, but every block is now informed by what thousands of other servers saw a few minutes ago. CrowdSec is a free, open-source intrusion prevention system (MIT license) that pairs local log detection with a community blocklist, so an IP that hammered SSH on someone else's VPS this morning can already be blocked on yours before it ever knocks. This beginner's guide walks the whole first-use arc in one sitting: installing the engine, picking the right firewall bouncer, applying the allowlist rule before anything gets blocked, enabling the right collections, reading your first cscli commands, and optionally enrolling the free console. If you have only ever used the classic single-host ban engine, skim the Fail2ban beginner guide first — it takes five minutes and makes every contrast in this guide click instantly.

What Is CrowdSec, in One Paragraph?

CrowdSec is an open-source intrusion prevention system built from four pieces: a security engine that reads service logs (SSH, nginx, Traefik, Postfix, and over a hundred more), parses them, and matches them against curated behavior scenarios; a local API that stores the resulting blocking decisions; small remediation programs called bouncers that pull those decisions and enforce them at the firewall, web server, or reverse proxy; and an optional console, a web dashboard for viewing alerts and blocks across all your servers. The current release is v1.8.2, published October 26, 2026, and the project holds about 15,400 GitHub stars, per the official releases API checked while writing this guide. Its signature feature is the community blocklist: every install can share its decisions upstream, and the consensus of those shared decisions comes back down as preemptive blocks for attacks your server has not seen yet.

How Do You Use CrowdSec for the First Time?

The whole beginner arc is seven steps, and the order matters — the allowlist step before the bouncer is the one beginners skip and regret:

1. Install the CrowdSec engine from the official repository.
2. Check what the installer auto-detected: sudo cscli metrics and sudo cscli collections list.
3. Allowlist your own IPs (office, monitoring, admin) with the native allowlist commands — before any blocking starts.
4. Install the firewall bouncer that matches your packet filter: nftables or iptables.
5. Verify the bouncer registered itself: sudo cscli bouncers list and sudo cscli decisions list.
6. Install the collections for your other services (nginx, the base HTTP scenarios, HTTP CVE coverage).
7. Optionally enroll the free console to receive the community blocklist and get the web dashboard.

What Are the Parts of CrowdSec?

CrowdSec's documentation uses a small vocabulary, and learning it first makes every command obvious later. The Security Engine is the detection system itself: a Log Processor (often called the agent) that tails your service logs plus a Local API (LAPI) that stores blocking decisions and distributes them to remediation components. The Log Processor parses log lines with parsers and matches them against scenarios — YAML descriptions of malicious behavior such as password guessing, port scanning, or probing for vulnerable web paths. Bouncers are the separate programs that receive decisions from the LAPI and actually block: in the firewall, in the web server, in the reverse proxy, or even at a CDN. Collections are ready-made sets of parsers and scenarios for one service (SSH, nginx, Postfix), stored in the Hub catalog. The Console is the optional web interface for viewing alerts and blocks from every connected server in one place. The single most important architectural fact, stated explicitly in the official documentation: the Security Engine by itself does not block anything — it is only a detection system. Without a bouncer, CrowdSec will detect attacks and let the attackers straight through.

How Do You Install the CrowdSec Engine on Ubuntu or Debian?

You install CrowdSec from its own package repository, which the project's install script registers for you. The script at install.crowdsec.net adds the CrowdSec repository (hosted on Cloudsmith) to your APT sources — read what any install script does before piping it to a shell, but this one's job is exactly that: register the repo and its signing key. Then you install the engine package:

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

That installs three things: the daemon, the local API, and a first-boot catalog pull (cscli hub update) so the Hub's parsers and scenarios are current. On first install CrowdSec also runs a detection wizard that scans your running services and pre-installs the matching collections — on a fresh box that is usually the crowdsecurity/sshd collection (parsing /var/log/auth.log with brute-force and user-enumeration scenarios) plus the Linux base. Verify the install with the two sanity commands the independent guides all recommend:

sudo systemctl status crowdsec
sudo cscli metrics
sudo cscli machines list

The machines list should show your machine auto-registered with the local API. If cscli metrics shows no acquisition lines for a service you expected, CrowdSec is not reading that service's logs — and nothing is protected there. That one command is your ground truth for the entire setup.

Which Firewall Bouncer Should You Pick: nftables or iptables?

Picking the wrong bouncer backend is one of the documented beginner mistakes, so decide deliberately. Modern distributions — Debian 12 and newer, Ubuntu 24.04 and newer — use nftables as the native packet filter, and the iptables command on those systems is only a compatibility shim. CrowdSec ships a separate bouncer package per backend, and you want the one that matches the native filter:

sudo apt install crowdsec-firewall-bouncer-nftables   # or -iptables
sudo systemctl status crowdsec-firewall-bouncer
sudo cscli bouncers list

The bouncer registers itself with the local API on first boot and then pulls decisions every few seconds. The iptables variant manages its own chain (CROWDSEC_CHAIN) that it prepends to INPUT and FORWARD, so it composes with your existing firewall rules instead of replacing them — your UFW or hand-written rules keep working untouched. This is also the moment to remember the rule from the allowlist section below: on a fresh what is VPS hosting box, the bouncer is the component that can lock you out, so your own IPs must already be allowlisted before you install it.

What Is the Allowlist Rule, and Why Must It Come Before Blocking?

The allowlist rule is simple: whitelist your own addresses — office IP, monitoring servers, admin jump hosts — before you enable any blocking, because a false positive against your own monitoring IP bans it exactly like a bot. CrowdSec's modern, preferred mechanism is the native allowlist, added in version 1.6.8 and managed entirely through cscli. It integrates with the local decisions, the console blocklists, and the AppSec WAF enforcement, takes effect immediately with no restart, and even expires decisions that already exist against an address the moment you add it:

sudo cscli allowlist create my_allowlist -d "Trusted admin and monitoring IPs"
sudo cscli allowlist add my_allowlist 203.0.113.5
sudo cscli allowlist add my_allowlist 198.51.100.0/24
sudo cscli allowlist inspect my_allowlist

Add every IP you administrate from and every monitoring host that polls this server; use CIDR ranges for office and VPN subnets. Two comfort facts from the official behavior: CrowdSec ships a built-in crowdsecurity/whitelists parser that already discards all RFC 1918 private ranges, so tests from localhost or your Docker network never produce bans — only public-IP traffic reaches the scenarios at all. And the older parser-level YAML whitelist (/etc/crowdsec/parsers/s02-enrich/mywhitelists.yaml, with whitelist: / reason: / ip: / cidr: lists) still works, but the native allowlist is the current recommendation and the only one that also covers blocklist pulls and AppSec.

What Collections and Scenarios Run After the Install?

Whatever the install wizard detected is already running, but you confirm and extend it yourself with three cscli commands. Collections bundle a service's parsers, its scenarios, and any postoverflow they need; scenarios are the versioned, Hub-shared descriptions of attacks that the community keeps extending, which is why updating them is part of routine maintenance:

sudo cscli collections list
sudo cscli collections install crowdsecurity/nginx
sudo cscli collections install crowdsecurity/base-http-scenarios
sudo cscli collections install crowdsecurity/http-cve
sudo systemctl reload crowdsec

Run sudo cscli collections inspect crowdsecurity/nginx to see exactly what a collection contains before you trust it. Keep the Hub catalog fresh with sudo cscli hub update followed by sudo cscli hub upgrade — scenarios in the Hub are extended regularly as new attack patterns emerge, and an engine running year-old scenarios is only half an engine. If you run nginx behind a reverse proxy or a CDN, add the nginx bouncer (a Lua module configured in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf) or the Traefik middleware plugin; for Caddy there is a community bouncer plugin that points at the local API on port 8080 with a key you generate via sudo cscli bouncers add caddy-bouncer.

What Are the First cscli Commands You Should Learn?

cscli is the single control surface for the whole system, and six commands cover the first month. sudo cscli metrics is the main diagnostic: it shows what logs are being read, what is triggering, and what is whitelisted — if a service's lines are missing, CrowdSec is not protecting that service. sudo cscli alerts list shows detected attacks; sudo cscli decisions list shows the active blocks the bouncers are enforcing. The testing workflow that every guide teaches is to add a manual decision, watch it appear, then remove it:

sudo cscli metrics                 # what is read, what triggers
sudo cscli alerts list             # detected attacks
sudo cscli decisions list          # active block decisions
sudo cscli decisions add --ip 198.51.100.7 --duration 1h --reason "test"
sudo cscli decisions delete --ip 198.51.100.7
sudo cscli bouncers list           # registered remediation components
sudo cscli console enroll <enrollment-key>   # optional console enrollment

Two details save beginners real confusion. First, the allowlist from the previous section refuses new decisions against allowlisted addresses — so if your manual test ban silently does nothing, check that the test IP is not allowlisted before assuming the bouncer is broken. Second, cscli alerts list includes a kind column identifying which component generated each alert: crowdsec for local log detection, waf for an AppSec match, and cscli for a manually added decision.

How Does the Community Blocklist Work?

The community blocklist is CrowdSec's answer to the fundamental weakness of single-host blocking: your server only ever sees its own attackers. When your engine detects an attack it sends a signal upstream — just the attacker IP, the triggered scenario, and a timestamp. No logs, no request payloads, no usernames ever leave your machine. The CrowdSec central API compiles the signals of thousands of installs into a consensus list: an IP lands in the community blocklist only after multiple independent installs report it against multiple scenarios. Your engine then pulls that list and blocks those addresses preemptively — attackers your server has never seen are already stopped at your firewall because they were seen on someone else's.

How much of the list you receive depends on your contribution level: installs that regularly send signals receive the full list of up to 15,000 addresses, selected for the scenarios that appear on their hosts; installs that send nothing receive a reduced list of up to 3,000; paid plans extend coverage up to 60,000 addresses. You get the blocklist by enrolling the optional console, which is the next section. Enrollment is strictly opt-in — skip it and the local install keeps working with local decisions only, like a smarter Fail2ban.

How Do You Enroll the CrowdSec Console?

The console is the free web dashboard for viewing alerts and active decisions from all your servers in one place, and it is also the channel that delivers the community blocklist. Sign up for a free account at the CrowdSec console site, create an enrollment key in the web UI, and run it on the server:

sudo cscli console enroll <enrollment-key-from-console>

After enrollment the engine pulls the community blocklist alongside your locally generated decisions, and the dashboard starts showing the same alerts and decisions you see in cscli. This is the right moment for the fleet insight: one local API and one console can serve multiple servers, so a second and third machine just get the engine plus a bouncer and enroll the same way — each new machine immediately inherits the attack knowledge of the whole community. Keep the console credentials treated like any admin secret, and never expose the local API port 8080 itself to the internet; it is a localhost service that bouncers and your reverse proxy reach locally.

CrowdSec vs Fail2ban: Which One Do You Actually Need?

This is the comparison every beginner asks for, and the honest answer is that they overlap but aim at different jobs. The independent comparison published by systems engineer Mikhail Gorbachev frames it as a table, and it is worth reproducing in spirit because it settles the decision:

The practical rule: for a single server with SSH to protect, Fail2ban is sufficient and simpler — the Fail2ban beginner guide remains the right first read for that setup. CrowdSec earns its extra moving parts when you have multiple servers, when you need to protect web applications by behavior rather than only by failed logins, and when you want known attackers blocked before their first attempt. One firm warning from the same comparison: do not run Fail2ban and CrowdSec against the same logs at the same time — they will duplicate blocks and you will lose track of which system banned an address. Pick one per service. And if your whole edge is already a firewall appliance, the OPNsense beginner guide covers the distro lane, where CrowdSec-style blocking happens at the network perimeter instead.

Can CrowdSec Run in Docker?

Yes — CrowdSec ships for Linux, Windows, Docker, and Kubernetes, and there are maintained Docker Compose guides for running the engine as a container. The beginner caveat is that the firewall bouncer is the awkward piece in a container: it must manipulate the host's firewall, which means privileged host-network access, and beginners routinely misconfigure it. The path of least resistance for your first CrowdSec setup is the native package on the host, exactly as this guide teaches; move to the container topology once the concepts are comfortable. If containers are new to you generally, the Docker beginner guide covers the runtime fundamentals first.

Beginner Mistakes to Avoid

Every one of these appears in the independent deployment guides, and every one is avoidable in the first hour:

Sources

Every version number, command, and limit in this guide was verified against sources fetched on October 31, 2026: the official CrowdSec releases API on GitHub (v1.8.2 released October 26, 2026; about 15,400 stars); Mikhail Gorbachev's "Securing a Linux Server: Part 3 — CrowdSec" (bigmike.help, September 22, 2026) for the architecture, the engine-detects-only rule, the whitelist-before-blocking rule, the community blocklist tiers, and the CrowdSec-vs-Fail2ban comparison; Amir Eslampanah's "CrowdSec: a modern fail2ban with collaborative blocklists" (amireslampanah.com, May 2026) for the Cloudsmith repository, the first-boot catalog pull, the CROWDSEC_CHAIN behavior, manual decision testing, enrollment being opt-in, and what is actually shared upstream; the bitdoze.com "How to Secure a VPS Server with CrowdSec (2026 Guide)" for the native allowlist commands (added in 1.6.8), the nftables-vs-iptables decision, and the LAPI default port 8080; the dev.to complete setup guide for the native allowlist create/add/inspect flow; the dev.to Traefik write-up for the built-in private-range whitelist behavior; the NetBird CrowdSec IP reputation docs (October 14, 2026) for allowlist semantics including immediate effect on existing decisions; and the simplehomelab Docker Compose guide for the legacy YAML whitelist syntax.

CrowdSec Tutorial FAQ

Is CrowdSec really free?

Yes. CrowdSec is MIT-licensed open source: the engine, the bouncers, the Hub collections, and the console account are all free, and enrollment in the community blocklist costs nothing — you contribute signals and receive the consensus list in return. Paid plans exist only for larger blocklist coverage (up to 60,000 addresses) and team features; the free tier covers the full beginner arc in this guide.

Does CrowdSec replace Fail2ban?

It can, but it does not have to on day one. For one server with SSH to protect, Fail2ban is simpler and sufficient. CrowdSec is the better pick with multiple servers, web applications to protect by behavior, or a desire for preemptive community blocking. Never run both against the same logs simultaneously — they duplicate blocks and obscure which system acted.

Will CrowdSec slow down my VPS?

Noticeably less than you would expect. The independent comparison puts Fail2ban at minimal footprint and CrowdSec at "more, but moderate" — the engine is a single Go daemon tailing logs, and the firewall bouncer only acts when decisions arrive. On a typical small VPS the install is comfortable; the resource question only gets interesting on very tiny single-core boxes, where you should watch memory during the first week.

What if CrowdSec locks me out of my own server?

Remove the block with sudo cscli decisions delete --ip YOUR_IP, then add your IP to the native allowlist with sudo cscli allowlist add my_allowlist YOUR_IP — allowlisting expires existing decisions immediately and refuses new ones. This is exactly why the guide puts the allowlist step before the bouncer: prevention beats recovery.

Does the community blocklist send my logs to CrowdSec?

No. Your engine uploads only aggregated decisions — the attacker IP, the triggered scenario, and a timestamp. No log lines, no request payloads, and no usernames ever leave your machine, and an IP joins the community blocklist only after multiple independent installs report it against multiple scenarios.