Skip to content

Installing CrowdSec in a Distributed Setup on Ubuntu

This guide walks you through setting up CrowdSec in a distributed architecture using Ubuntu. In this setup, we will configure a central server (the LAPI server) to receive threat signals from multiple log-processing agents on exposed servers such as Nextcloud, Wordpress, and Home Assistant.

What is CrowdSec?

CrowdSec is a modern security engine designed to detect and respond to malicious behaviors. It consists of two main components:

  • Detection Engine: Analyzes logs and identifies suspicious activity.
  • Remediation (Bouncers): Enforces defensive actions (e.g., blocking IPs) based on detections.

Out of the box, CrowdSec detects threats but takes no action unless a bouncer is installed.

Architecture Overview

In this guide:

  • The LAPI server (Local API) will be the central hub that stores and shares signals.
  • The child log processors (e.g., Nextcloud) will parse logs and forward detected threats to the LAPI.
  • Bouncers will be deployed on the child nodes to take automatic action against malicious IPs.

1. Install the LAPI Server (Core Engine)

Run the following on a clean Ubuntu server (LXC container or VM):

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl
curl -s https://install.crowdsec.net | sudo sh
sudo apt install crowdsec

Enable External API Access

Edit the configuration:

sudo nano /etc/crowdsec/config.yaml

Update:

listen_uri: 0.0.0.0:8080

Restart CrowdSec and allow the port:

sudo systemctl restart crowdsec
sudo ufw allow 8080/tcp

2. Install CrowdSec on Child Log Processors (e.g., Nextcloud)

On each exposed VM:

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

Register the agent with the central LAPI:

sudo cscli lapi register -u http://<LAPI_SERVER_IP>:8080 --machine <unique_machine_name>

Disable the Local API on the Child

We disable the local API on these nodes to conserve resources:

sudo nano /etc/crowdsec/config.yaml

Update or add:

api:
  server:
    enable: false

Then restart the service:

sudo systemctl restart crowdsec

3. Approve Child Machines from the LAPI Server

On the LAPI server, run:

sudo cscli machines list

Copy the Machine ID of the pending registration, then validate:

sudo cscli machines validate <MACHINE_ID>

You should now see the status as valid:

sudo cscli machines list

Repeat the above steps for each child server.

4. Install Bouncers (Remediation)

Add Bouncer on LAPI Server

This creates an API key for the child server’s bouncer:

sudo cscli bouncers add nextcloud-firewall

Make note of the API key printed. You’ll use it on the child server.

Install Bouncer on the Child Server

On the child server:

sudo apt install crowdsec-firewall-bouncer-iptables
sudo nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml

Update with:

api_url: http://<LAPI_SERVER_IP>:8080/
api_key: <YOUR_API_KEY_FROM_LAPI>

Restart the bouncer:

sudo systemctl restart crowdsec-firewall-bouncer

Repeat for each server.

5. Enroll Servers in the CrowdSec Console (Optional)

You can optionally manage your setup via the CrowdSec Console:

  1. Create an account.
  2. On each machine:
sudo cscli console enroll -e <[email protected]>