update opnsense/pfsense install docs (#598)

* update opnsense install * update pfsense install * Update opnsense.mdx * Update opnsense.mdx * Update pfsense.mdx * Update QuickStart.js * enhance: Some reason sidebar was bugged, fixed * Update install_opnsense.md * Update install_pfsense.md --------- Co-authored-by: Thibault "bui" Koechlin <[email protected]> Co-authored-by: Laurence Jones <[email protected]>
crowdsecurity · Jul 30, 2024 · 9d8e0aa · 9d8e0aa
1 parent cbd95ed
commit 9d8e0aa
Show file tree

Hide file tree

Showing 6 changed files with 101 additions and 76 deletions.
diff --git a/crowdsec-docs/docs/getting_started/install_opnsense.md b/crowdsec-docs/docs/getting_started/install_opnsense.md
@@ -4,45 +4,52 @@ title: OPNsense
 sidebar_position: 1
 ---
 
-## The OPNsense plugin
+# OPNsense plugin
 
-OPNsense, the widely known firewall and routing software, is based on FreeBSD. The standard packages that we provide for FreeBSD (agent+lapi and bouncer) can also run on OPNsense, but need more integration with the rest of the system (for example, to feed the firewall tables).
+The CrowdSec plugin for OPNsense is installed from the official repositories.
+It includes a Log Processor, LAPI service, and Remediation Component. This allows you
+to:
 
-By installing the `CrowdSec` plugin, available through the OPNsense repositories, you can:
-
- - use the OPNsense server as LAPI for other agents and bouncers
- - deploy an agent on OPNsense and scan its logs for attacks
- - block attackers from your whole network with a single firewall bouncer
+ - block attacking traffic from entering the network (protect machines that don't have CrowdSec)
+ - deploy a log processor on OPNsense and scan its logs for attacks
+ - use the OPNsense server as LAPI for other log processors and remediation components
  - list the hub plugins (parsers, scenarios..) and decisions on the OPNsense admin interface
 
-### Plugin installation
+## Plugin installation
 
-:::caution
-With OPNsense 22.1, if you are using a RAM filesystem for `/var` (you can verify `System > Settings > Miscellaneous > Disk/Memory Settings`) you need to disable it before proceeding, because the `Security Engine` keeps a small persistent database in `/var/db`. When the `/var` directory is in RAM, the database is re-created from scratch at each reboot. The ram disk was changed to `/var/log` for 22.7, which does not interfere with the database.
-:::
+Click `System > Firmware > Plugins` menu. Select os-crowdsec. It will deploy three packages:
 
-With OPNsense 22.1:
+ - `os-crowdsec`, the plugin itself
+ - `crowdsec`
+ - `crowdsec-firewall-bouncer`
 
-```console
-# pkg install os-crowdsec-devel
-```
+Do not enable/start the services from the terminal like you would on a standard freebsd system, because the plugin takes care of that.
 
-With OPNsense >= 22.7:
+Refresh the page and go to `Services > CrowdSec > Overview` to verify the running services and installed configurations.
 
-Download CrowdSec from the `System > Firmware > Plugins` menu. It will deploy three packages:
+Great, you now have CrowdSec installed on your system. Have a look at the [post installation steps](/getting_started/next_steps.md) to see how to to configure and optimize it,
+these recommendations are valid for any system.
 
- - `os-crowdsec`, the plugin itself
- - `crowdsec`
- - `crowdsec-firewall-bouncer`
 
-On the Settings tab, select the first three checkboxes: IDS, LAPI and IPS. Click Apply.
+## Plugin Configuration
 
-Do not enable/start the agent and bouncer services with `sysrc` or `/etc/rc.conf` like you would on a standard freebsd system, because the plugin takes care of that (in a different way).
+You will find some options under `Services > CrowdSec > Settings`. You will see the first three are enabled by default: Log Processor (previously known as IDS), LAPI and Remediation Component (previously known as IPS).
+You can disable them for testing or if you have special requirements.
 
 The parsers, scenarios and all objects from the [CrowdSec Hub](https://hub.crowdsec.net/) are periodically upgraded. The [crowdsecurity/freebsd](https://hub.crowdsec.net/author/crowdsecurity/collections/freebsd) and [crowdsecurity/opnsense](https://hub.crowdsec.net/author/crowdsecurity/collections/opnsense) collections are installed by default.
 
-### Testing the plugin
+Since crowdsec 1.6.3, private IP networks are whitelisted by default as well. This means for example an IP from a LAN or WAN which is on 192.168.x.y won't get blocked by a local decision
+(community blocklists don't contain private IPs).
+
+If you want to revert to the previous behavior, to block private IPs as well, you can remove the related parser.
+
+```console
+[root@OPNsense ~]# cscli parsers remove crowdsecurity/whitelists
+```
+
+If on the other hand you upgrade from a version before 1.6.3, you need to install the lists yourself.
 
+## Testing the remediation component
 
 A quick way to test that everything is working correctly is to execute the following command. Your ssh session should freeze and you should be kicked out from the firewall. You will not be able to connect to it (from the same IP address) for two minutes. It might be a good idea to have a secondary IP from which you can connect, should anything go wrong.
 
@@ -54,7 +61,7 @@ This is a more secure way to test than attempting to brute-force yourself: the d
 
 You can find a list of all available flags with `cscli decisions add --help`.
 
-#### How do I find my connecting IP address to test?
+### How do I find my connecting IP address to test?
 
 We have provided some examples below to help you find your connecting IP address. Depending on your shell / environment, you may need to use a different command. 
 
@@ -65,8 +72,7 @@ We have provided some examples below to help you find your connecting IP address
 
 ## Remote LAPI setup (optional)
 
-You may have a need to put the LAPI service on a different machine, possibly because you already have it, or opnsense is running on a slow machine or...
-well - your servers, your right to choose. But you'll have to manually tweak the configuration (thanks [Jarno Rankinen](https://github.com/0ranki)).
+If you don't want to run the LAPI service on the OPNsense machine (because it's small/slow or you already have LAPI somewhere) then you'll have to manually tweak the configuration (thanks [Jarno Rankinen](https://github.com/0ranki)).
 
 Be aware: the list of machines and bouncers shown in the Overview tab will be incorrect. In the current version, the crowdsec instance on OPNsense has no way (and no permission) to retrieve the list of machines and bouncers from the LAPI if it resides on another server, so it displays the local (and outdated) information.
 
@@ -122,8 +128,3 @@ For more information on the topic:
 
  - [Improve The CrowdSec Multi-Server Installation With HTTPS Between Agents](https://www.linuxjournal.com/content/improve-crowdsec-multi-server-installation-https-between-agents) (Linux Journal)
 
-## Enrolling your instance
-
-The next step is to enroll your instance with the [CrowdSec Console](https://app.crowdsec.net/security-engines?enroll-engine=true).
-
-For the benefits, please visit the [Console section](/u/console/intro).
diff --git a/crowdsec-docs/docs/getting_started/install_pfsense.md b/crowdsec-docs/docs/getting_started/install_pfsense.md
@@ -3,14 +3,13 @@ id: install_crowdsec_pfsense
 title: pfSense
 ---
 
-We have created a [pfSense package](https://docs.netgate.com/pfsense/en/latest/packages/list.html) with
-a simple UI to configure the Security Engine and the Firewall Remediation Component (bouncer).
+The CrowdSec package for pfSense requires some manual installation steps, as it is not yet available in the official repositories.
 
 Three types of setup are supported:
 
-**Small** (remediation only) - the pfSense machine receives blocklists from a CrowdSec
+**Small** (remediation only) - the pfSense machine receives blocklists from a
 Security Engine that you are running on a different machine.
-Incoming connections are blocked at the firewall by (configurable) pfSense rules.
+Attacking traffic is blocked at the firewall by (configurable) pfSense rules.
 
 **Medium** (small+log processor) - in addition to enforcing blocklists, the pfSense
 machine can detect attacks directed at the firewall itself, for example port scans.
@@ -27,17 +26,13 @@ values to enable remediation, log processor and Local API.
 
 :::info
 The CrowdSec configuration is not transferred when you restore a pfSense backup, and you'll need
-to reconfigure it or backup separately.
+to reconfigure it or backup separately. Major pfSense upgrades may also require you to re-install
+or re-configure CrowdSec so please verify that it's running afterwards. We have submitted the package
+for inclusion in the official repository which should smooth out these issues.
 :::
 
 ## Installing the package
 
-We have submitted the package to the pfSense developers for review and inclusion in the official repositories.
-
-If you find `crowdsec` under `System/Package Manager`, we recommend you to install it from there.
-
-If the package is not available yet, you'll have to install it manually.
-
  * Choose [the release you want to install](https://github.com/crowdsecurity/pfSense-pkg-crowdsec/releases),
    click `Assets` for the list of packages to install.
 
@@ -53,6 +48,10 @@ If the package is not available yet, you'll have to install it manually.
 # pkg add -f <link to pfSense-pkg-crowdsec>
 ```
 
+The direct links are for the most popular Community Edition of pfSense, architecture amd64. If you run on ARM or a different base version 
+of FreeBSD, you will find .tar files in the release assets containing the packages for the possible platforms.
+
+
 ## Configuration
 
 Once the package and its dependencies are installed, go to `Service/CrowdSec`. The options *Remediation Component*,
@@ -61,7 +60,7 @@ Once the package and its dependencies are installed, go to `Service/CrowdSec`. T
 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.
 
 CrowdSec on pfSense is fully functional from the command line but the web interface is read-only, with the exception of decision revocation (unban).
-Most actions require the shell or the [CrowdSec Console](https://app.crowdsec.net).
+Most other actions require the shell or the [CrowdSec Console](https://app.crowdsec.net).
 For simple things, `Diagnostics/Command Prompt` works as well as ssh.
 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.
 
@@ -81,7 +80,8 @@ In the page `Status/CrowdSec` you can see
  - installed hub items (collections, scenarios, parsers, postoverflows)
  - alerts and local decisions
 
-All tables are read-only with an exception: you can delete single decisions, to unban an IP for example.
+All tables are read-only with an exception: you can delete decisions one by one, to unban an IP for example.
+An IP may have been banned for several reasons, which counts as separate decisions.
 
 All hub objects are periodically upgraded with a cron job.
 
@@ -181,9 +181,17 @@ If you need more CrowdSec tests you may want to temporarily disable Login Protec
 
 ## LAN / private networks whitelist
 
-By default the FreeBSD version of CrowdSec does not install any whitelist.
-If you trust your `10.0.0.0/8`, `192.168.0.0/16` and `172.16.0.0/12`
-networks, you can use `cscli parsers install crowdsecurity/whitelists` to whitelist them.
+Since crowdsec 1.6.3, private IP networks are whitelisted by default as well. This means for example an IP from a LAN or WAN which is on 192.168.x.y won't get blocked by a local decision
+(community blocklists don't contain private IPs).
+
+If you want to revert to the previous behavior, to block private IPs as well, you can remove the related parser.
+
+```console
+[root@OPNsense ~]# cscli parsers remove crowdsecurity/whitelists
+```
+
+If on the other hand you upgrade from a version before 1.6.3, you need to install the lists yourself.
+
 
 ## Uninstalling
 
@@ -203,17 +211,3 @@ If you need to make sure you removed all traces of CrowdSec, you can run the fol
 For testing purposes, you may want to remove the &lt;crowdsec&gt; section
 from `/conf/config.xml` as well.
 
-
-## The blocklist mirror
-
-Before releasing the official package, one way to integrate pfSense and CrowdSec
-was to install a blocklist mirror and connect it to pfBlockerNG. While this is still
-a viable solution, it has slower performance than the method described above,
-especially in terms of latency when receiving decision updates.
-It also required pfBlockerNG in addition to CrowdSec.
-
-## Enrolling your instance
-
-The next step is to enroll your instance with the [CrowdSec Console](https://app.crowdsec.net/security-engines?enroll-engine=true).
-
-For the benefits, please visit the [Console section](/u/console/intro).
diff --git a/crowdsec-docs/sidebarsUnversioned.js b/crowdsec-docs/sidebarsUnversioned.js
@@ -429,8 +429,8 @@ module.exports = {
                 "getting_started/installation/macos",
                 "getting_started/installation/docker",
                 "getting_started/installation/kubernetes",
-                // "getting_started/installation/pfsense",
-                // "getting_started/installation/opnsense",
+                "getting_started/installation/pfsense",
+                "getting_started/installation/opnsense",
                 "getting_started/installation/whm",
             ],
         },

diff --git a/crowdsec-docs/src/components/QuickStart.js b/crowdsec-docs/src/components/QuickStart.js
@@ -43,16 +43,16 @@ const staticData = [
         text: "Kubernetes",
         link: "/u/getting_started/installation/kubernetes",
     },
-    // {
-    //     icon: opnsenseLogo,
-    //     text: "OPNsense",
-    //     link: "/u/getting_started/installation/opnsense",
-    // },
-    // {
-    //     icon: pfSenseLogo,
-    //     text: "pfSense",
-    //     link: "/u/getting_started/installation/pfsense",
-    // },
+    {
+        icon: opnsenseLogo,
+        text: "OPNsense",
+        link: "/u/getting_started/installation/opnsense",
+    },
+    {
+        icon: pfSenseLogo,
+        text: "pfSense",
+        link: "/u/getting_started/installation/pfsense",
+    },
     {
         icon: whmLogo,
         text: "WHM",

diff --git a/crowdsec-docs/unversioned/getting_started/installation/opnsense.mdx b/crowdsec-docs/unversioned/getting_started/installation/opnsense.mdx
@@ -5,4 +5,29 @@ pagination_prev: getting_started/pre_requisites
 pagination_next: getting_started/next_steps
 ---
 
-## TODO BY @MMETC
+# OPNsense plugin
+
+The CrowdSec plugin for OPNsense is installed from the official repositories.
+It includes a Log Processor, LAPI service, and Remediation Component. This allows you
+to:
+
+ - block attacking traffic from entering the network (protect machines that don't have CrowdSec)
+ - deploy a log processor on OPNsense and scan its logs for attacks
+ - use the OPNsense server as LAPI for other log processors and remediation components
+ - list the hub plugins (parsers, scenarios..) and decisions on the OPNsense admin interface
+
+## Plugin installation
+
+Click `System > Firmware > Plugins` menu. Select os-crowdsec. It will deploy three packages:
+
+ - `os-crowdsec`, the plugin itself
+ - `crowdsec`
+ - `crowdsec-firewall-bouncer`
+
+Do not enable/start the services from the terminal like you would on a standard freebsd system, because the plugin takes care of that.
+
+Refresh the page and go to `Services > CrowdSec > Overview` to verify the running services and installed configurations.
+
+## Next Steps?
+
+Great, you now have CrowdSec installed on your system. Have a look at the [post installation steps](/getting_started/next_steps.md) to see how to to configure and optimize it, or keep reading [the rest of the plugin documentation](/docs/next/getting_started/install_crowdsec_opnsense)
diff --git a/crowdsec-docs/unversioned/getting_started/installation/pfsense.mdx b/crowdsec-docs/unversioned/getting_started/installation/pfsense.mdx
@@ -1,8 +1,13 @@
 ---
 id: pfsense
-title: PFsense
+title: pfSense
 pagination_prev: getting_started/pre_requisites
 pagination_next: getting_started/next_steps
 ---
 
-## TODO BY @MMETC
+# pfSense package
+
+The CrowdSec package for pfSense is not installed from the official repositories, at least not yet.
+
+Please refer to the [detailed documentation](/docs/next/getting_started/install_crowdsec_pfsense) to install or update it from a release archive.
+