Skip to main content

About multi-server setup

Crowdsec's architecture allows distributed setups, as most components communicate via HTTP API.

When doing such, a few considerations must be kept in mind to understand the role of each component:

  • The agent is in charge of processing the logs, matching them against scenarios, and sending the resulting alerts to the local API
  • The local API (LAPI from now on) receives the alerts and converts them into decisions based on your profile
  • The bouncer(s) query the LAPI to receive the decisions to be applied

A typical multi server setup should thus have:

  1. Agents push alerts to LAPI :
  • The local_api_credentials.yaml should point to LAPI's Ip

  • The agent should be registered to the local api

    Using login/password authentication

    • By running cscli machines add MyMachine on the LAPI (and c/c the generated credentials to the agent)
    • or by running cscli lapi register --machine MyMachine --url http://<lapi> on the agent and accepting the machine from LAPI with cscli machines validate MyMachine

    Using client cert authentication

Once done, you can check that the agent can communicate with LAPI :

# cscli  lapi status
INFO[20-12-2021 01:31:33 PM] Loaded credentials from /etc/crowdsec/local_api_credentials.yaml
INFO[20-12-2021 01:31:33 PM] Trying to authenticate with username xxxx on http://<LAPI IP>:8080/
INFO[20-12-2021 01:31:33 PM] You can successfully interact with Local API (LAPI)


To avoid any confusion, disabling the LAPI service on the machine running the agent can be done by commenting out the api->server section in the config.yaml file

  1. Bouncers speaking to LAPI
  • ⚠️ Most of the bouncers installers are going to assume that LAPI is running on the same machine
  • You need to modify the bouncer's configuration (in /etc/crowdsec/bouncers/) to be sure they speak to the LAPI:
    • Create an API key from LAPI with cscli bouncers add MyBouncer
    • Or again, rely on client certificate authentication for the bouncers that support it
    • Edit the bouncer's configuration file to be sure it points to the LAPI uri and uses the newly generated API key

Things to keep in mind

  • Parsers and Scenarios must be present on the agents. It's not useful to deploy them on LAPI
  • Decisions are made by LAPI. This is where you want to setup eventual custom profiles, and this is where you bouncers should point
  • You can use the console, it supports multiserver setups!
  • If you have an important setup, switching LAPI backend from SQLite to MySQL/PgSQL is strongly advised

This existing article might as well be useful!