.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Debian ships CrowdSec in its own archive, and my advice is to skip it. The Debian 12 package is frozen at 1.4.6, which predates the AppSec component, the current hub format and roughly three years of scenario updates. Debian 13 carries something newer but it still trails the official repository, and CrowdSec is one of those tools where the detection rules matter as much as the binary.
This walkthrough uses the official repo on a Debian 12 VPS, and every command works unchanged on Debian 13 and Ubuntu 24.04. By the end the Security Engine will be parsing your logs and a firewall bouncer will be enforcing its bans, with the community blocklist layered on top.
If you're new to the architecture, the short version is that CrowdSec splits detection from enforcement. The engine reads logs and decides who's hostile; a separate Remediation Component (a bouncer, in CrowdSec speak) does the blocking. I've written a longer piece on what CrowdSec is and how the parts fit together if you want the full picture, and a CrowdSec vs Fail2ban comparison if you're migrating from the old guard.
Why the official repository beats the distro package
Distro archives freeze at release time. That's the right call for coreutils and a bad fit for a security tool whose parsers chase log formats and whose scenarios chase attacker behaviour. The official packagecloud repository tracks upstream, which as of May 2026 means the 1.7.8 release. The 1.7 line brought cscli setup (the service detection machinery) and usage metrics that show what your bouncers are dropping. None of that exists in 1.4.6.
The one argument for the distro package is unattended updates through Debian's own infrastructure. I don't find it convincing. CrowdSec's repo signs its packages, upgrades are boring in practice and you'd be trading a current engine for a fossil.
Add the CrowdSec repository
curl -s https://install.crowdsec.net | sudo shThe script detects your distribution and writes a sources file under /etc/apt/sources.list.d/. If piping a script from the internet into a root shell makes you twitch (healthy instinct), the official install docs list the manual steps: import the GPG key into /etc/apt/keyrings/ and add the packagecloud repo line yourself. Same result.
Before installing, confirm apt will pick the repo version and not Debian's:
apt-cache policy crowdsecThe candidate should be a 1.7.x version. If an old distro candidate wins instead, apt pinning fixes the priority; the install docs include a ready-made preferences file for exactly this. Then install:
sudo apt update
sudo apt install crowdsecSmall aside before the config spelunking starts: if this server doesn't exist yet, LumaDock has an Ubuntu 24.04 + CrowdSec template you pick during ordering. It deploys in seconds with the engine and bouncer already wired, so CrowdSec is watching from first boot. I still think you should read on so you know what's running, but you don't have to type any of it.
What the post-install step auto-detects
The package's post-install hook runs service detection against your box (on the 1.7 line this is cscli setup doing the work). On a bare Debian VPS it finds sshd and the system logs, installs the crowdsecurity/linux collection and registers the machine with the local API. A collection is a bundle of parsers and scenarios; crowdsecurity/linux pulls in SSH brute force detection among other things. Check what landed:
sudo cscli collections listIf you later add nginx or Postfix, install the matching collection from the CrowdSec hub and the engine starts covering those services too.
Acquisitions on Debian: journald vs auth.log
Acquisitions tell the engine which logs to read. They live in /etc/crowdsec/acquis.yaml and the /etc/crowdsec/acquis.d/ directory. Here's the wrinkle that catches people on modern Debian: rsyslog is no longer installed by default, so /var/log/auth.log may simply not exist. SSH events live in journald instead. The setup detection normally figures this out on its own, but if an acquisition points at a file that's never written, detection silently does nothing. A journald acquisition looks like this:
source: journalctl
journalctl_filter:
- "_SYSTEMD_UNIT=ssh.service"
labels:
type: syslogAfter any acquisition change, restart the engine with sudo systemctl restart crowdsec.
Confirm detection with cscli metrics and alerts
Two checks. First, is the engine reading anything at all?
sudo cscli metricsThe acquisition table shows lines read and lines parsed per source. Zeros in the read column mean your acquisition path is wrong; lines read but nothing parsed usually means a label mismatch.
Second, trigger it on purpose. From a different machine, fail a handful of SSH logins against the server. One warning about this test: since 1.6.3 the engine whitelists private RFC1918 ranges by default, so hammering from a LAN address will never produce a ban. Test from a genuinely external IP. Then:
sudo cscli alerts list
sudo cscli decisions listYou should see an SSH brute force alert against your test IP and a matching ban decision. Nothing is blocked yet, though, which brings us to the part people skip.
Install the firewall bouncer
The engine alone is a smoke detector. Decisions pile up in the local API and nothing enforces them until a Remediation Component subscribes. For a plain VPS the firewall bouncer is the right first one:
sudo apt install crowdsec-firewall-bouncer-iptablesThere's a crowdsec-firewall-bouncer-nftables package as well, and on Debian 12/13 (where iptables is a compatibility shim over nftables) it's arguably the cleaner pick. I've gone deep on modes, ipsets and the Docker traps in a dedicated firewall bouncer guide, so here I'll just verify it registered:
sudo cscli bouncers listThe bouncer should appear with a recent pull timestamp. Now repeat the failed-login test from outside and watch the connection start timing out mid-test. Before you do, read up on rolling CrowdSec out without locking yourself out; testing brute force detection from the same laptop you administer the box from is a classic way to ban your own IP.
Console enrollment and the community blocklist
Your engine already shares alert signals with the Central API and receives the community blocklist in return, a curated feed of IPs currently attacking the wider CrowdSec network. Verify the link is healthy:
sudo cscli capi statusEnrolling the engine in the free console at app.crowdsec.net adds a web view of your alerts plus extra blocklist subscriptions. Grab the enrollment key from the console and run:
sudo cscli console enroll YOUR_ENROLL_KEYThen approve the machine in the web UI and restart crowdsec. I resisted the console for a while out of self-hosting stubbornness and eventually caved; seeing which scenarios fire across several servers in one place is worth the account.
Upgrades: apt packages and hub objects
Two things version independently. The engine and bouncer upgrade through apt like everything else:
sudo apt update && sudo apt upgradeParsers, scenarios and collections upgrade through the hub:
sudo cscli hub update
sudo cscli hub upgrade
sudo systemctl reload crowdsecI run the hub pair monthly. New scenarios and parser fixes land continuously, and an apt upgrade alone won't fetch them.
Uninstall CrowdSec cleanly
sudo systemctl stop crowdsec crowdsec-firewall-bouncer
sudo apt purge crowdsec crowdsec-firewall-bouncer-iptables
sudo rm -rf /etc/crowdsec /var/lib/crowdsecPurge removes the packages and most of the config; the manual rm clears hub data and the local decision database that survive it. If the machine was enrolled, remove it from the console too so it stops showing up as offline.
That's a complete install. When something misbehaves later, my CrowdSec troubleshooting cheat sheet covers the errors I hit in practice, and once SSH is boring again the same engine can grow into a web application firewall with the AppSec component.
That one deserves its own afternoon :)
