CrowdSec for other software
Switch CrowdSec on, and add your own log sources, never-ban ranges and collections without editing files LibrePortal manages.
On this page
LibrePortal installs and looks after CrowdSec on the server: the agent that reads logs and spots attackers, and the firewall bouncer that blocks them. Other software on the same server, such as a monitor or a web app with its own setup tool, should work with it, not install a second one. Two intrusion tools fighting over the firewall is a common way to break a server.
This page is for people who write that software, and for administrators who set it up. You hand LibrePortal a log source, a never-ban range or a collection, tagged with your name, and it keeps them for you.
Ask the server, don't guess#
Read CrowdSec's state as JSON first, before you change anything: see Security status.
Switch it on or off#
sudo -u libreportal libreportal crowdsec enable [--bouncer nftables] [--json]
sudo -u libreportal libreportal crowdsec disable [--json]
Both can be run again and again, and neither asks anything. enable installs CrowdSec through LibrePortal's own app install if it is missing (agent first, then your trusted places and the VPN go on the never-ban list, then the firewall bouncer, so nobody who is allowed in can be blocked in the gap) or starts it if it is stopped. disable stops the agent and the bouncer and leaves the package, so enable is quick. With --json the only output is {"ok": true, "action": "enable", "changed": false}. Only the nftables bouncer is supported.
Log sources#
libreportal crowdsec acquisition add --owner myapp --file /var/log/myapp/access.log --label nginx
libreportal crowdsec acquisition add --owner myapp --journal-unit myapp.service --label myapp
libreportal crowdsec acquisition list [--owner myapp] [--json]
libreportal crowdsec acquisition remove --owner myapp [--file <path> | --journal-unit <unit>]
--label is the CrowdSec log type, which picks the parser (for example nginx, syslog). A file must already exist, be a plain file (no symlink anywhere in its path), and live under /var/log or in a log or logs folder inside an app's folder. A journal unit must exist on the server, ends in .service (that is added if you leave it off), and is read with CrowdSec's journald source filtered to exactly that unit; nothing else can be passed through. list --json shows files as {"type":"file","file":"…"} and journald sources as {"type":"journald","unit":"…"}.
Never-ban ranges#
libreportal crowdsec allow add --owner myapp --cidr 10.44.0.0/24 --reason "myapp admin VPN"
libreportal crowdsec allow list [--owner myapp] [--json]
libreportal crowdsec allow remove --owner myapp [--cidr 10.44.0.0/24]
Each owner gets its own CrowdSec allow-list, so your operators can never be locked out by it. A range wider than /8 (IPv4) or /32 (IPv6) is refused, and so are 0.0.0.0/0 and ::/0: a never-ban list that covers the internet would switch protection off.
Collections#
libreportal crowdsec collection add --owner myapp crowdsecurity/nginx
libreportal crowdsec collection list [--owner myapp] [--json]
libreportal crowdsec collection remove --owner myapp [crowdsecurity/nginx]
A collection is uninstalled when the last owner that wanted it is gone. The ones LibrePortal itself uses (crowdsecurity/linux, crowdsecurity/sshd, crowdsecurity/traefik and what they bring) are never removed.
Decisions#
libreportal crowdsec decisions --json
is the list of active bans, one entry per decision (id, origin, type, scope, value, scenario, duration). libreportal crowdsec reload re-applies everything stored.
What LibrePortal owns, and what survives#
LibrePortal owns /etc/crowdsec/config.yaml, the firewall bouncer's file, the libreportal-adminaccess never-ban list and the acquisition file libreportal-traefik.yaml. Do not edit those. Your entries live in LibrePortal's database; on the server they appear as acquis.d/lpx-<owner>-<hash>.yaml and a never-ban list named lpx-<owner>. Nothing else in acquis.d or in the hub is touched, and anything you put in those lpx- files by hand is overwritten.
Your entries are put back after a reboot, after an update, and when CrowdSec is installed or re-enabled. They are part of the system backup, so a restore onto a new server brings them back (a log file that is not on the new server yet is skipped until it is). An entry whose log file has gone away is skipped until the file is back. Every change is written to the system journal under libreportal-crowdsec.
Who can do this#
The commands run as the libreportal user or root, through a root helper that checks every value again: owner names are 2 to 32 characters (lower case letters, digits, _ and -), at most 64 entries per owner and 256 in all. Nothing here can be changed from outside the server; the only thing served to an access key is the read-only status.