EN

Linux and networking

Install CrowdSec with a firewall bouncer

Protect your Debian or Ubuntu server with CrowdSec: installation, allowlisting your IP, firewall bouncer, collections, decisions and troubleshooting.

7 min read, updated on 18 November 2026

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 root or a sudo user
  • 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

Terminal
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:

Terminal
curl -fsSL https://install.crowdsec.net -o crowdsec-repo.sh
less crowdsec-repo.sh
sudo sh crowdsec-repo.sh

Then install the package:

Terminal
sudo apt update
sudo apt install crowdsec

Check the service:

Terminal
sudo systemctl status crowdsec
sudo cscli version

Step 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:

Terminal
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 status

The 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:

Terminal
echo $SSH_CONNECTION | awk '{print $1}'

Create an allowlist and add this address to it:

Terminal
sudo cscli allowlists create admins -d 'Admin addresses'
sudo cscli allowlists add admins YOUR_IP -d 'Admin workstation'
sudo cscli allowlists inspect admins

A 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:

Terminal
sudo cscli decisions delete --ip YOUR_IP

Step 5: install the firewall bouncer

Terminal
sudo apt install crowdsec-firewall-bouncer-iptables
sudo systemctl status crowdsec-firewall-bouncer
sudo cscli bouncers list

A 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

Terminal
sudo cscli capi status
sudo cscli metrics show acquisition parsers

The 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:

Terminal
ssh crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl@YOUR_SERVER_IP

On the server, the test alert must appear:

Terminal
sudo cscli alerts list -s crowdsecurity/ssh-generic-test

Test blocking

Use a public address you have access to, different from your administration address, in place of 203.0.113.10:

Terminal
sudo cscli decisions add --ip 203.0.113.10 --duration 5m --reason 'Test'
sudo cscli decisions list

After a few seconds, the address is added to the firewall and can no longer reach the server:

Terminal
sudo iptables -S CROWDSEC_CHAIN
sudo ipset list crowdsec-blacklists-0 | tail -n 5

Then remove the decision:

Terminal
sudo cscli decisions delete --ip 203.0.113.10

Collections 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/.

Terminal
sudo cscli collections list
sudo cscli collections list -a

For a service installed after CrowdSec, such as Nginx, add the collection:

Terminal
sudo cscli collections install crowdsecurity/nginx

Then create /etc/crowdsec/acquis.d/nginx.yaml:

YAML
filenames:
  - /var/log/nginx/*.log
labels:
  type: nginx

Test the configuration and restart:

Terminal
sudo crowdsec -t && sudo systemctl restart crowdsec
sudo cscli metrics show acquisition

Manage 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:

YAML
iptables_chains:
  - INPUT
  - DOCKER-USER

The 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:

Terminal
sudo systemctl edit crowdsec-firewall-bouncer
Configuration
[Unit]
After=docker.service
Wants=docker.service

Restart, then check:

Terminal
sudo systemctl restart crowdsec-firewall-bouncer
sudo iptables -S DOCKER-USER

CrowdSec 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:

Terminal
sudo cscli console enroll ENROLLMENT_KEY

Accept 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):

Terminal
sudo apt update
sudo apt install --only-upgrade crowdsec crowdsec-firewall-bouncer-iptables
sudo cscli hub update
sudo cscli hub upgrade
sudo systemctl restart crowdsec

Items 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:

Terminal
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.gz

This 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:

Terminal
sudo cscli decisions delete --ip YOUR_IP
sudo cscli allowlists add admins YOUR_IP

If 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_url in the bouncer configuration with listen_uri in /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:

Terminal
sudo cscli bouncers add firewall-bouncer-2
sudo nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
sudo systemctl restart crowdsec-firewall-bouncer

ent: machine not found or incorrect Username or Password

The local credentials no longer match the database:

Terminal
sudo cscli machines add -a --force
sudo systemctl restart crowdsec

No 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.

References