Skip to content

CrowdSec

NetDefense can keep the settings of the CrowdSec plugin (os-crowdsec) consistent across your OPNsense fleet: which of its services run, whether its block rules are on, and which CrowdSec Console the engine enrolls in. One snippet type carries them:

Type What it syncs Where it appears on the firewall
CROWDSEC_SETTINGS The plugin’s general settings Services > CrowdSec > Settings

NetDefense manages the plugin’s settings only. It doesn’t replace the firewall’s WebAdmin, and it doesn’t install the plugin.

Before you start

  • Agent 1.29.0 or later on every device that receives the snippet. A device on an older agent fails its build with SNIPPET_AGENT_TOO_OLD, and no configuration reaches it until the agent is upgraded or the snippet no longer applies to it.
  • The os-crowdsec plugin installed on the device, for example through a software policy. On a device without the plugin nothing happens: the sync completes with a warning that the plugin isn’t installed.

The content is a JSON object with at least one of these keys:

Key Value Plugin setting Left out (agent 1.30.2)
agent_enabled true or false Enable Log Processor (IDS) on
lapi_enabled true or false Enable LAPI on
firewall_bouncer_enabled true or false Enable Remediation Component (IPS) on
rules_enabled true or false Create blocklist rules on
rules_log true or false Enable log for rules off
crowdsec_firewall_verbose true or false Verbose log for firewall bouncer off
rules_tag Letters and digits, 1 to 63 characters, or "" Tag for matched packets cleared
enroll_key Letters and digits, 1 to 63 characters, or "" Enrollment key from https://app.crowdsec.net cleared

Key names are exact and lowercase. A key that isn’t in the table is refused, with a suggestion when it looks like a typo. A boolean must be a JSON true or false, not a string.

{
"agent_enabled": true,
"lapi_enabled": true,
"firewall_bouncer_enabled": true,
"rules_enabled": true,
"rules_log": true,
"rules_tag": "branch",
"enroll_key": "${crowdsec_enrollment_key}"
}
Terminal window
ndcli snippet create crowdsec-settings --type CROWDSEC_SETTINGS --file crowdsec-settings.json

rules_tag and enroll_key can take a ${variable}. Use a secret variable for the enrollment key.

  • A key you leave out takes the plugin’s default from agent 1.30.2: the agent, the LAPI, the firewall bouncer and the blocklist rules are on, the two logging switches are off, and rules_tag and enroll_key are cleared. Spell out every value you rely on. Older agents kept the device’s value.
  • A device with a remote LAPI (its agent and bouncer use a manual Local API configuration) starts an idle local LAPI when the snippet leaves out lapi_enabled, and the sync that turns it on warns. That local LAPI may contact CrowdSec’s central API if online credentials exist. Set lapi_enabled to false to keep it off.
  • A sync with nothing to change leaves the settings alone. A device whose settings differ gets one CrowdSec restart at its sync.
  • A stopped engine is restarted once. When the settings already match but CrowdSec isn’t running, the sync restarts it. If it’s down again within the hour, the sync fails and names the engine instead of restarting it again.
  • At most one plugin reconfigure per sync. A reconfigure restarts CrowdSec and the bouncer, so blocking pauses briefly, and it contacts CrowdSec’s servers for a hub update.
  • The plugin owns its own aliases and block rules. NetDefense doesn’t touch them. rules_enabled and firewall_bouncer_enabled switch them on or off through the plugin.

When several CROWDSEC_SETTINGS snippets reach a device, only the one with the lowest priority number applies. If two or more share that lowest priority, the device’s sync fails with SNIPPET_SINGLETON_CONFLICT, naming the snippets, and the device gets no task until it’s fixed. Give one of them a lower number with ndcli snippet set-priority. See Snippet priority. The same rule applies to ZABBIX_SETTINGS.

Setting enroll_key requests enrollment. The sync result says enrollment was requested; it can’t confirm it.

  1. Put the key in a secret variable and reference it as enroll_key.
  2. Sync the device.
  3. In the CrowdSec Console, accept the engine. It appears under the device’s full host name, host plus domain.
  4. Restart the CrowdSec service on the device. CrowdSec asks for one restart after the engine is accepted.

Changing the key on an engine that is already enrolled doesn’t re-enroll it: the plugin leaves the existing enrollment as it is, and the new key is not applied. Moving an enrolled engine to another CrowdSec account happens outside the snippet; see CrowdSec’s documentation for cscli console enroll.

Detaching or deleting the snippet leaves the device as it is. NetDefense stops managing the settings. The plugin’s own defaults have everything on, so a reset would switch protection on, which is why nothing is reset. To turn a service off, push a snippet that sets it to false.

In this version NetDefense doesn’t manage allowlists, hub collections, the Console’s sharing options, or the Local API address and port. Manage those on the firewall.

  • Internal hosts get banned. The plugin installs no allowlist for private (RFC1918) addresses, so local scenarios can ban internal hosts. Add an allowlist on the firewall.
  • CrowdSec’s servers refuse requests. Each reconfigure contacts them. Devices behind one public IP share a request budget, so roll changes out one organizational unit at a time.
  • The agent refuses to turn off the Local API. Settings with lapi_enabled set to false while agent_enabled or firewall_bouncer_enabled stays on are refused, unless the device uses a manual Local API configuration. The error names the pair, for example lapi_enabled=false together with agent_enabled=true and firewall_bouncer_enabled=true leaves them without a local API to talk to. From agent 1.30.2, a key the snippet left out takes the default, on, and the error ends by naming it: agent_enabled left out of the snippet, so at the plugin's default. Set it to false.
  • The same settings aren’t applied again after a failure. After a failed apply, the agent doesn’t apply the same settings again for up to 1 hour, unless the snippet or the device changes. The message says not applied again because the previous apply failed.
  • A pull fails with crowdsec_settings '<name>' not found. The plugin isn’t installed on the device. Pulling needs os-crowdsec.
  • The sync completed but nothing changed. Check that the plugin is installed on the device. Without it the sync completes with a warning and applies nothing.
  • SNIPPET_AGENT_TOO_OLD. Upgrade the agent to 1.29.0 or later.