Setting Up CrowdSec on your Linux Server: A Complete Guide

Previously, I wrote about setting up fail2ban to protect your server from malicious attacks and brute-force attempts, which works quite well. However, there is a better alternative: CrowdSec. CrowdSec is an open-source, collaborative security engine that detects and blocks malicious behavior using shared threat intelligence. Unlike traditional fail2ban-style tools, it crowdsources attack patterns across its entire user base, which means your server benefits from bans triggered by attacks on other machines worldwide.

This guide walks through a full production setup on the Ubuntu 22.04 LTS operating system, which should also work on other systems.

Prerequisites

• A server running Ubuntu or any other operating system


• 
  sudo access


• nftables installed (sudo apt install nftables -y) [iptables will also work. But needs separate setup for that]


• Grafana Prometheus for monitoring section


• A Telegram account (for the optional notification section)

1. Installing CrowdSec

CrowdSec provides an official repository script that handles APT source registration:

# Add the CrowdSec repository

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



# Install the agent

sudo apt update && sudo apt install crowdsec -y

Verify the service is running:

sudo systemctl status crowdsec

sudo cscli version

Note: On first install, CrowdSec runs a detection wizard (wizard.sh) that scans your running services and pre-populates the log acquisition config. You can find the log acquisition config from this location and configure it as per your use case /etc/crowdsec/acquis.yaml

2. Enrolling into the CrowdSec Security Engine

Enrollment links your local agent to the CrowdSec Console, giving you access to the shared blocklist network, centralized alert management and remote decision control.

Steps:

1. Create a free account at app.crowdsec.net
   


2. Navigate to Engines → Enroll and copy your enrollment key


3. Run on your server:
   

sudo cscli console enroll <YOUR_ENROLLMENT_KEY>

1. Restart CrowdSec:
   

sudo systemctl restart crowdsec

1. Go back to the Console and accept the engine from the UI.

Once accepted, your instance appears under Engines with a green status. You can now install their blocklists from the UI and manage decisions remotely.

3. Installing the Firewall Bouncer

Now that you have your security engine running, it's time to install the remediation component. The remediation component is primarily responsible for blocking threat actors. One great thing about CrowdSec is that you can choose which type of remediation component you want. For example, if you want to ban an IP from your firewall, you can use cs-firewall-bouncer. If you want to restrict the IP from your Nginx server, then you will install cs-nginx-bouncer, and there are many more options. Here, we will use the nftables-compatible cs-firewall-bouncer.

sudo apt install crowdsec-firewall-bouncer-nftables -y

Enable and start it:

sudo systemctl enable --now crowdsec-firewall-bouncer

Confirm the bouncer registered with the agent:

sudo cscli bouncers list

Warning: Ensure the nf_tables kernel module is loaded before starting the bouncer: sudo modprobe nf_tables

4. Installing Collections

Collections bundle parsers and detection scenarios for specific services. Install the ones matching your environment:

# Core service collections

sudo cscli collections install crowdsecurity/nginx

sudo cscli collections install crowdsecurity/sshd

sudo cscli collections install crowdsecurity/mysql

sudo cscli collections install crowdsecurity/linux



# Optional but recommended

sudo cscli collections install crowdsecurity/http-cve

sudo cscli collections install crowdsecurity/iptables

Activate the configuration change:

# Reload to activate new parsers and scenarios

sudo systemctl reload crowdsec

Verify what's installed:

sudo cscli collections list

The output should show something like below:

Tip: There's a lot of already developed collections by their community out there. You can search the available collections on their console app and then install it with the mentioned command.

5. Configuring Log Acquisition

CrowdSec reads logs via /etc/crowdsec/acquis.yaml. While the wizard generates this automatically, you should review and modify it based on your specific use cases. For example, if your Nginx logs are stored in a custom location rather than /var/log/nginx/error.log, you must update the configuration accordingly. Below is a sample illustrating the structure of an acquis.yaml file:

# /etc/crowdsec/acquis.yaml



filenames:

  - /var/log/nginx/access.log

  - /var/log/nginx/error.log

labels:

  type: nginx

---

# SSH auth logs

filenames:

  - /var/log/auth.log

labels:

  type: syslog

---

# MySQL error log

filenames:

  - /var/log/mysql/error.log

labels:

  type: mysql

---

# General syslog and kernel log

filenames:

  - /var/log/syslog

  - /var/log/kern.log

labels:

  type: syslog

After any changes don't forget to reload crowdsec:

sudo systemctl reload crowdsec

Use sudo cscli metrics to confirm log files are being tailed. Zero parsed lines typically means a missing collection or wrong type label.

6. Whitelisting IPs with cscli allowlist

CrowdSec newer versions include a native allowlist command to permanently exempt IPs or CIDRs from bans. It is useful for your own infrastructure, monitoring tools or trusted partners. My recommendation is always whitelist your own IPs so that you don't get accidentally banned and blocked out of your own server.

Create an allowlist:

sudo cscli allowlists create my_allowlist \

  --description "Trusted internal and monitoring IPs"

Add IPs or CIDRs:

# Single IP

sudo cscli allowlists add my_allowlist 192.168.1.10 \

  --comment "Internal monitoring"



# CIDR range

sudo cscli allowlists add my_allowlist 10.0.0.0/8 \

  --comment "Private network range"



# Multiple IPs at once

sudo cscli allowlists add my_allowlist \

  203.0.113.5 203.0.113.10 \

  --comment "Partner IPs"

Manage allowlists:

sudo cscli allowlists list

sudo cscli allowlists inspect my_allowlist

sudo cscli allowlists remove my_allowlist 203.0.113.5

sudo cscli allowlists delete my_allowlist

Allowlisted IPs are evaluated before any decision is applied and they will never be banned even if they trigger a scenario.

7. Configuring nftables as the Bouncer Backend

Edit the bouncer config at /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml:

mode: nftables

update_frequency: 10s

log_mode: file

log_dir: /var/log/

log_level: info

log_compression: true

log_max_size: 100

log_max_backups: 3

log_max_age: 30

api_url: http://127.0.0.1:8080/

api_key: <BOUNCER_API_KEY>

insecure_skip_verify: false

disable_ipv6: false

deny_action: DROP

deny_log: false

supported_decisions_types:

  - ban

blacklists_ipv4: crowdsec-blacklists

blacklists_ipv6: crowdsec6-blacklists

ipset_type: nethash



## nftables

nftables:

  ipv4:

    enabled: true

    set-only: false

    table: crowdsec

    chain: crowdsec-chain

    priority: -10

  ipv6:

    enabled: true

    set-only: false

    table: crowdsec6

    chain: crowdsec6-chain

    priority: -10



nftables_hooks:

  - input

  - forward



# packet filter

pf:

  # an empty string disables the anchor

  anchor_name: ""

The bouncer API key is auto-generated on install. To retrieve or regenerate it:

sudo cscli bouncers list



# Regenerate if needed

sudo cscli bouncers delete crowdsec-firewall-bouncer

sudo cscli bouncers add crowdsec-firewall-bouncer

Restart the bouncer and verify nftables rules:

sudo systemctl restart crowdsec-firewall-bouncer

sudo nft list ruleset | grep crowdsec

Warning: If you're running both iptables and nftables, use the iptables-nft backend to avoid rule conflicts: sudo update-alternatives --set iptables /usr/sbin/iptables-nft

8. Prometheus + Grafana Integration

CrowdSec exposes a Prometheus metrics endpoint out of the box — no extra plugin needed.

Enable Prometheus in CrowdSec

Confirm or add the following in /etc/crowdsec/config.yaml:

prometheus:

  enabled: true

  level: full

  listen_addr: 127.0.0.1

  listen_port: 6060

Reload and test:

sudo systemctl reload crowdsec

curl -s http://127.0.0.1:6060/metrics | head -20

Configure Prometheus to Scrape CrowdSec

Add a scrape job to your prometheus.yml:

scrape_configs:

  - job_name: 'crowdsec'

    static_configs:

      - targets: ['localhost:6060']

    scrape_interval: 30s

Reload Prometheus:

sudo systemctl reload prometheus

# Or via the HTTP API if enabled:

curl -X POST http://localhost:9090/-/reload

Import the Grafana Dashboard

1. In Grafana, go to Dashboards → Import
   


2. Use dashboard ID 21419 (Crowdsec Metrics)


3. Select your Prometheus datasource and click Import
   


4. You can also import dashboards from their official github repository here: Crowdsec Grafana Dashboards
   

Key metrics to monitor:

9. Telegram Notification Integration

CrowdSec's HTTP notification plugin can POST alerts to any webhook, including Telegram's Bot API. Alerts include inline buttons linking the offending IP to Shodan and the CrowdSec CTI.

Step 1: Create a Telegram Bot

1. Open Telegram and search for @botfather
   


2. Send /newbot and follow the prompts — save your bot token
   


3. Add the bot to your target group or channel


4. Get the chat ID:
   

curl -s https://api.telegram.org/bot<BOT_TOKEN>/getUpdates \

  | python3 -m json.tool | grep '"id"'

Group chat IDs are negative integers (e.g., -123456789).

Step 2: Configure the Plugin

Create /etc/crowdsec/notifications/http_tg.yaml:

# Author: Nirjas Jakilim

type: http

name: http_tg

log_level: info



format: |

  {

   "chat_id": "-YOUR_CHAT_ID",

   "text": "

     {{range . -}}

     {{$alert := . -}}

     {{range .Decisions -}}

     {{if $alert.Source.Cn -}}

  Scenario: {{.Scenario}}

  IP: {{.Value}}

  Ban Duration: {{.Duration}}

  Country: {{$alert.Source.Cn}}

  AS Name: {{$alert.Source.AsName}}

    {{end}}

     {{if not $alert.Source.Cn -}}

  Scenario: {{.Scenario}}

  IP: {{.Value}}

  Ban Duration: {{.Duration}}

  Country: Unknown

    {{end}}

     {{end -}}

     {{end -}}

   ",

   "reply_markup": {

      "inline_keyboard": [

          {{ $arrLength := len . -}}

          {{ range $i, $value := . -}}

          {{ $V := $value.Source.Value -}}

          [

              {

                  "text": "See {{ $V }} on shodan.io",

                  "url": "https://www.shodan.io/host/{{ $V }}"

              },

              {

                  "text": "See {{ $V }} on crowdsec.net",

                  "url": "https://app.crowdsec.net/cti/{{ $V }}"

              }

          ]{{if lt $i ( sub $arrLength 1) }},{{end }}

          {{end -}}

      ]

    }

  }

url: https://api.telegram.org/bot<BOT_TOKEN>/sendMessage

method: POST

headers:

  Content-Type: "application/json"

Step 3: Add Notifications in profiles.yaml

Edit /etc/crowdsec/profiles.yaml to attach http_tg to your remediation profiles:

# Skip re-banning IPs that already have an active decision

name: silence_ip_remediation

filters:

  - Alert.Remediation == true && Alert.GetScope() == "Ip" && GetActiveDecisionsCount(Alert.GetValue()) > 0

on_success: break

---

# Default IP ban — 500h with Telegram notification

name: default_ip_remediation

filters:

  - Alert.Remediation == true && Alert.GetScope() == "Ip"

decisions:

  - type: ban

    duration: 500h

notifications:

  - http_tg

on_success: break

---

# Range ban — 500h with Telegram notification

name: default_range_remediation

filters:

  - Alert.Remediation == true && Alert.GetScope() == "Range"

decisions:

  - type: ban

    duration: 500h

notifications:

  - http_tg

on_success: break

Step 4: Reload and Test

sudo systemctl reload crowdsec



# Send a test notification

sudo cscli notifications test http_tg

If the test fails, check /var/log/crowdsec/crowdsec.log for plugin errors. Common issues: wrong chat ID format, bot not added to the group, or malformed JSON in the format template.

If everything is alright the alert notifications will be like as below

!Crowdsec telegram notification example](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ne0av5eesel0xqe4j5o8.png)

Verifying the Full Stack

Once everything is configured, run these commands to confirm each layer is working:

# Agent status and active decisions

sudo cscli decisions list

sudo cscli alerts list



# Bouncer is enforcing bans

sudo nft list ruleset | grep crowdsec



# Metrics endpoint alive

curl -s http://127.0.0.1:6060/metrics | grep cs_active



# All services healthy

sudo systemctl status crowdsec crowdsec-firewall-bouncer

Conclusion

You now have a fully operational CrowdSec stack: the agent parsing logs from nginx, SSH, MySQL, and syslog, the nftables bouncer enforcing bans at the kernel level, IP allowlists protecting trusted sources, Prometheus and Grafana providing observability and Telegram delivering real-time alerts with one-click threat investigation links.

Because CrowdSec is collaborative, every ban your instance issues contributes back to the shared blocklist making the network stronger for everyone.