docs: add new Access Control and Logs documentation pages
- Documented Access Control features (e.g., Device Approvals, Password Rotation, 2FA, Custom Login Pages). - Added detailed descriptions for Logs & Analytics (Access Logs, Request Logs, Action Logs). - Included configuration instructions and feature-specific notes for Pangolin Cloud and Enterprise Edition. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
@@ -0,0 +1,226 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# CrowdSec
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
iptables -A INPUT -j LOG --log-prefix "iptables: "
|
||||
```
|
||||
|
||||
Update the `docker-compose.yml` file as follows:
|
||||
|
||||
```yaml theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
|
||||
```
|
||||
|
||||
5. Restart the firewall bouncer:
|
||||
|
||||
```bash theme={null}
|
||||
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 theme={null}
|
||||
service:
|
||||
crowdsec:
|
||||
ports:
|
||||
- 6060:6060 # Metrics port
|
||||
- 8080:8080 # Local API port
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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](/self-host/dns-and-networking).
|
||||
</Warning>
|
||||
|
||||
7. Verify communication between the firewall bouncer and the CrowdSec container by running:
|
||||
|
||||
```bash theme={null}
|
||||
docker exec crowdsec cscli metrics
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
||||
```bash theme={null}
|
||||
+------------------------------------------------------------------+
|
||||
| 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 theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
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 `<SERVICE>` with
|
||||
your captcha provider (MUST BE either `hcaptcha`, `recaptcha`, or `turnstile`), and `<KEY>` with the appropriate site
|
||||
and secret keys:
|
||||
|
||||
```yaml theme={null}
|
||||
http:
|
||||
middlewares:
|
||||
crowdsec:
|
||||
plugin:
|
||||
crowdsec:
|
||||
captchaHTMLFilePath: /etc/traefik/captcha.html
|
||||
captchaGracePeriodSeconds: 300
|
||||
captchaProvider: <SERVICE>
|
||||
captchaSiteKey: <KEY>
|
||||
captchaSecretKey: <KEY>
|
||||
```
|
||||
|
||||
## 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 theme={null}
|
||||
docker exec crowdsec cscli decisions add --ip <YOUR IP> -d 1m --type ban
|
||||
```
|
||||
|
||||
To trigger a captcha challenge:
|
||||
|
||||
```bash theme={null}
|
||||
docker exec crowdsec cscli decisions add --ip <YOUR IP> -d 1m --type captcha
|
||||
```
|
||||
|
||||
+148
@@ -0,0 +1,148 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# GeoLite2 Automation
|
||||
|
||||
> A simple automation to download & update your GeoLite2 databases with geoipupdate
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/txwgnd).
|
||||
</Note>
|
||||
|
||||
This automation lets your system automatically download & upgrade the `GeoLite2-Country` and `GeoLite2-ASN` databases
|
||||
from Maxmind to use for geoblocking and ASN blocking on your Pangolin host. It's utilizing Maxmind'
|
||||
s [geoipupdate](https://github.com/maxmind/geoipupdate/tree/main) Docker container to achieve this.
|
||||
|
||||
Maxmind's service is free of charge for development, personal or community
|
||||
use. [Quote](https://support.maxmind.com/knowledge-base/articles/create-a-maxmind-account#h_01G4G4NG5C63BQ6HRG6MSS50T3)
|
||||
|
||||
# Table of Contents
|
||||
|
||||
1. **[Requirements](#1-requirements)**
|
||||
2. **[Maxmind Account](#2-maxmind-account)**
|
||||
3. **[API key creation](#3-api-key-creation)**
|
||||
4. **[Modification of Pangolin's `docker-compose.yml`](#4-modification-of-pangolin’s-docker-compose-yml)**
|
||||
5. **[Modification of Pangolin's `config.yml`](#5-modification-of-pangolin’s-config-yml)**
|
||||
|
||||
## 1. Requirements
|
||||
|
||||
* A Maxmind account for API access
|
||||
* Pangolin version 1.11.0 or higher
|
||||
|
||||
## 2. Maxmind Account
|
||||
|
||||
To be able to use Maxmind's service you need to request access to the GeoLite2 databases and create an account on
|
||||
their [website](https://www.maxmind.com/en/geolite2/signup?utm_source=kb\&utm_medium=kb-link\&utm_campaign=kb-create-account).
|
||||
|
||||
After you successfully created an account visit the mainpage again and login to your new account.
|
||||
|
||||
## 3. API key creation
|
||||
|
||||
The next step is to create an API key for `geoipupdate`. You'll find an entry called `Manage license keys` in the menu
|
||||
on the left side. Head to this page and click on `Generate new license key`.
|
||||
|
||||
<Frame caption="Maxmind's Manage license keys page">
|
||||
<img src="https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=45cc57507e2f28814baceabeac81da9a" alt="Maxmind's Manage license keys page" data-og-width="2792" width="2792" data-og-height="1634" height="1634" data-path="images/maxmind_manage-license-keys.jpeg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?w=280&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=8180cc300150dfcb01c08083bf78524e 280w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?w=560&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=d82f7823cc52940ab01c187cb5011a43 560w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?w=840&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=3a837b0adaa483fe95b414f83765d72b 840w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?w=1100&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=bbbba78330b1c69004368cad6ada0ef3 1100w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?w=1650&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=301d34d12c0619bdb1de32a3cc4db17c 1650w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_manage-license-keys.jpeg?w=2500&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=48b6917e61cda0a1b7bb0de946983cb2 2500w" />
|
||||
</Frame>
|
||||
|
||||
Give your new key a name. E.g. `Pangolin`.
|
||||
|
||||
<Frame caption="Choose a name for the key">
|
||||
<img src="https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=0558ff4f3da32cc7622bb516b736e72a" alt="Maxmind's key creation page" data-og-width="2014" width="2014" data-og-height="624" height="624" data-path="images/maxmind_create-key-page.jpeg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?w=280&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=6e0a7d0eb4fb01c71b06deaf18c3cd24 280w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?w=560&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=413dac8ceb1247709542e95be4b5bbdb 560w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?w=840&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=dbbd65d58084dfc7151c21663fc041b2 840w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?w=1100&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=528a07b151c87eec1fee9a214f969116 1100w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?w=1650&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=df460bb545e889b4d92e2ce5fea26c64 1650w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_create-key-page.jpeg?w=2500&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=bec43d2ae69d890c3d61558294bcfdb3 2500w" />
|
||||
</Frame>
|
||||
|
||||
After your key got created the webpage will show you your Account ID as well as the API key. Save the key now because it
|
||||
can only be seen once. Don't panic if something goes wrong, you can easily create new keys.
|
||||
|
||||
<Frame caption="Key successfully created">
|
||||
<img src="https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=538be94f872890457482ecb8ec9289f1" alt="The key got created successfully" data-og-width="1960" width="1960" data-og-height="570" height="570" data-path="images/maxmind_key-created.jpeg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?w=280&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=c45add128f333755e926de48ba54eb50 280w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?w=560&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=0937bac3fecd007a211cd032b9dbda39 560w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?w=840&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=62c6d99d867cdcf78dccc840d5405642 840w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?w=1100&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=8426121d796b806c89453fe8fffee084 1100w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?w=1650&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=3601e6b1ce3c49eb7cccbfb84f93ed29 1650w, https://mintcdn.com/fossorial/WZ4OcypdChdYMxya/images/maxmind_key-created.jpeg?w=2500&fit=max&auto=format&n=WZ4OcypdChdYMxya&q=85&s=fa3446ea791ff59cb1758739a745e37b 2500w" />
|
||||
</Frame>
|
||||
|
||||
After you clicked on `Return to list` you should see an overview of your keys bundled with some metadata.
|
||||
|
||||
## 4. Modification of Pangolin's `docker-compose.yml`
|
||||
|
||||
Now login to your Pangolin host and navigate to `/pangolin` in your user directory:
|
||||
|
||||
```bash theme={null}
|
||||
cd pangolin
|
||||
```
|
||||
|
||||
Shut down Pangolin with:
|
||||
|
||||
```bash theme={null}
|
||||
docker compose down
|
||||
```
|
||||
|
||||
Open `docker-compose.yml` with your favorite text editor.
|
||||
E.g. nano:
|
||||
|
||||
```bash theme={null}
|
||||
nano docker-compose.yml
|
||||
```
|
||||
|
||||
Append this Docker compose service at the end of your stack and add your Account ID as well as your API key you created
|
||||
in the last step:
|
||||
|
||||
```yaml theme={null}
|
||||
services:
|
||||
(...)
|
||||
geoipupdate:
|
||||
container_name: geoipupdate
|
||||
image: ghcr.io/maxmind/geoipupdate
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- 'GEOIPUPDATE_ACCOUNT_ID=' # Account ID
|
||||
- 'GEOIPUPDATE_LICENSE_KEY=' # API key
|
||||
- 'GEOIPUPDATE_EDITION_IDS=GeoLite2-Country GeoLite2-ASN' # Which dbs should be downloaded
|
||||
- 'GEOIPUPDATE_FREQUENCY=72' # Update intervall in hours
|
||||
volumes:
|
||||
- './config/GeoLite2:/usr/share/GeoIP'
|
||||
```
|
||||
|
||||
#### Note
|
||||
|
||||
If you use the standard Pangolin deployment you shouldn't need to modify the path.
|
||||
This is the bare minimum to run the container. There are other optional environment variables available. Have a look at
|
||||
their [docs](https://dev.maxmind.com/geoip/updating-databases/?lang=en)!
|
||||
|
||||
Save and close the file, but don't restart the stack yet!
|
||||
|
||||
## 5. Modification of Pangolin's config.yml
|
||||
|
||||
Navigate to `/config` within the same folder and open it with a text editor.
|
||||
|
||||
```bash theme={null}
|
||||
cd config
|
||||
```
|
||||
|
||||
Add these lines to the `server` object
|
||||
|
||||
```yaml theme={null}
|
||||
server:
|
||||
maxmind_db_path: "./config/GeoLite2/GeoLite2-Country.mmdb"
|
||||
maxmind_asn_path: "./config/GeoLite2/GeoLite2-ASN.mmdb"
|
||||
```
|
||||
|
||||
These entries tell the Pangolin application where to find the databases.
|
||||
|
||||
Save and close the file then navigate to the `pangolin` folder one level higher.
|
||||
|
||||
Restart your Pangolin stack with:
|
||||
|
||||
```bash theme={null}
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Et voilà, you are now able to define country rules and ASN rules for your ressources! 🏁
|
||||
|
||||
btw: you can use these exact databases for your Traefik dashboard
|
||||
too -> [Community Guide](/self-host/community-guides/traefiklogsdashboard)
|
||||
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Home Assistant Add-on
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
http:
|
||||
use_x_forwarded_for: true
|
||||
trusted_proxies:
|
||||
- 127.0.0.1
|
||||
homeassistant:
|
||||
allowlist_external_urls:
|
||||
- "https://<subdomain>.example.com" # <-- Replace with URL of created resource in Pangolin
|
||||
```
|
||||
|
||||
4.5: If you want 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](/manage/access-control/rules).
|
||||
|
||||
Many thanks to steuerlexi for finding this out!
|
||||
|
||||
[https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897](https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897)
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
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/)
|
||||
|
||||
@@ -0,0 +1,210 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Metrics
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
This is a basic example of collecting metrics from Traefik and CrowdSec using Prometheus and visualizing them with
|
||||
Grafana dashboards.
|
||||
|
||||
<Warning>
|
||||
Important for users with low-powered server (1GB RAM):
|
||||
This setup will increase the use of your server RAM.
|
||||
</Warning>
|
||||
|
||||
## Configuration
|
||||
|
||||
### Traefik
|
||||
|
||||
For claiming metrics from Traefik we have to adjust some configuration files.
|
||||
|
||||
1. Update the `docker-compose.yml` file of the Pangolin stack to expose metrics port `8082` for the Prometheus
|
||||
connection:
|
||||
|
||||
```yaml theme={null}
|
||||
service:
|
||||
gerbil:
|
||||
ports:
|
||||
- 8082:8082
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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](/self-host/dns-and-networking).
|
||||
</Warning>
|
||||
|
||||
2. Update the `/config/traefik/traefik_config.yml` file to include the following:
|
||||
|
||||
```yaml theme={null}
|
||||
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 theme={null}
|
||||
sudo docker restart traefik gerbil
|
||||
```
|
||||
|
||||
### Crowdsec
|
||||
|
||||
For claiming metrics from Crowdsec we have to adjust the docker compose files.
|
||||
|
||||
1. Update the `docker-compose.yml` file of the Pangolin stack to expose metrics port `6060` for the Prometheus
|
||||
connection:
|
||||
|
||||
```yaml theme={null}
|
||||
service:
|
||||
crowdsec:
|
||||
ports:
|
||||
- 6060:6060
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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](/self-host/dns-and-networking).
|
||||
</Warning>
|
||||
|
||||
2. Restart the Crowdsec container to apply the changes:
|
||||
|
||||
```bash theme={null}
|
||||
sudo docker restart crowdsec
|
||||
```
|
||||
|
||||
## Prometheus
|
||||
|
||||
1. Create a new Prometheus container or add it to `docker-compose.yml` of Pangolin stack:
|
||||
|
||||
```yaml theme={null}
|
||||
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
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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](/self-host/dns-and-networking).
|
||||
</Warning>
|
||||
|
||||
2. Create a `prometheus.yml` file in the `/config/prometheus` directory with the following content:
|
||||
|
||||
```yaml theme={null}
|
||||
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 owner and owning group:
|
||||
|
||||
```bash theme={null}
|
||||
chown nobody:nogroup data
|
||||
```
|
||||
|
||||
4. Start the Prometheus container:
|
||||
|
||||
```bash theme={null}
|
||||
sudo docker compose up -d
|
||||
```
|
||||
|
||||
## Grafana
|
||||
|
||||
1. Create a new Grafana container or add it to `docker-compose.yml` of Pangolin stack:
|
||||
|
||||
```yaml theme={null}
|
||||
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
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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](/self-host/dns-and-networking).
|
||||
</Warning>
|
||||
|
||||
2. Start the Grafana container:
|
||||
|
||||
```bash theme={null}
|
||||
sudo docker compose up -d
|
||||
```
|
||||
|
||||
<Note>
|
||||
Default login credentials for Grafana admin user is admin:admin.
|
||||
</Note>
|
||||
|
||||
### 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
|
||||
|
||||
<Frame caption="Traefik Dashboard">
|
||||
<img src="https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=6afb4e81847fffc7aaf6c45686826528" alt="Traefik Dashboard" data-og-width="1842" width="1842" data-og-height="770" height="770" data-path="images/traefik_dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?w=280&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=bb9b62a17b2b7e7889158bd2795a01e2 280w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?w=560&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=7454585b3478a194163804fdbf29e7eb 560w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?w=840&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=e8f3caea9bb396b433a4c1ae60dddcc1 840w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?w=1100&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=69121558ea6b5627a12148b50ba2c261 1100w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?w=1650&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=bf2d1d60bd3d2dcc90b55438c6b668ac 1650w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/traefik_dashboard.png?w=2500&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=7c14e820503c65dfcd6ebdc754d3aa82 2500w" />
|
||||
</Frame>
|
||||
|
||||
Template Import ID = 17346
|
||||
|
||||
[https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/](https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/)
|
||||
|
||||
#### Crowdsec
|
||||
|
||||
[https://github.com/crowdsecurity/grafana-dashboards/tree/master](https://github.com/crowdsecurity/grafana-dashboards/tree/master)
|
||||
|
||||
+183
@@ -0,0 +1,183 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Middleware Manager
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
This is a community guide and not officially supported. For issues, contributions, or bug reports, please use the [official GitHub repository](https://github.com/hhftechnology/middleware-manager).
|
||||
</Note>
|
||||
|
||||
## What is Middleware Manager?
|
||||
|
||||
The **Middleware Manager** is a microservice that extends your existing traefik deployments.\
|
||||
It provides a **web UI** to attach Traefik middlewares to resources without editing Pangolin itself.
|
||||
|
||||
#### Security Warning
|
||||
|
||||
Middlewares can strengthen security but also create vulnerabilities if misconfigured.
|
||||
|
||||
* Test in staging before production.
|
||||
* Misusing forward authentication can leak credentials.
|
||||
* Bad rate limiter configs may be bypassed.
|
||||
* Header misconfigurations can expose apps to XSS/CSRF.
|
||||
* Stacking too many middlewares impacts performance.
|
||||
* Always check provider references (`@http` vs `@file`).
|
||||
|
||||
***
|
||||
|
||||
### Key Use Cases
|
||||
|
||||
* External authentication (Authelia, Authentik, JWT)
|
||||
* Security headers and CSP policies
|
||||
* Geographic IP blocking
|
||||
* Rate limiting / DDoS protection
|
||||
* Redirects & path rewrites
|
||||
* CrowdSec and other security tool integrations
|
||||
|
||||
***
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* A running **Pangolin v1.0.0+**
|
||||
* Docker + Docker Compose
|
||||
* Basic Traefik knowledge
|
||||
* Admin access to your Pangolin host
|
||||
|
||||
***
|
||||
|
||||
## Step 1: Add Middleware Manager Service
|
||||
|
||||
Update your `docker-compose.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
middleware-manager:
|
||||
image: hhftechnology/middleware-manager:latest
|
||||
container_name: middleware-manager
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ./data:/data
|
||||
- ./config/traefik/rules:/conf
|
||||
- ./config/middleware-manager/templates.yaml:/app/config/templates.yaml # Optional custom templates
|
||||
environment:
|
||||
- PANGOLIN_API_URL=http://pangolin:3001/api/v1
|
||||
- TRAEFIK_CONF_DIR=/conf
|
||||
- DB_PATH=/data/middleware.db
|
||||
- PORT=3456
|
||||
ports:
|
||||
- "3456:3456"
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Step 2: Create Required Directories
|
||||
|
||||
```bash theme={null}
|
||||
mkdir -p ./config/traefik/rules
|
||||
mkdir -p ./config/middleware-manager
|
||||
```
|
||||
|
||||
Move any dynamic configs into `./config/traefik/rules`.
|
||||
|
||||
***
|
||||
|
||||
## Step 3: Update Traefik Volumes & Providers
|
||||
|
||||
In your `traefik` service:
|
||||
|
||||
```yaml theme={null}
|
||||
volumes:
|
||||
- ./config/traefik:/etc/traefik:ro
|
||||
- ./config/letsencrypt:/letsencrypt
|
||||
- ./config/traefik/logs:/var/log/traefik
|
||||
- ./config/traefik/rules:/rules # required
|
||||
```
|
||||
|
||||
In `traefik_config.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
providers:
|
||||
file:
|
||||
directory: "/rules"
|
||||
watch: true
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Step 4: Start Services
|
||||
|
||||
```bash theme={null}
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Step 5: Access the UI
|
||||
|
||||
Middleware Manager runs at:
|
||||
👉 [http://localhost:3456](http://localhost:3456)
|
||||
|
||||
***
|
||||
|
||||
## Common Middleware Examples
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```yaml theme={null}
|
||||
middlewares:
|
||||
- id: "rate-limit"
|
||||
type: "rateLimit"
|
||||
config:
|
||||
average: 100
|
||||
burst: 50
|
||||
```
|
||||
|
||||
### Security Headers
|
||||
|
||||
```yaml theme={null}
|
||||
middlewares:
|
||||
- id: "security-headers"
|
||||
type: "headers"
|
||||
config:
|
||||
customResponseHeaders:
|
||||
Server: ""
|
||||
X-Powered-By: ""
|
||||
browserXSSFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
stsSeconds: 63072000
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
* **Service does not exist** → Check `@http` or `@file` suffix in references
|
||||
* **Middleware does not exist** → Verify config and required plugins
|
||||
* **No changes applied** → Check Traefik logs, middleware priority, restart services
|
||||
* **UI not showing resources** → Confirm `PANGOLIN_API_URL` and network connectivity
|
||||
* **Database errors** → Check `./data` permissions, or reset `middleware.db`
|
||||
* \*\*CrowdSec errors → Ensure the crowdsec container is running; middlewares fail if the service is down.
|
||||
* **Protecting Pangolin itself** → Apply middlewares (e.g. geoblock, headers) directly on the websecure entryPoint to
|
||||
cover all traffic.
|
||||
* **Applying to many services** → Attach middleware to entryPoints instead of individual resources to cover all
|
||||
subdomains at once.
|
||||
* **TCP / SMTP with STARTTLS** → Not supported. Traefik cannot handle STARTTLS negotiation (only implicit TLS like SMTPS
|
||||
on 465).
|
||||
|
||||
***
|
||||
|
||||
## Final Notes
|
||||
|
||||
The Middleware Manager gives you a UI to work with Traefik’s powerful middleware ecosystem.
|
||||
|
||||
* Start with simple configs → test thoroughly → expand gradually.
|
||||
* Use templates where possible.
|
||||
* Always validate in staging before production.
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Overview
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
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://pangolin.net/discord) or [Github discussions](https://github.com/orgs/fosrl/discussions).
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<Note>
|
||||
Pangolin now supports native geoblocking. The GeoBlock plugin is considered legacy in Pangolin setups. If you previously installed it, follow [Remove GeoBlock Plugin](/self-host/community-guides/remove-geoblock-plugin) before enabling native geoblocking.
|
||||
</Note>
|
||||
|
||||
For more details, please refer to the following resources:
|
||||
|
||||
* [Github Repository](https://github.com/PascalMinder/geoblock)
|
||||
|
||||
### Middleware Manager
|
||||
|
||||
The Middlware manager is a microservice that allows you to add custom middleware to Pangolin / Traefik resources.
|
||||
|
||||
For more details, please refer to the following resources:
|
||||
|
||||
* [Github Repository](https://github.com/hhftechnology/middleware-manager)
|
||||
|
||||
## Metrics
|
||||
|
||||
Currently you can claim metric data from Traefik and Crowdsec with Prometheus and visualize 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)
|
||||
|
||||
### Traefik Logs Dashboard
|
||||
|
||||
The Traefik Logs Dashboard is a real-time dashboard for analyzing Traefik logs with IP geolocation, status code
|
||||
analysis, and service metrics.
|
||||
|
||||
For more details, please refer to the following resources:
|
||||
|
||||
* [Github Repository](https://github.com/hhftechnology/traefik-log-dashboard)
|
||||
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Remove GeoBlock Plugin
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
This is a community guide and is not officially supported. If you have any issues, please reach out to the community on [Discord](https://pangolin.net/discord) or [Github discussions](https://github.com/orgs/fosrl/discussions).
|
||||
</Note>
|
||||
|
||||
Pangolin now supports native geoblocking. If you previously installed the Traefik GeoBlock plugin, remove it before
|
||||
enabling native geoblocking to avoid duplicate blocking or startup errors.
|
||||
|
||||
<Note>
|
||||
After cleanup, follow [Enable Geo-blocking](/self-host/advanced/enable-geoblocking) to configure native geoblocking in Pangolin.
|
||||
</Note>
|
||||
|
||||
## Remove the GeoBlock plugin
|
||||
|
||||
<Steps>
|
||||
<Step title="Remove GeoBlock middleware references">
|
||||
Remove any references to `geoblock@file` from your Traefik entry points, routers, or labels.
|
||||
|
||||
Example removal in `/config/traefik/traefik_config.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
entryPoints:
|
||||
websecure:
|
||||
http:
|
||||
middlewares:
|
||||
# Remove this line
|
||||
- geoblock@file
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Remove the plugin definition from Traefik static config">
|
||||
Delete the GeoBlock plugin block from `/config/traefik/traefik_config.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
experimental:
|
||||
plugins:
|
||||
geoblock:
|
||||
moduleName: github.com/PascalMinder/geoblock
|
||||
version: v0.3.2
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Remove the middleware configuration from dynamic config">
|
||||
Delete the GeoBlock middleware section from `/config/traefik/dynamic_config.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
http:
|
||||
middlewares:
|
||||
geoblock:
|
||||
plugin:
|
||||
geoblock:
|
||||
...
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Restart Traefik">
|
||||
Restart Traefik to apply the changes:
|
||||
|
||||
```bash theme={null}
|
||||
docker restart traefik
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Next steps
|
||||
|
||||
Follow [Enable Geo-blocking](/self-host/advanced/enable-geoblocking) to configure native geoblocking in Pangolin.
|
||||
|
||||
+302
@@ -0,0 +1,302 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Traefik Log Dashboard (v2 – Agent Architecture)
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<Note>
|
||||
This is a community guide and is not officially supported. For issues or advanced configuration, please visit the [official repository](https://github.com/hhftechnology/traefik-log-dashboard).
|
||||
</Note>
|
||||
|
||||
If you’re already using the **Pangolin stack with Traefik as your reverse proxy**, you already have robust routing in
|
||||
place.\
|
||||
However, raw logs can be hard to interpret — making it difficult to visualize request patterns, latency, and geographic
|
||||
origins.
|
||||
|
||||
The **new Traefik Log Dashboard (v2)** introduces a **lightweight agent-based architecture** with **multi-instance
|
||||
scalability, enhanced GeoIP analytics, and a modern Next.js frontend** for real-time insights into your Traefik traffic.
|
||||
|
||||
***
|
||||
|
||||
## Highlights (New in v2)
|
||||
|
||||
* **Agent-based architecture**: The Go-powered agent parses logs, exposes metrics, and supports multiple Traefik
|
||||
instances.
|
||||
* **Multi-agent support**: Monitor multiple Traefik setups (e.g., production, staging) from one dashboard.
|
||||
* **Next.js 14 frontend**: Real-time charts, filters, and system stats in a responsive UI.
|
||||
* **Enhanced GeoIP**: Supports both **City** and **Country** MaxMind databases.
|
||||
* **System monitoring**: Built-in CPU, memory, and disk tracking.
|
||||
* **Bearer token authentication**: Secure access between dashboard and agents.
|
||||
* **Backward compatible** with existing Traefik log setups.
|
||||
|
||||
***
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Docker + Docker Compose
|
||||
* Traefik v2.x or v3.x (logs in JSON format)
|
||||
* A working **Pangolin stack**
|
||||
* (Optional) MaxMind GeoLite2 databases (City + Country)
|
||||
|
||||
***
|
||||
|
||||
## Step 1: Configure Traefik Logs
|
||||
|
||||
Ensure Traefik is outputting **JSON logs** and **access logs** are written to a file.
|
||||
|
||||
Update your `./config/traefik/traefik_config.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
log:
|
||||
level: INFO
|
||||
filePath: "/var/log/traefik/traefik.log"
|
||||
format: json
|
||||
|
||||
accessLog:
|
||||
filePath: "/var/log/traefik/access.log"
|
||||
format: json
|
||||
fields:
|
||||
defaultMode: keep
|
||||
headers:
|
||||
defaultMode: keep
|
||||
```
|
||||
|
||||
> Tip: JSON format is required for accurate parsing by the new agent.
|
||||
|
||||
***
|
||||
|
||||
## Step 2: Add Dashboard and Agent Services
|
||||
|
||||
Extend your existing `docker-compose.yml` with the new services.
|
||||
|
||||
```yaml theme={null}
|
||||
# Traefik Log Dashboard Agent
|
||||
traefik-agent:
|
||||
image: hhftechnology/traefik-log-dashboard-agent:latest
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "5000:5000"
|
||||
volumes:
|
||||
- ./data/positions:/data
|
||||
- ./config/traefik/logs:/logs:ro
|
||||
- ./config/maxmind:/geoip:ro
|
||||
environment:
|
||||
# Log Paths
|
||||
- TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
|
||||
- TRAEFIK_LOG_DASHBOARD_ERROR_PATH=/logs/traefik.log
|
||||
|
||||
# Authentication
|
||||
- TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=YOUR_API_TOKEN
|
||||
|
||||
# System Monitoring
|
||||
- TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING=true
|
||||
|
||||
# GeoIP Configuration
|
||||
- TRAEFIK_LOG_DASHBOARD_GEOIP_ENABLED=true
|
||||
- TRAEFIK_LOG_DASHBOARD_GEOIP_CITY_DB=/geoip/GeoLite2-City.mmdb
|
||||
- TRAEFIK_LOG_DASHBOARD_GEOIP_COUNTRY_DB=/geoip/GeoLite2-Country.mmdb
|
||||
|
||||
# Log Format
|
||||
- TRAEFIK_LOG_DASHBOARD_LOG_FORMAT=json
|
||||
|
||||
# Server Port
|
||||
- PORT=5000
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:5000/api/logs/status"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
|
||||
# Traefik Log Dashboard - Web UI
|
||||
traefik-dashboard:
|
||||
image: hhftechnology/traefik-log-dashboard:latest
|
||||
container_name: traefik-log-dashboard
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
# Agent Configuration
|
||||
- AGENT_API_URL=http://traefik-agent:5000
|
||||
- AGENT_API_TOKEN=YOUR_API_TOKEN
|
||||
- NODE_ENV=production
|
||||
- PORT=3000
|
||||
depends_on:
|
||||
traefik-agent:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
```
|
||||
|
||||
Please replace the YOUR\_API\_TOKEN with a secure token of your choice.
|
||||
|
||||
> Note: The new agent replaces both `log-dashboard-backend` and `log-dashboard-frontend` from the previous guide.
|
||||
|
||||
***
|
||||
|
||||
## Step 3: Setup MaxMind GeoIP (City + Country)
|
||||
|
||||
GeoIP is optional but highly recommended for geographic analytics and maps.
|
||||
|
||||
### 1. Create a free MaxMind account
|
||||
|
||||
[GeoLite2 Signup](https://www.maxmind.com/en/geolite2/signup)
|
||||
Generate a license key and export it for Docker use:
|
||||
|
||||
```bash theme={null}
|
||||
export MAXMIND_LICENSE_KEY=your_license_key_here
|
||||
mkdir -p ./config/maxmind
|
||||
```
|
||||
|
||||
### 2. Add the GeoIP Database Updater
|
||||
|
||||
Append this to your `docker-compose.yml`:
|
||||
|
||||
```yaml theme={null}
|
||||
# Optional: MaxMind GeoIP Database Updater
|
||||
maxmind-updater:
|
||||
image: alpine:latest
|
||||
restart: "no"
|
||||
volumes:
|
||||
- ./config/maxmind:/data
|
||||
environment:
|
||||
- MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY:-your-license-key-here}
|
||||
command: >
|
||||
sh -c "
|
||||
apk add --no-cache wget tar &&
|
||||
cd /data &&
|
||||
if [ ! -f GeoLite2-City.mmdb ] || [ \"$(find . -name 'GeoLite2-City.mmdb' -mtime +7)\" ]; then
|
||||
echo 'Updating GeoLite2-City database...'
|
||||
wget -O GeoLite2-City.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz' &&
|
||||
tar --wildcards -xzf GeoLite2-City.tar.gz --strip-components=1 '*/GeoLite2-City.mmdb' &&
|
||||
rm -f GeoLite2-City.tar.gz
|
||||
fi &&
|
||||
if [ ! -f GeoLite2-Country.mmdb ] || [ \"$(find . -name 'GeoLite2-Country.mmdb' -mtime +7)\" ]; then
|
||||
echo 'Updating GeoLite2-Country database...'
|
||||
wget -O GeoLite2-Country.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz' &&
|
||||
tar --wildcards -xzf GeoLite2-Country.tar.gz --strip-components=1 '*/GeoLite2-Country.mmdb' &&
|
||||
rm -f GeoLite2-Country.tar.gz
|
||||
fi &&
|
||||
echo 'GeoIP databases updated successfully.'
|
||||
"
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Step 4: Launch the Stack
|
||||
|
||||
```bash theme={null}
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Step 5: Access the Dashboard
|
||||
|
||||
* **Web UI** → [http://localhost:3000](http://localhost:3000)
|
||||
* Default data source: `traefik-agent:5000`
|
||||
|
||||
You should see real-time traffic metrics, GeoIP maps, error tracking, and system performance indicators.
|
||||
|
||||
***
|
||||
|
||||
## Key Features
|
||||
|
||||
**Real-time analytics** for request rates, response times, and errors
|
||||
**GeoIP maps** with both City and Country-level resolution
|
||||
**System health** (CPU, memory, disk)
|
||||
**Multi-agent support** (monitor multiple Traefik instances)
|
||||
**Secure API authentication** via token
|
||||
**Responsive modern UI**
|
||||
|
||||
***
|
||||
|
||||
## Advanced: Multi-Agent Setup
|
||||
|
||||
You can deploy multiple `traefik-agent` instances across environments and connect them all to a single dashboard.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml theme={null}
|
||||
traefik-agent-prod:
|
||||
image: hhftechnology/traefik-log-dashboard-agent:latest
|
||||
ports: ["5000:5000"]
|
||||
environment:
|
||||
- TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=prod_token
|
||||
- TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
|
||||
- TRAEFIK_LOG_DASHBOARD_GEOIP_ENABLED=true
|
||||
volumes:
|
||||
- /var/log/traefik/prod:/logs:ro
|
||||
- ./config/maxmind:/geoip:ro
|
||||
- ./data/positions-prod:/data
|
||||
|
||||
traefik-agent-staging:
|
||||
image: hhftechnology/traefik-log-dashboard-agent:latest
|
||||
ports: ["5001:5000"]
|
||||
environment:
|
||||
- TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=staging_token
|
||||
- TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
|
||||
volumes:
|
||||
- /var/log/traefik/staging:/logs:ro
|
||||
- ./config/maxmind:/geoip:ro
|
||||
|
||||
traefik-dashboard:
|
||||
image: hhftechnology/traefik-log-dashboard:latest
|
||||
ports: ["3000:3000"]
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
```
|
||||
|
||||
Then, in the **Dashboard → Settings → Agents**, add each agent URL and token.
|
||||
|
||||
***
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
| Setting | Description | Recommended |
|
||||
|-------------------------------------------|----------------------|-------------|
|
||||
| `TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING` | Enables system stats | `true` |
|
||||
| `TRAEFIK_LOG_DASHBOARD_LOG_FORMAT` | Log parsing format | `json` |
|
||||
|
||||
***
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Fix |
|
||||
|-----------------------|--------------------------|---------------------------------------------------------------------|
|
||||
| Dashboard not loading | Container not healthy | `docker compose ps` → check `health` |
|
||||
| No logs appearing | Wrong log path or format | Ensure `access.log` is JSON and volume mounted |
|
||||
| GeoIP missing | Missing databases | Run `maxmind-updater` or mount both `.mmdb` files |
|
||||
| Auth errors | Token mismatch | Verify `AGENT_API_TOKEN` matches `TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN` |
|
||||
| Slow UI | Large logs | Use JSON logs + incremental read; prune logs periodically |
|
||||
|
||||
***
|
||||
|
||||
## Summary
|
||||
|
||||
* Replaces the old `log-dashboard-backend` + `log-dashboard-frontend` with the new **agent-based architecture**
|
||||
* Supports **multiple Traefik instances**
|
||||
* Adds **GeoLite2 Country + City databases**
|
||||
* Integrates **real-time analytics + system monitoring**
|
||||
* Uses **MaxMind license key** for GeoIP updates
|
||||
* More stable with less memory
|
||||
|
||||
***
|
||||
|
||||
**Project Repository
|
||||
** → [https://github.com/hhftechnology/traefik-log-dashboard](https://github.com/hhftechnology/traefik-log-dashboard)
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user