Install CrowdSec with a firewall bouncer
Protect your Debian or Ubuntu server with CrowdSec: installation, allowlisting your IP, firewall bouncer, collections, decisions and troubleshooting.
On this page
Your values
Enter them once and the commands in this guide update.
CrowdSec analyzes your server's logs, spots malicious behavior (SSH brute force, web scans, etc.) and decides to block the addresses involved. This guide shows you how to install it on a VPS or a dedicated server, protect your own IP address, then apply the blocks at the firewall level.
How CrowdSec works
| Component | Role |
|---|---|
| Security Engine | Reads the logs and detects attacks using scenarios |
| Local API (LAPI) | Stores the decisions, listening on 127.0.0.1:8080 by default |
| Firewall bouncer | Fetches the decisions and blocks the addresses in the firewall |
cscli |
Command-line tool to manage everything |
Prerequisites
- A server running Debian 12/13 or Ubuntu 22.04/24.04
- SSH access with
rootor asudouser - The public IP address from which you administer the server
- A fallback way to access the server: on a VPS, the VNC console in your client area. On a dedicated server, check the available access or contact support from your client area
Ports: no incoming port needs to be opened. The LAPI (8080) and the metrics (6060) only listen on 127.0.0.1 and must not be exposed. The server must be able to reach api.crowdsec.net over HTTPS.
Step 1: check the local ports
sudo ss -ltnp | grep -E ':(8080|6060) 'If the command displays nothing, go to the next step. If port 8080 is already in use, for example by a Docker container, continue as well: step 3 covers this case.
Step 2: install CrowdSec
Download the official script that adds the repository, review it, then run it:
curl -fsSL https://install.crowdsec.net -o crowdsec-repo.sh
less crowdsec-repo.sh
sudo sh crowdsec-repo.shThen install the package:
sudo apt update
sudo apt install crowdsecCheck the service:
sudo systemctl status crowdsec
sudo cscli versionStep 3: change the LAPI port if needed
If port 8080 is taken, the package installs without starting the service and displays Not attempting to start crowdsec, port 8080 is already used. Choose a free port, here 8180, then edit the two files involved:
sudo sed -i 's|listen_uri: 127.0.0.1:8080|listen_uri: 127.0.0.1:8180|' /etc/crowdsec/config.yaml
sudo sed -i 's|^url: .*|url: http://127.0.0.1:8180|' /etc/crowdsec/local_api_credentials.yaml
sudo systemctl restart crowdsec
sudo cscli lapi statusThe message You can successfully interact with Local API (LAPI) confirms that everything works.
Step 4: allow your IP address
Do this before installing the bouncer, so you do not risk blocking your own access. From your SSH session, display the address in use:
echo $SSH_CONNECTION | awk '{print $1}'Create an allowlist and add this address to it:
sudo cscli allowlists create admins -d 'Admin addresses'
sudo cscli allowlists add admins YOUR_IP -d 'Admin workstation'
sudo cscli allowlists inspect adminsA range is added the same way, for example 198.51.100.0/24. An allowlist prevents new decisions but does not remove existing ones. If your address was already blocked:
sudo cscli decisions delete --ip YOUR_IPStep 5: install the firewall bouncer
sudo apt install crowdsec-firewall-bouncer-iptables
sudo systemctl status crowdsec-firewall-bouncer
sudo cscli bouncers listA bouncer installed on the same server registers itself automatically with the LAPI: it must appear in the list with a check mark in the Valid column. Its configuration is in /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.
This package uses iptables and ipset, which works with UFW and with Docker's DOCKER-USER chain. A crowdsec-firewall-bouncer-nftables package exists for setups based entirely on nftables.
Step 6: check detection and blocking
Overall status
sudo cscli capi status
sudo cscli metrics show acquisition parsersThe sources table may stay empty until a new line has been written to the logs since the service started.
Test SSH detection
From a machine whose address is not in your allowlist, run this connection, which will normally fail:
ssh crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl@YOUR_SERVER_IPOn the server, the test alert must appear:
sudo cscli alerts list -s crowdsecurity/ssh-generic-testTest blocking
Use a public address you have access to, different from your administration address, in place of 203.0.113.10:
sudo cscli decisions add --ip 203.0.113.10 --duration 5m --reason 'Test'
sudo cscli decisions listAfter a few seconds, the address is added to the firewall and can no longer reach the server:
sudo iptables -S CROWDSEC_CHAIN
sudo ipset list crowdsec-blacklists-0 | tail -n 5Then remove the decision:
sudo cscli decisions delete --ip 203.0.113.10Collections and log sources
A collection groups the parsers and scenarios of a service. At installation, CrowdSec detects the services present and writes the matching sources in /etc/crowdsec/acquis.d/.
sudo cscli collections list
sudo cscli collections list -aFor a service installed after CrowdSec, such as Nginx, add the collection:
sudo cscli collections install crowdsecurity/nginxThen create /etc/crowdsec/acquis.d/nginx.yaml:
filenames:
- /var/log/nginx/*.log
labels:
type: nginxTest the configuration and restart:
sudo crowdsec -t && sudo systemctl restart crowdsec
sudo cscli metrics show acquisitionManage decisions
| Action | Command |
|---|---|
| List decisions | sudo cscli decisions list |
| Ban an address for 24 h | sudo cscli decisions add --ip 203.0.113.10 --duration 24h --reason 'Manual ban' |
| Ban a range | sudo cscli decisions add --range 203.0.113.0/24 --reason 'Manual ban' |
| Unban an address | sudo cscli decisions delete --ip 203.0.113.10 |
| View alerts | sudo cscli alerts list |
| Alerts for an address | sudo cscli alerts list --ip 203.0.113.10 |
Without --duration, a manual decision lasts 4 hours. Avoid sudo cscli decisions delete --all, which also deletes local and community decisions.
Protect Docker containers
Ports published by Docker go through the FORWARD chain and not INPUT. For the bouncer to cover them, create /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local:
iptables_chains:
- INPUT
- DOCKER-USERThe list in this file replaces the one in the main file: so keep INPUT. Docker must be installed, because it is what creates the DOCKER-USER chain. For the bouncer to start after Docker, add a systemd drop-in:
sudo systemctl edit crowdsec-firewall-bouncer[Unit]
After=docker.service
Wants=docker.serviceRestart, then check:
sudo systemctl restart crowdsec-firewall-bouncer
sudo iptables -S DOCKER-USERCrowdSec Console (optional)
The web console lets you follow your alerts and your servers. Create an account on app.crowdsec.net, get your enrollment key, then run:
sudo cscli console enroll ENROLLMENT_KEYAccept the server in the console, then restart the service with sudo systemctl restart crowdsec. CrowdSec also works without this step.
Updates
Update the packages, then the Hub items (collections, scenarios, parsers):
sudo apt update
sudo apt install --only-upgrade crowdsec crowdsec-firewall-bouncer-iptables
sudo cscli hub update
sudo cscli hub upgrade
sudo systemctl restart crowdsecItems you have modified locally are not updated by cscli hub upgrade.
Backup
The configuration is in /etc/crowdsec and the data, including the default SQLite database, in /var/lib/crowdsec/data. Stop the service while copying to get a consistent database:
sudo systemctl stop crowdsec
sudo tar czf crowdsec-backup.tar.gz /etc/crowdsec /var/lib/crowdsec/data
sudo systemctl start crowdsec
sudo chmod 600 crowdsec-backup.tar.gzThis archive contains credentials: keep it in a safe place, off the server.
Troubleshooting
You are blocked by CrowdSec
Connect through the VNC console, or contact support for a dedicated server, then remove the decision and allow your address:
sudo cscli decisions delete --ip YOUR_IP
sudo cscli allowlists add admins YOUR_IPIf needed, sudo systemctl stop crowdsec-firewall-bouncer suspends the blocks while you fix things.
bind: address already in use
Another service is using the LAPI port. Identify it with sudo ss -ltnp | grep 8080, then apply step 3. If the bouncer was already installed, also update api_url in its configuration and restart it.
The bouncer displays connection refused
- Check that CrowdSec is running:
sudo systemctl status crowdsec - Compare
api_urlin the bouncer configuration withlisten_uriin/etc/crowdsec/config.yaml - Check
/var/log/crowdsec-firewall-bouncer.log
The bouncer displays API error: access forbidden
Its key is no longer recognized. Create a new one under a new name, copy it into api_key, then restart the bouncer:
sudo cscli bouncers add firewall-bouncer-2
sudo nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
sudo systemctl restart crowdsec-firewall-bouncerent: machine not found or incorrect Username or Password
The local credentials no longer match the database:
sudo cscli machines add -a --force
sudo systemctl restart crowdsecNo lines are being analyzed
- List the sources:
sudo cscli metrics show acquisition - Check the files in
/etc/crowdsec/acquis.d/and the actual path of your logs - Look for errors:
sudo grep -E 'level=(error|fatal)' /var/log/crowdsec.log
The bouncer no longer starts after adding DOCKER-USER
The chain does not exist until Docker has started. Check sudo systemctl status docker, then sudo iptables -S DOCKER-USER.