Ansible role crowdsec

Install and configure CrowdSec — the LAPI server, the agents that ship logs to it, and the bouncers (firewall, HAProxy, custom) that enforce its decisions.

One role, three roles in disguise. Pick the right crowdsec_mode and let the role figure out the rest.

Example Playbook

---
- name: Install the CrowdSec LAPI server
  hosts: crowdsec_server
  become: true
  roles:
    - role: crowdsec
      vars:
        crowdsec_mode: server
        crowdsec_agents_hostnames: "{{ groups['crowdsec_agents'] }}"
        crowdsec_bouncers_to_register:
          - { host: edge-01, name: firewall }
          - { host: edge-01, name: haproxy }

- name: Install the CrowdSec agents
  hosts: crowdsec_agents
  become: true
  roles:
    - role: crowdsec
      vars:
        crowdsec_mode: agent
        crowdsec_lapi_host: crowdsec-lapi.example.com

- name: Install the bouncers
  hosts: edge-01
  become: true
  roles:
    - role: crowdsec
      vars:
        crowdsec_mode: agent
        crowdsec_bouncers_firewall_enabled: true
        crowdsec_bouncers_haproxy_enabled: true

Run the server play first — it generates the credentials that the agents and bouncers will need on the next plays.

Role Variables

The full list (with comments) lives in defaults/main.yml. The ones you almost always end up touching:

Variable	Default	What it does
crowdsec_mode	agent	One of server (LAPI), agent, or bouncer.
crowdsec_lapi_host	crowdsec-lapi	Hostname agents and bouncers connect to.
crowdsec_lapi_port	8080	LAPI port.
crowdsec_collections	[crowdsecurity/linux, crowdsecurity/sshd]	Hub collections to install.
crowdsec_scenarios	a few HTTP probing scenarios	Hub scenarios to install.
crowdsec_scenarios_prune	false	Wipe everything in the hub before reinstalling, useful right after a fresh apt install crowdsec since the package post-install brings half the hub with it.
crowdsec_bouncer_authenticate	true	Whether bouncer hosts pull their API key (from the server-pushed fact or .crowdsec_creds/). Set to false when auth is handled outside the role.
crowdsec_bouncers_firewall_enabled	false	Deploy the firewall bouncer (nftables by default, switchable to iptables).
crowdsec_bouncers_haproxy_enabled	false	Deploy the HAProxy SPOA bouncer (patches haproxy.cfg, deploys SPOE config, manages the service).
crowdsec_bouncers_custom	[]	Custom bouncer definitions — see the example block in defaults/main.yml.
crowdsec_custom_files_path	""	Path on the controller to a directory containing per-environment overrides (profiles.yaml.j2, scenarios/, bouncers/custom/, acquis.d/).

Custom files

Anything in crowdsec_custom_files_path overrides the role's default templates. Layout:

files/
├── profiles.yaml.j2
├── acquis.d/
│   └── nginx.yaml
├── scenarios/
│   └── my-ssh-bf.yaml.j2
└── bouncers/custom/
    └── ssh-user/
        ├── config.yaml.j2
        └── scripts/bouncer.sh.j2

Then point at it:

crowdsec_custom_files_path: "{{ playbook_dir }}/files/"

Requirements

• Ansible 2.12 or newer.
• apt (the role uses the upstream CrowdSec packagecloud repo).
• For HAProxy bouncers: HAProxy already installed and managed elsewhere — the role only patches its config.

Compatibility

	bullseye	bookworm	focal	jammy	noble
Ansible 2.12+	yes	yes	yes	yes	yes

CrowdSec's own packagecloud repo is the source of truth for what versions actually run — the role just installs whatever is current there.

License

GPL-3.0-or-later — see LICENSE.

Author

Maintained by the IFB Core Cluster team. Issues and PRs welcome.