Skip to content

Commit 7bfce51

Browse files
buixorbuixor
authored
Merge pull request #17 from crowdsecurity/skill/pfsense
pfsense crowdsec skill
2 parents bd5bbe7 + 73d08d9 commit 7bfce51

2 files changed

Lines changed: 205 additions & 0 deletions

File tree

‎skills/crowdsec/SKILL.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ kubectl get pods -A 2>/dev/null | grep -i crowdsec
3737

3838
If nothing matches and the user reports CrowdSec is installed, ask where: a vendor appliance, a custom image, a binary in `/opt/`, or a remote host. Otherwise pivot to install: see [references/install/](./references/install/).
3939

40+
**pfSense detection:**
41+
```sh
42+
uname -i # → pfSense (pfSense CE or Plus)
43+
```
44+
If confirmed pfSense, go directly to [references/install/pfsense.md](./references/install/pfsense.md) — paths, service names, and activation flow are entirely different from Linux/systemd.
45+
4046
## Privileges — bare-metal / systemd prerequisite
4147

4248
On bare-metal/systemd, `cscli` and `crowdsec` need **root** (they read
@@ -94,6 +100,7 @@ Hub. If it's far behind `version.crowdsec.net/latest`, pull a newer tag
94100
| Cue from user | Go to |
95101
|---|---|
96102
| "install", "set up", "fresh box", "how do I start" | [references/install/](./references/install/) (pick file by env) |
103+
| "pfsense", "pfSense", "netgate" | [references/install/pfsense.md](./references/install/pfsense.md) |
97104
| "configure logs / acquisition", "read journald / syslog / docker logs" | [references/configure/acquisition.md](./references/configure/acquisition.md) |
98105
| "install a collection / parser / scenario", "hub", "tainted" | [references/configure/hub.md](./references/configure/hub.md) |
99106
| "ban duration", "captcha", "decisions", "simulation", "alerts but no bans" | [references/configure/profiles.md](./references/configure/profiles.md) |

‎skills/crowdsec/references/install/pfsense.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
verified:
3+
- date: 2026-05-27
4+
version: "1.7.8"
5+
env: pfsense
6+
notes: "full Large install (LAPI + log processor + bouncer) on pfSense Plus 26.03 / FreeBSD 16.0-CURRENT amd64"
7+
---
8+
9+
# Install — pfSense
10+
11+
Canonical docs: <https://docs.crowdsec.net/docs/getting_started/install_crowdsec_pfsense>
12+
13+
CrowdSec on pfSense is installed via a shell script (not via the pfSense Package Manager —
14+
the package is not yet in the official repos). The pfSense plugin manages configuration and
15+
service lifecycle. **Do not start or configure services manually** — the GUI save triggers
16+
everything.
17+
18+
## Detect environment
19+
20+
```sh
21+
uname -i # → pfSense (confirms pfSense, not generic FreeBSD)
22+
uname -r # → 15.0-CURRENT / 16.0-CURRENT (pfSense Plus 26.x) or 14.x (CE 2.8.x)
23+
pkg info | grep -i crowdsec # empty = not installed
24+
```
25+
26+
## Three install modes
27+
28+
| Mode | Components | Use when |
29+
|---|---|---|
30+
| **Large** (default) | Remediation + Log Processor + Local API | Standalone, no other CrowdSec instance |
31+
| **Medium** | Remediation + Log Processor | pfSense sends log data to a remote LAPI |
32+
| **Small** | Remediation only | pfSense enforces blocklists from a remote LAPI |
33+
34+
## Install
35+
36+
SSH into the pfSense box (default shell: `/bin/tcsh` for root):
37+
38+
```sh
39+
fetch https://raw.githubusercontent.com/crowdsecurity/pfSense-pkg-crowdsec/refs/heads/main/install-crowdsec.sh
40+
sh install-crowdsec.sh
41+
```
42+
43+
The script is interactive — it asks three confirmations. Answer **y** to each:
44+
1. Banner prompt (the script IS the correct install path — answer y to continue).
45+
2. Download confirmation (downloads the release `.tar` from GitHub).
46+
3. Install confirmation.
47+
48+
To install a specific release:
49+
50+
```sh
51+
sh install-crowdsec.sh --release v0.1.7-1.7.8-34
52+
```
53+
54+
To uninstall:
55+
56+
```sh
57+
sh install-crowdsec.sh --uninstall
58+
```
59+
60+
## Activate (GUI — required after install)
61+
62+
After `sh install-crowdsec.sh` completes, **services are not yet running**. Open the pfSense
63+
web UI and go to `Services` → `CrowdSec`. Verify that *Remediation Component*, *Log Processor*,
64+
and *Local API* are enabled. Click **Save**.
65+
66+
This triggers the pfSense plugin to:
67+
- Write the YAML config files (`/usr/local/etc/crowdsec/config.yaml`, bouncer config, LAPI credentials).
68+
- Register the machine and bouncer with the local LAPI.
69+
- Install the `crowdsecurity/pfsense` collection (hub update + upgrade).
70+
- Start both services via `service crowdsec.sh restart` and `service crowdsec_firewall.sh restart`.
71+
72+
**Verify activation:**
73+
74+
```sh
75+
service crowdsec status # crowdsec is running as pid <n>
76+
service crowdsec_firewall status # crowdsec_firewall is running as pid <n>
77+
cscli lapi status # You can successfully interact with Local API (LAPI)
78+
cscli capi status # You can successfully interact with Central API (CAPI)
79+
cscli bouncers list # pfsense-firewall 127.0.0.1 ✔️
80+
cscli machines list # pfsense 127.0.0.1 ✔️
81+
```
82+
83+
## Directory map (pfSense-specific paths)
84+
85+
| Path | What |
86+
|---|---|
87+
| `/usr/local/bin/crowdsec`, `/usr/local/bin/cscli` | Engine + CLI |
88+
| `/usr/local/etc/crowdsec/config.yaml` | Master config |
89+
| `/usr/local/etc/crowdsec/acquis.yaml` | Base acquisition (nginx, auth.log, httpd) |
90+
| `/usr/local/etc/crowdsec/acquis.d/pfsense.yaml` | pfSense-specific acquisition (filter.log, nginx.log) |
91+
| `/usr/local/etc/crowdsec/acquis.d/` | Drop new acquisition files here |
92+
| `/usr/local/etc/crowdsec/{parsers,scenarios,collections,...}/` | Hub-managed symlinks |
93+
| `/usr/local/etc/rc.conf.d/crowdsec` | Service flags (`crowdsec_machine_name`) |
94+
| `/usr/local/etc/rc.conf.d/crowdsec_firewall` | Service flags (`crowdsec_firewall_name`) |
95+
| `/var/db/crowdsec/data/` | SQLite DB, GeoIP tables — **must be on persistent disk** |
96+
| `/var/log/crowdsec/crowdsec.log` | Engine log (also visible in pfSense UI) |
97+
| `/var/log/crowdsec/crowdsec_api.log` | LAPI log |
98+
| `/var/log/crowdsec/crowdsec-firewall-bouncer.log` | Bouncer log |
99+
100+
## Service management
101+
102+
```sh
103+
service crowdsec start|stop|restart|status
104+
service crowdsec_firewall start|stop|restart|status
105+
```
106+
107+
The `.sh` suffix form (`service crowdsec.sh`) also works for `start/stop/restart` but **does
108+
not support `status`**. Always use the form without `.sh` to check running state.
109+
110+
pfSense GUI equivalent: `Status` → `Services`.
111+
112+
## Acquisition notes
113+
114+
`acquis.d/pfsense.yaml` is created by the package. It reads `/var/log/filter.log` and
115+
`/var/log/nginx.log` with `labels.type: syslog`, plus two important options:
116+
117+
```yaml
118+
poll_without_inotify: true # required when log sources are symlinks
119+
force_inotify: true # watches for directory/file creation (critical if /var is in RAM)
120+
```
121+
122+
`cscli metrics show acquisition` will show high "unparsed" rate for `/var/log/filter.log`.
123+
**This is normal**: CrowdSec only parses pf entries that match its scenarios (port scans, etc.).
124+
The majority of firewall log entries are intentionally not processed.
125+
126+
To add new log sources, create files in `/usr/local/etc/crowdsec/acquis.d/` and reload:
127+
128+
```sh
129+
service crowdsec reload
130+
```
131+
132+
## Default collections installed (Large mode)
133+
134+
After GUI save, `cscli hub list` shows (among others):
135+
136+
- `crowdsecurity/pfsense` — pfSense core collection (pf-logs, pfsense-gui, sshd, freebsd)
137+
- `crowdsecurity/pfsense-gui` — pfSense admin UI brute-force detection
138+
- `firewallservices/pf` — pf port-scan detection
139+
- `crowdsecurity/sshd` — SSH brute-force
140+
- `crowdsecurity/nginx` — nginx log parsing (for pfSense's nginx reverse proxy)
141+
- `crowdsecurity/base-http-scenarios`, `crowdsecurity/http-cve` — HTTP attack patterns
142+
- `crowdsecurity/whitelist-good-actors` — CDN, search engine whitelists
143+
144+
## UI page map
145+
146+
| Quickstart reference | Actual pfSense menu path |
147+
|---|---|
148+
| `Services/CrowdSec` | `Services` → `CrowdSec` (config / Save) |
149+
| `Status/CrowdSec` | `Status` → `CrowdSec Status` (read-only status, decision revocation) |
150+
| `Diagnostics/CrowdSec Metrics` | `Diagnostics` → `CrowdSec Metrics` |
151+
| `Status/System Logs/Packages/crowdsec` | `Status` → `System Logs` → `Packages` → `crowdsec` |
152+
| `Status/Services` | `Status` → `Services` (service start/stop/restart) |
153+
| `Diagnostics/Tables` | `Diagnostics` → `Tables` (view pfctl blacklist tables) |
154+
| `Diagnostics/Command Prompt` | `Diagnostics` → `Command Prompt` |
155+
156+
## Known gotchas
157+
158+
**Services don't auto-start after `sh install-crowdsec.sh`**: you must open the GUI and click
159+
Save. There is no documented CLI shortcut; the activation is done via the PHP resync hook.
160+
161+
**RAM disk**: if `System` → `Advanced` → `Misc` → `Use RAM disks` is enabled, Local API
162+
cannot be used (the database in `/var/db` would be lost on reboot). Disable RAM disk or use
163+
a remote LAPI (Medium/Small setup).
164+
165+
**Confusing post-install messages**: the `crowdsec` and `crowdsec-firewall-bouncer` packages
166+
print standard FreeBSD install instructions (service enable/start, pf.conf changes) during
167+
installation. These can be ignored — the pfSense plugin handles all of this.
168+
169+
**`service crowdsec.sh status` shows usage message**: only `start/stop/restart` are supported
170+
in the `.sh` form. Use `service crowdsec status` to check running state.
171+
172+
**Private IP whitelist**: since CrowdSec 1.6.3, `crowdsecurity/whitelists` is installed by
173+
default and prevents local bans on private IP ranges. To remove:
174+
```sh
175+
cscli parsers remove crowdsecurity/whitelists
176+
```
177+
178+
## Health check
179+
180+
```sh
181+
cscli version # v1.7.x-...
182+
cscli lapi status # LAPI reachable
183+
cscli capi status # CAPI connected, sharing enabled
184+
cscli bouncers list # pfsense-firewall ✔️, last pull recent
185+
cscli machines list # pfsense ✔️, recent heartbeat
186+
cscli metrics show acquisition # filter.log + auth.log being read
187+
cscli decisions list # active bans (empty is normal on fresh install)
188+
pfctl -T show -t crowdsec_blacklists # IPv4 blocked IPs
189+
```
190+
191+
## Quick uninstall (clean)
192+
193+
```sh
194+
pkg remove pfSense-pkg-crowdsec crowdsec crowdsec-firewall-bouncer
195+
rm -rf /usr/local/etc/crowdsec /usr/local/etc/rc.conf.d/crowdsec*
196+
rm -rf /var/db/crowdsec /var/log/crowdsec* /var/run/crowdsec*
197+
# optionally: remove <crowdsec> section from /conf/config.xml
198+
```

0 commit comments

Comments
 (0)