Skip to content

Commit d35ce1d

Browse files
feat(*): Update pfsense doc with screenshots (#737)
1 parent 9203a76 commit d35ce1d

12 files changed

+68
-10
lines changed

crowdsec-docs/docs/getting_started/install_pfsense.md

Lines changed: 68 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,23 @@ for inclusion in the official repository which should smooth out these issues.
3333

3434
## Installing the package
3535

36-
* Choose [the release you want to install](https://github.com/crowdsecurity/pfSense-pkg-crowdsec/releases),
37-
click `Assets` for the list of packages to install.
36+
* Choose [the release you want to install](https://github.com/crowdsecurity/pfSense-pkg-crowdsec/releases)
3837

39-
* Open an ssh connection to your pfSense box and run the following commands in the right order. Do not activate or run the services,
40-
because pfSense will take care of it.
38+
* Open an ssh connection to your pfSense box
39+
40+
* Download the `install-crowdsec.sh` script:
41+
```console
42+
fetch https://raw.githubusercontent.com/crowdsecurity/pfSense-pkg-crowdsec/refs/heads/main/install-crowdsec.sh
43+
```
44+
* Run it:
45+
```console
46+
sh install-crowdsec.sh --release vx.y.z-X.Y.Z
47+
```
48+
49+
* Do not activate or run the services, because pfSense will take care of it.
50+
51+
52+
* Alternatively, you can download the packages to install in the `Assets` part of the release, and run the following commands in the right order.
4153

4254
```console
4355
# setenv IGNORE_OSVERSION yes
@@ -54,14 +66,26 @@ of FreeBSD, you will find .tar files in the release assets containing the packag
5466

5567
## Configuration
5668

57-
Once the package and its dependencies are installed, go to `Service/CrowdSec`. The options *Remediation Component*,
69+
Once the package and its dependencies are installed, go to `Services/CrowdSec`. The options *Remediation Component*,
5870
*Log Processor* and *Local API* should be enabled. Click Save.
5971

60-
With the size analogy, the default is a "Large", autonomous installation. For a "Medium", disable *Local API* and fill the fields in the *Remote LAPI* section. For a "Small", disable *Log Processor* too.
72+
![Config part 1](/img/pfsense/config-1.png)
73+
74+
With the size analogy, the default is a "Large", autonomous installation.
75+
76+
For a "Medium", disable *Local API* and fill the fields in the *Remote LAPI* section.
77+
78+
![Config part 2](/img/pfsense/config-2-remote.png)
79+
80+
For a "Small", disable *Log Processor* too.
6181

6282
CrowdSec on pfSense is fully functional from the command line but the web interface is read-only, with the exception of decision revocation (unban).
6383
Most other actions require the shell or the [CrowdSec Console](https://app.crowdsec.net).
6484
For simple things, `Diagnostics/Command Prompt` works as well as ssh.
85+
86+
![Command Prompt](/img/pfsense/command-prompt.png)
87+
88+
6589
You are free to edit the files in `/usr/local/etc/crowdsec`, although some setting may be overwritten by the pfSense package if they are mandatory.
6690

6791
:::caution
@@ -76,9 +100,20 @@ need to connect them to a remote CrowdSec instance.
76100

77101
In the page `Status/CrowdSec` you can see
78102

79-
- registered log processors and bouncers
103+
- registered log processors and remediation components
104+
105+
![Remediation components](/img/pfsense/status-remediation-components.png)
106+
107+
80108
- installed hub items (collections, scenarios, parsers, postoverflows)
109+
110+
![Hub collections](/img/pfsense/status-hub-collections.png)
111+
112+
81113
- alerts and local decisions
114+
115+
![Alerts](/img/pfsense/status-alerts.png)
116+
82117

83118
All tables are read-only with an exception: you can delete decisions one by one, to unban an IP for example.
84119
An IP may have been banned for several reasons, which counts as separate decisions.
@@ -123,8 +158,19 @@ Make sure to reload or restart CrowdSec when you add new data sources.
123158

124159
## Diagnostics
125160

126-
Under `Diagnostics/CrowdSec` you can check if the logs are acquired and the
127-
events are triggered correctly. For real monitoring, you can fetch the same metrics with
161+
Under `Diagnostics/CrowdSec Metrics` you can check if the logs are acquired and the
162+
events are triggered correctly.
163+
164+
165+
![Diagnostics acquisition](/img/pfsense/diagnostic-metrics-acquisition.png)
166+
167+
168+
169+
![Diagnostics local api](/img/pfsense/diagnostic-metrics-local-api.png)
170+
171+
172+
173+
For real monitoring, you can fetch the same metrics with
128174
[Prometheus](https://docs.crowdsec.net/docs/observability/prometheus/) (Grafana dashboard included)
129175
Telegraf or your favorite solution.
130176

@@ -135,18 +181,30 @@ If you are not running a LAPI or a Log Processor, some metrics are always empty.
135181

136182
You can see the Security Engine logs in `Status/System Logs/Packages/crowdsec`.
137183

184+
185+
![Logs](/img/pfsense/logs.png)
186+
138187
Other logs not shown in the UI are in `/var/log/crowdsec/crowdsec_api.log`
139188
and `crowdsec-firewall-bouncer.log`.
140189

141190

142191
## Service Management
143192

144193
Both services, Security Engine (crowdsec) and Remediation (crowdsec-firewall-bouncer) can be controlled from `Status/Services`.
194+
195+
![Services](/img/pfsense/status-services.png)
196+
197+
145198
The equivalent shell commands are `service crowdsec.sh start/stop/restart` and `service crowdsec_firewall.sh start/stop/restart`. Note the ending **.sh**!
146199

147200
## Viewing blocked IPs
148201

149-
You can see the tables of the blocked IPs in Diagnostics/Tables or from the shell, with the commands
202+
You can see the tables of the blocked IPs in `Diagnostics/Tables`
203+
204+
![Blocked IPs](/img/pfsense/blocked-ips.png)
205+
206+
207+
Or from the shell, with the commands
150208
`pfctl -T show -t crowdsec_blacklists` (IPv4) and `pfctl -T show -t crowdsec6_blacklists` (IPv6).
151209

152210
To show the same data with more context, use `cscli decisions list -a`.
66 KB
Loading
35.8 KB
Loading
135 KB
Loading
68.5 KB
Loading
46.5 KB
Loading
55.3 KB
Loading
155 KB
Loading
46.8 KB
Loading
108 KB
Loading

0 commit comments

Comments
 (0)