diff --git a/docs.json b/docs.json index 8fea64a..da9681e 100644 --- a/docs.json +++ b/docs.json @@ -97,6 +97,16 @@ "self-host/advanced/database-options", "self-host/advanced/integration-api" ] + }, + { + "group": "Community Guides", + "pages": [ + "self-host/community-guides/overview", + "self-host/community-guides/geoblock", + "self-host/community-guides/crowdsec", + "self-host/community-guides/metrics", + "self-host/community-guides/homeassistant" + ] } ] }, diff --git a/images/traefik_dashboard.png b/images/traefik_dashboard.png new file mode 100644 index 0000000..8a08ef2 Binary files /dev/null and b/images/traefik_dashboard.png differ diff --git a/self-host/community-guides/crowdsec.mdx b/self-host/community-guides/crowdsec.mdx new file mode 100644 index 0000000..903ee96 --- /dev/null +++ b/self-host/community-guides/crowdsec.mdx @@ -0,0 +1,205 @@ +--- +title: "CrowdSec" +--- + + +This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Lokowitz). + + +CrowdSec is a modern, open-source, collaborative behavior detection engine, integrated with a global IP reputation network. It functions as a massively multiplayer firewall, analyzing visitor behavior and responding appropriately to various types of attacks. + +## Installation + +Crowdsec can be installed using the Pangolin Installer. + +## Configuration + +By default, Crowdsec is installed with a basic configuration, which includes the [Crowdsec Bouncer Traefik plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin). + +### Choose the right logs + +#### Syslog + +For systems utilizing Syslog, the following volumes should be added to the `docker-compose.yml` file: + +```yaml +service: + crowdsec: + volumes: + - /var/log/auth.log:/var/log/auth.log:ro + - /var/log/syslog:/var/log/syslog:ro +``` + +Create a `syslog.yaml` file under `/config/crowdsec/acquis.d` with the following content: + +```yaml +filenames: + - /var/log/auth.log + - /var/log/syslog +labels: + type: syslog +``` + +#### Journalctl + +To log iptables to journalctl, execute the following command on your host system: + +```bash +iptables -A INPUT -j LOG --log-prefix "iptables: " +``` + +Update the `docker-compose.yml` file as follows: + +```yaml +service: + crowdsec: + image: crowdsecurity/crowdsec:latest-debian + environment: + COLLECTIONS: crowdsecurity/traefik crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules crowdsecurity/linux crowdsecurity/iptables + volumes: + - ./config/crowdsec:/etc/crowdsec + - ./config/crowdsec/db:/var/lib/crowdsec/data + - ./config/traefik/logs:/var/log/traefik:ro + - /var/log/journal:/var/log/host:ro +``` + +Create a `journalctl.yaml` file under `/config/crowdsec/acquis.d` with the following content: + +```yaml +source: journalctl +journalctl_filter: + - "--directory=/var/log/host/" +labels: + type: syslog +``` + +### Securing the Host System (SSH) + +By default, only Traefik requests are secured through the Crowdsec bouncer. To extend protection to your host system (e.g., SSH), follow these steps to add a firewall bouncer: + +1. Install the Crowdsec repositories. Refer to the [installation documentation](https://docs.crowdsec.net/docs/next/getting_started/install_crowdsec/#install-our-repositories): + +```bash +curl -s https://install.crowdsec.net | sudo sh +``` + +2. Install the firewall bouncer. For Debian/Ubuntu systems using IPTables, refer to the [documentation](https://docs.crowdsec.net/u/bouncers/firewall/): + +```bash +sudo apt install crowdsec-firewall-bouncer-iptables +``` + +3. Create an API key for the firewall bouncer to communicate with your CrowdSec Docker container. ("vps-firewall" is a placeholder name for the key): + +```bash +docker exec -it crowdsec cscli bouncers add vps-firewall +``` + +4. Copy the dispalyed API key and insert it into the bouncer's configuration file: + +```bash +nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml +``` + +5. Restart the firewall bouncer: + +```bash +systemctl restart crowdsec-firewall-bouncer +``` + +6. Update the `docker-compose.yml` file to expose communication port `8080` for the CrowdSec container and restart the container: + +```yaml +service: + crowdsec: + ports: + - 6060:6060 # Metrics port + - 8080:8080 # Local API port +``` + + +Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public. +Please see [complete warning about exposing ports](/Getting%20Started/dns-networking#ports-to-expose). + + +7. Verify communication between the firewall bouncer and the CrowdSec container by running: + +```bash +docker exec crowdsec cscli metrics +``` + +The output should look like this: + +```bash ++------------------------------------------------------------------+ +| Local API Bouncers Metrics | ++---------------------------+----------------------+--------+------+ +| Bouncer | Route | Method | Hits | ++---------------------------+----------------------+--------+------+ +| traefik-bouncer | /v1/decisions/stream | HEAD | 2 | +| traefik-bouncer@10.0.4.20 | /v1/decisions | GET | 3 | +| vps-firewall | /v1/decisions/stream | GET | 84 | <--------- ++---------------------------+----------------------+--------+------+ +``` + +## Custom Ban Page + +To display a custom ban page to attackers, follow these steps: + +1. Place a `ban.html` page in the `/config/traefik` directory. If you prefer not to create your own, you can download the official example: + +```bash +wget https://raw.githubusercontent.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/refs/heads/main/ban.html +``` + +2. Update the `/config/traefik/dynamic_config.yml` file to include the following: + +```yaml +http: + middlewares: + crowdsec: + plugin: + crowdsec: + banHTMLFilePath: /etc/traefik/ban.html +``` + +## Custom Captcha Page + +To use a custom captcha page, follow these steps: + +1. Place a `captcha.html` page in the `/config/traefik` directory. If you don't want to create your own, you can download the official example: + +```bash +wget https://raw.githubusercontent.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/refs/heads/main/captcha.html +``` + +2. Update the `/config/traefik/dynamic_config.yml` file with the following configuration, replacing `` with your captcha provider (MUST BE either `hcaptcha`, `recaptcha`, or `turnstile`), and `` with the appropriate site and secret keys: + +```yaml +http: + middlewares: + crowdsec: + plugin: + crowdsec: + captchaHTMLFilePath: /etc/traefik/captcha.html + captchaGracePeriodSeconds: 300 + captchaProvider: + captchaSiteKey: + captchaSecretKey: +``` + +## Testing + +You can test your configuration by adding a temporary ban or captcha for your IP. The ban will last for one minute. + +To add a ban: + +```bash +docker exec crowdsec cscli decisions add --ip -d 1m --type ban +``` + +To trigger a captcha challenge: + +```bash +docker exec crowdsec cscli decisions add --ip -d 1m --type captcha +``` diff --git a/self-host/community-guides/geoblock.mdx b/self-host/community-guides/geoblock.mdx new file mode 100644 index 0000000..e4f222c --- /dev/null +++ b/self-host/community-guides/geoblock.mdx @@ -0,0 +1,69 @@ +--- +title: "GeoBlock" +--- + + +This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Lokowitz). + + +GeoBlock is a Traefik middleware that uses IP-based geolocation to allow or block traffic from specific countries. It helps enhance security and access control by restricting unwanted or potentially harmful connections based on geographic regions. + +## Installation + +To integrate GeoBlock into your Traefik setup, follow the steps below: + +1. Add the following configuration to your `/config/traefik/traefik_config.yml` file: + +```yaml +entryPoints: + websecure: + http: + middlewares: + - geoblock@file + +experimental: + plugins: + geoblock: + moduleName: github.com/PascalMinder/geoblock + version: v0.3.2 +``` + +2. Add the following configuration to your `/config/traefik/dynamic_config.yml` file. Setting `blackListMode: false` enables GeoBlock in whitelist mode, allowing only the specified countries. Remember to add the appropriate countries when traveling. A list of country codes can be found in the [documentation](https://github.com/PascalMinder/geoblock#full-plugin-sample-configuration). + +```yaml +http: + middlewares: + geoblock: + plugin: + geoblock: + silentStartUp: false + allowLocalRequests: true + logLocalRequests: false # change to true to see logs and verify if it is working + logAllowedRequests: false # change to true to see logs and verify if it is working + logApiRequests: false # change to true to see logs and verify if it is working + api: "https://get.geojs.io/v1/ip/country/{ip}" + apiTimeoutMs: 500 + cacheSize: 25 + forceMonthlyUpdate: true + allowUnknownCountries: false + unknownCountryApiResponse: "nil" + blackListMode: false + countries: + - DE # add/replace with your country code +``` + +3. Restart Traefik to apply the changes: + +```bash +docker restart traefik +``` + +## Testing + +To monitor GeoBlock activities in the Traefik logs, enable logging by setting the following options to `true`: + +```yaml +logLocalRequests: true +logAllowedRequests: true +logApiRequests: true +``` diff --git a/self-host/community-guides/homeassistant.mdx b/self-host/community-guides/homeassistant.mdx new file mode 100644 index 0000000..10bc774 --- /dev/null +++ b/self-host/community-guides/homeassistant.mdx @@ -0,0 +1,142 @@ +--- +title: "Home Assistant Add-on" +--- + + +This is a community add-on and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Ferdinand99/home-assistant-newt-addon). + + +This Home Assistant add-on allows you to easily run **Newt** directly in Home Assistant. The add-on lets you configure **PANGOLIN_ENDPOINT**, **NEWT_ID**, and **NEWT_SECRET** via the Home Assistant interface. + +## Features + +- Easy installation via Home Assistant Add-on Store +- Automated setup and execution of the Newt container +- Supports `amd64`, `armv7`, `armhf`, and `aarch64` architectures +- Automatic restart on crash + +## Installation + +### **1. Add the GitHub Repository as an Add-on Source** + +- Go to **Settings → Add-ons → Add-on Store**. +- Click the menu (three dots in the top right) and select **Repositories**. +- Add the following URL: + ``` + https://github.com/Ferdinand99/home-assistant-newt-addon + ``` + or + ``` + https://git.opland.net/Ferdinand99/home-assistant-newt-addon/ + ``` + +1. Click **Add** and wait for the repository to load. + +### **2. Install and Start the Add-on** + +1. Find **Newt Add-on** in the list and click **Install**. +2. Go to the **Configuration** tab and enter your values for: + - **PANGOLIN_ENDPOINT** (e.g., `https://example.com`) + - **NEWT_ID** + - **NEWT_SECRET** +3. Click **Save** and then **Start**. +4. Check the **Logs** tab to verify that everything is running correctly. + +## **Configuration** + +After installation, you can configure the add-on via the Home Assistant UI: + +```yaml +PANGOLIN_ENDPOINT: "https://example.com" +NEWT_ID: "your_newt_id" +NEWT_SECRET: "your_newt_secret" +``` + +### **Docker Environment Variables** + +The following environment variables are passed to the `Newt` container: + +- `PANGOLIN_ENDPOINT` +- `NEWT_ID` +- `NEWT_SECRET` + +## Exposing Home Assistant through addon +1. Connect addon to your Pangolin by completing environment variables and starting the addon +2. In Pangolin create new HTTP resource for your new Tunnel with subdomain +3. Within the created Resource add new Target Configuration + +| Method | IP / Hostname | Port | +| --- | ----------- | --- | +| HTTP | 127.0.0.1 | 8123 | + +4. In Home Assistant's `configuration.yaml` add these two sections: +```yaml +http: + use_x_forwarded_for: true + trusted_proxies: + - 127.0.0.1 +homeassistant: + allowlist_external_urls: + - "https://.example.com" # <-- Replace with URL of created resource in Pangolin +``` + +4.5: If you wan't to use SSO Authentication in Pangolin you need to set up the `configuration.yaml` like this: +``` +http: +cors_allowed_origins: +- https://google.com +- https://www.home-assistant.io +ip_ban_enabled: true +login_attempts_threshold: 2 +use_x_forwarded_for: true +trusted_proxies: +- 127.0.0.1 +- Local IP of your NEWT instance +- VPS IP +``` + +You also need to set up `Resource rules` in the pangolin dashboard. [See rule overview here](../03-Pangolin/05-bypass-rules.md). + +Many thanks to steuerlexi for finding this out! + +https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897 + + +Please see [http](https://www.home-assistant.io/integrations/http/) documentation and [allowlist_external_urls](https://www.home-assistant.io/integrations/homeassistant/#external_url) on Home Assistant site. + + +5. Restart Home Assistant and your new Pangolin Proxy should be alive + +## Troubleshooting + +#### **Add-on does not start?** + +- Check the logs in Home Assistant (`Settings → Add-ons → Newt → Logs`). +- Ensure that `PANGOLIN_ENDPOINT`, `NEWT_ID`, and `NEWT_SECRET` are set correctly. + +#### **Changes in configuration do not take effect?** + +- Restart the add-on after making changes. +- Try removing the container manually: + + ```shell + docker stop newt + docker rm newt + ``` + +- Then start the add-on again. + +#### **Docker not available?** + +- Home Assistant OS manages Docker automatically, but check if the system has access to Docker by running: + ```shell + docker info + ``` + +If this fails, there may be a restriction in Home Assistant OS. + +## Useful Links + +- [HA addon repo](https://github.com/Ferdinand99/home-assistant-newt-addon) +- [Home Assistant](https://www.home-assistant.io/) +- [Docker Docs](https://docs.docker.com/) diff --git a/self-host/community-guides/metrics.mdx b/self-host/community-guides/metrics.mdx new file mode 100644 index 0000000..5037b6a --- /dev/null +++ b/self-host/community-guides/metrics.mdx @@ -0,0 +1,200 @@ +--- +title: "Metrics" +--- + + +This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Lokowitz). + + +This is a basic example of collecting metrics from Traefik and CrowdSec using Prometheus and visualizing them with Grafana dashboards. + + +Important for users with low-powered server (1GB RAM): +This setup will increase the use of your server RAM. + + +## Configuration + +### Traefik + +For claiming metrics from Traefik we have to adjust some configuration files. + +1. Udpate the `docker-compose.yml` file of the Pangolin stack to expose metrics port `8082` for the Prometheus connection: + +```yaml +service: + gerbil: + ports: + - 8082:8082 +``` + + +Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in `docker-compose` file. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public. +Please see [complete warning about exposing ports](/Getting%20Started/dns-networking#ports-to-expose). + + +2. Update the `/config/traefik/traefik_config.yml` file to include the following: + +```yaml +entryPoints: + metrics: + address: ":8082" + +metrics: + prometheus: + buckets: + - 0.1 + - 0.3 + - 1.2 + - 5.0 + entryPoint: metrics + addEntryPointsLabels: true + addRoutersLabels: true + addServicesLabels: true +``` + +3. Restart the Gerbil and Traefik container to apply the changes: + +```bash +sudo docker restart traefik gerbil +``` + +### Crowdsec + +For claiming metrics from Crowdsec we have to adjust the docker compose files. + +1. Udpate the `docker-compose.yml` file of the Pangolin stack to expose metrics port `6060` for the Prometheus connection: + +```yaml +service: + crowdsec: + ports: + - 6060:6060 +``` + + +Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public. +Please see [complete warning about exposing ports](/Getting%20Started/dns-networking#ports-to-expose). + + + +2. Restart the Crowdsec container to apply the changes: + +```bash +sudo docker restart crowdsec +``` + +## Prometheus + +1. Create a new Prometheus container or add it to `docker-compose.yml` of Pangolin stack: + +```yaml +services: + prometheus: + container_name: prometheus + image: prom/prometheus:latest + restart: unless-stopped + ports: + - 9090:9090 + volumes: + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + - ./config/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml + - ./config/prometheus/data:/prometheus +``` + + +Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public. +Please see [complete warning about exposing ports](/Getting%20Started/dns-networking#ports-to-expose). + + + +2. Create a `prometheus.yml` file in the `/config/prometheus` directory with the following content: + +```yaml +global: + scrape_interval: 15s + evaluation_interval: 15s + +scrape_configs: + - job_name: "prometheus" + static_configs: + - targets: ["localhost:9090"] + + - job_name: traefik + static_configs: + - targets: ["172.17.0.1:8082"] + + - job_name: crowdsec + static_configs: + - targets: ["172.17.0.1:6060"] +``` + +3. Create a folder `data` in `/config/prometheus` and change the ower and owning group: + +```bash +chown nobody:nogroup data +``` + +4. Start the Prometheus container: + +```bash +sudo docker conpose up -d +``` + +## Grafana + +1. Create a new Grafana container or add it to `docker-compose.yml` of Pangolin stack: + +```yaml +services: + grafana: + image: grafana/grafana:latest + container_name: grafana + restart: unless-stopped + ports: + - 3000:3000 + volumes: + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + - ./config/grafana/data:/var/lib/grafana +``` + + +Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public. +Please see [complete warning about exposing ports](/Getting%20Started/dns-networking#ports-to-expose). + + +2. Start the Grafana container: + +```bash +sudo docker compose up -d +``` + + +Default login credentials for Grafana admin user is admin:admin. + + +### Add Prometheus Connection + +Add the Prometheus connection under Connections -> Add new connection. + +Set `http://172.17.0.1:9090` as `Prometheus Server URL` and click `Save & test`. + +### Add Dashboard + +Add a Dashboard under Dashboard -> New -> Import and import a pre configured Dashboard or create your own. + +#### Traefik + + +Traefik Dashboard + + +Template Import ID = 17346 + +https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/ + +#### Crowdsec + +https://github.com/crowdsecurity/grafana-dashboards/tree/master diff --git a/self-host/community-guides/overview.mdx b/self-host/community-guides/overview.mdx new file mode 100644 index 0000000..4b740c4 --- /dev/null +++ b/self-host/community-guides/overview.mdx @@ -0,0 +1,55 @@ +--- +title: "Overview" +--- + + +These are community written guides and are not officially supported. If you have any issues, please reach out to the authors or the community on [Discord](https://discord.gg/HCJR8Xhme4) or [Github discussions](https://github.com/orgs/fosrl/discussions). + + +The modular design of this system enables the extension of its functionality through the integration of existing Traefik plugins, such as Crowdsec and Geoblock. +Additionally, Prometheus can collect metrics from both CrowdSec and Traefik, which can then be visualized in Grafana to monitor security events, request statistics, and traffic patterns in real time. + +## Traefik plugins + +For a complete list of available plugins, please refer to the [Plugin Catalog](https://plugins.traefik.io/plugins). + +### Crowdsec Bouncer + +When installing Crowdsec via the Pangolin installer, the Crowdsec Traefik Bouncer will be automatically installed and configured by default. The configuration can be customized to meet your specific requirements. + +The CrowdSec Bouncer plugin for Traefik integrates CrowdSec’s security engine to block malicious traffic in real time. It runs as middleware within a Traefik container and enforces decisions based on CrowdSec’s threat intelligence. This helps protect services from bots, attackers, and abusive IPs dynamically. + +For additional information, consult the following resources: + +- [Traefik Plugin Catalog](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin) +- [Github Repository](https://github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin) + +### Geoblock + +The GeoBlock plugin for Traefik is a middleware that restricts access based on the client’s geographic location. It runs within a Traefik container and uses IP-based geolocation to allow or block traffic from specific countries. This is useful for security, compliance, or access control in Traefik-managed services. + +For more details, please refer to the following resources: + +- [Github Repository](https://github.com/PascalMinder/geoblock) + +## Metrics + +Currently you can claim metric data from Traefik and Crowdsec with Prometheus and visiulize it within a Grafana Dashboard. + +### Prometheus + +Prometheus is an open-source monitoring and alerting toolkit designed for collecting and querying time-series metrics. It runs as a Docker container and uses a pull-based model to scrape data from configured endpoints. Prometheus integrates well with Grafana for visualization and Alertmanager for alert handling. + +For more details, please refer to the following resources: + +- [Homepage](https://prometheus.io/) +- [Github Repository](https://github.com/prometheus/prometheus) + +### Grafana + +Grafana is an open-source analytics and visualization platform used to monitor and display time-series data. It runs as a Docker container and supports multiple data sources, including Prometheus, InfluxDB, and MySQL. Grafana provides interactive dashboards, alerting, and extensive customization options for data visualization. + +For more details, please refer to the following resources: + +- [Homepage](https://grafana.com/) +- [Github Repository](https://github.com/grafana/grafana)