pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-08 05:56:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'dev'

Browse Source
This commit is contained in:
Owen
2025-12-22 16:40:25 -05:00
parent 9f94d3bc82 ab32e01413
commit 37498028cf
12 changed files with 280 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs.json
View File

@@ -73,6 +73,13 @@
]
},
"manage/domains",
{
"group": "Organizations",
"icon": "building",
"pages": [
"manage/organizations/org-id"
]
},
{
"group": "Access Control",
"icon": "user-group",
@@ -82,6 +89,7 @@
"manage/access-control/forwarded-headers",
"manage/access-control/login-page",
"manage/geoblocking",
"manage/asnblocking",
"manage/access-control/mfa",
"manage/access-control/password-rotation",
"manage/access-control/session-length",
@@ -151,6 +159,7 @@
"self-host/advanced/database-options",
"self-host/advanced/integration-api",
"self-host/advanced/enable-geoblocking",
"self-host/advanced/enable-asnblocking",
"self-host/advanced/metrics",
"self-host/telemetry"
]

BIN
images/asn_rules.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 KiB

114
manage/asnblocking.mdx Normal file
View File

@@ -0,0 +1,114 @@
---
title: "ASN Blocking"
description: "Configure ASN blocking to restrict access based on Autonomous System Numbers"
---
<Note>
ASN blocking is available in Pangolin community! Protect your resources by blocking or allowing specific networks and service providers.
</Note>
## Benefits of ASN Blocking
ASN blocking provides several important security and operational advantages:
### Security Benefits
- **Block Malicious Networks**: Prevent access from autonomous systems known for hosting malicious activity, botnets, or spam operations
- **Control Cloud Provider Access**: Restrict or allow access from specific cloud providers (AWS, Azure, GCP, etc.)
- **Block VPN/Proxy Services**: Deny access from commercial VPN and proxy service providers to prevent anonymous access
- **Datacenter Filtering**: Block traffic from datacenter networks while allowing residential ISPs
- **Compliance Requirements**: Meet regulatory requirements that restrict access from certain network types or providers
## Implementing ASN Blocking with Bypass Rules
ASN blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with ASN-based matching. You can create rules that either allow or deny access based on the visitor's Autonomous System Number.
<Frame caption="Screenshot of ASN rules from the Pangolin Dashboard.">
<img src="/images/asn_rules.png" alt="Pangolin Dashboard"/>
</Frame>
### Setting Up ASN Blocking Rules
1. Navigate to your target resource and select the **Rules** tab
2. Create a new rule and select **ASN** as the match type
3. Choose an ASN from the dropdown of common providers, or manually enter a specific ASN number
4. Choose your rule action:
- **Allow**: Bypass authentication for users from specific ASNs
- **Deny**: Block all access from specific ASNs
- **Pass to Auth**: Let users from specific ASNs proceed to authentication
### Common ASNs
The dropdown includes many commonly-used ASNs such as:
- **Cloud Providers**: Amazon (AS16509), Google Cloud (AS15169), Microsoft Azure (AS8075), DigitalOcean (AS14061)
- **Major ISPs**: Comcast (AS7922), AT&T (AS7018), Verizon (AS701), Deutsche Telekom (AS3320)
- **VPN/Proxy Services**: NordVPN (various), ExpressVPN (various), Mullvad (AS42831)
- **CDN Providers**: Cloudflare (AS13335), Fastly (AS54113), Akamai (various)
If the ASN you need isn't in the dropdown, you can manually enter the ASN number (e.g., AS12345 or just 12345).
### Common ASN Blocking Patterns
#### Block VPN and Proxy Services
Create deny rules for known VPN and proxy ASNs to prevent anonymous access:
1. Create **Deny** rules for each VPN/proxy provider ASN
2. Select ASNs from the dropdown or enter them manually
3. Set appropriate priorities
#### Block Datacenter Traffic
Block access from datacenter and hosting provider ASNs while allowing residential users:
1. Create **Deny** rules for major cloud and hosting provider ASNs
2. Include providers like AWS, GCP, Azure, DigitalOcean, etc.
3. This helps ensure only real users from residential ISPs can access your resources
#### Allow Only Specific Networks
Create a default deny rule and explicitly allow only approved ASNs:
1. Create a **Deny** rule matching all traffic with priority 100
2. Create **Allow** rules for specific approved ASNs with higher priority (e.g., 10, 20, 30)
#### Regional ISP Control
Allow access only from specific country ISPs while blocking others:
1. **Combine with Country Rules**: Use ASN rules to specify which ISPs are allowed
2. Create **Allow** rules for major residential ISPs in your target countries
3. Block datacenter and VPN ASNs that might circumvent country restrictions
### Best Practices
<Warning>
ASN blocking affects all users from that network. Be careful when blocking large ISPs or cloud providers, as legitimate users or your own infrastructure may be affected.
</Warning>
### Finding ASN Numbers
If you need to find the ASN for a specific network or provider:
1. Use online tools like [bgp.he.net](https://bgp.he.net/) or [ipinfo.io](https://ipinfo.io/)
2. Search by company name, IP address, or ASN number
3. Enter the ASN in the rule configuration (with or without the "AS" prefix)
### Rule Priority Example
```
Priority 1: Allow - ASN: AS7922 (Comcast)
Priority 2: Allow - ASN: AS7018 (AT&T)
Priority 3: Deny - ASN: AS13335 (Cloudflare - VPN)
Priority 4: Deny - ASN: AS16509 (Amazon - Datacenter)
```
This configuration allows access from residential users on Comcast and AT&T while blocking Cloudflare's VPN service and Amazon datacenters.
### Advanced Patterns
#### Block Bot Networks
Identify and block ASNs associated with automated bot traffic:
1. Monitor your access logs for suspicious ASNs
2. Create **Deny** rules for ASNs showing bot-like behavior
3. Regularly review and update your blocklist

14
manage/branding.mdx
View File

@@ -10,9 +10,9 @@ Branding is only available in Enterprise Edition.
Pangolin allows you to customize the appearance of your dashboard with your own branding, including colors, logos, and custom text for authentication pages. Branding is configured through the `privateConfig.yml` file.
<Warning>
Branding is currently available for the entire application only. Organization-specific branding will be available in a future release. Let us know if this is a priority for you.
</Warning>
## Organization Branding
In the settings of each organization, there is an Authentication Page branding settings section. These settings enable you to brand the resource authentication page and organization authentication page for that specific organization. These settings will override anything set in the configuration file.
## Setting up Branding
@@ -200,6 +200,14 @@ volumes:
</ResponseField>
</ResponseField>
### Hide Auth Page Footer
<ResponseField name="hide_auth_layout_footer" type="boolean">
Hide the horizontal footer text that appears in the bottom layout of all authentication pages.
**Default**: `false`
</ResponseField>
### Login Page
<ResponseField name="login_page" type="object">

16
manage/organizations/org-id.mdx Normal file
View File

@@ -0,0 +1,16 @@
---
title: "Organization ID"
description: "Understand organization IDs and how to locate yours in the dashboard"
---
Pangolin is multi-tenant. All sites, resources, clients, and other items belong to an organization, and a server can host more than one organization.
Each organization has a unique ID that Pangolin generates when you create the organization. You cannot change the ID after creation, and it is separate from the display name.
## Finding your organization ID
You can find your organization ID in two ways:
1. Check the general settings page for your organization. The ID appears at the top of the info card.
2. Check the URL path when viewing your dashboard. The org ID is the first slug in the URL. For example, in `https://app.pangolin.net/home-lab/settings/sites`, the org ID is `home-lab`.

49
self-host/advanced/container-cli-tool.mdx
View File

@@ -32,3 +32,52 @@ docker exec -it pangolin pangctl set-admin-credentials --email "admin@example.co
<Warning>
Use a strong password and keep your admin credentials secure.
</Warning>
## Clear Exit Nodes
Clear all exit nodes from the database:
```bash
docker exec -it pangolin pangctl clear-exit-nodes
```
<Warning>
This command permanently deletes all exit nodes from the database. This action cannot be undone.
</Warning>
## Reset User Security Keys
Reset a user's security keys (passkeys) by deleting all their webauthn credentials:
```bash
docker exec -it pangolin pangctl reset-user-security-keys --email "user@example.com"
```
<Warning>
This command permanently deletes all security keys for the specified user. The user will need to re-register their security keys to use passkey authentication again.
</Warning>
## Rotate Server Secret
Rotate the server secret by decrypting all encrypted values with the old secret and re-encrypting with a new secret. This command updates OIDC IdP configurations and license keys in the database, as well as the config file.
```bash
docker exec -it pangolin pangctl rotate-server-secret --old-secret "current-secret" --new-secret "new-secret"
```
### Options
- `--old-secret` (required): The current server secret (for verification)
- `--new-secret` (required): The new server secret to use (must be at least 8 characters long)
- `--force` (optional): Force rotation even if the old secret doesn't match the config file. Use this if you know the old secret is correct but the config file is out of sync.
<Warning>
This command performs a critical operation that affects all encrypted data in your database. Ensure you have a backup before running this command.
**Important considerations:**
- The new secret must be at least 8 characters long
- The new secret must be different from the old secret
- The command verifies the old secret matches the config file (unless `--force` is used)
- After rotation, you must restart the server for the new secret to take effect
- Using `--force` with an incorrect old secret will cause the rotation to fail or corrupt encrypted data
</Warning>

65
self-host/advanced/enable-asnblocking.mdx Normal file
View File

@@ -0,0 +1,65 @@
---
title: "Enable ASN Blocking"
description: "Configuration requirements to enable ASN blocking in Pangolin"
---
To enable ASN blocking in Pangolin Community you must download and place the Maxmind ASN database into the `config/` directory and update the config file. This can be done for free.
<Tip>
Remember to keep the ASN database updated regularly, as ASN assignments and network mappings can change over time. You can just repeat the download and extraction steps periodically to ensure your database is current.
</Tip>
<Tip>
It is possible to automate this process with a Docker container from Maxmind themself.
Have a look at this [Community guide](/self-host/community-guides/geolite2automation) on how to implement this!
</Tip>
You can use the installer to download and place the database for you, just grab the latest installer:
```bash
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
```
Then run the installer again:
```bash
./installer
```
### Manual Installation Steps
<Steps>
<Step title="Download and extract the ASN database">
Download and extract the GeoLite2 ASN database using the following commands:
```bash
# Download the GeoLite2 ASN database
curl -L -o GeoLite2-ASN.tar.gz https://github.com/GitSquared/node-geolite2-redist/raw/refs/heads/master/redist/GeoLite2-ASN.tar.gz
# Extract the database
tar -xzf GeoLite2-ASN.tar.gz
# Move the .mmdb file to the config directory
mv GeoLite2-ASN_*/GeoLite2-ASN.mmdb config/
# Clean up the downloaded files
rm -rf GeoLite2-ASN.tar.gz GeoLite2-ASN_*
```
</Step>
<Step title="Update the Pangolin config file">
Update your Pangolin configuration to point to the new ASN database file. Edit your `config/config.yml` file to include the following entry:
```yaml
server:
maxmind_asn_path: "./config/GeoLite2-ASN.mmdb"
```
</Step>
<Step title="Restart Pangolin">
Restart your Pangolin instance to apply the changes:
```bash
docker compose restart pangolin
```
</Step>
</Steps>
Alternatively you can create an account at [Maxmind](https://www.maxmind.com/en/geolite2/signup) to get a license key and download the database directly from them.

23
self-host/community-guides/geolite2automation.mdx
View File

@@ -1,13 +1,13 @@
---
title: "GeoLite2 Automation"
description: "A simple automation to download & update your GeoLite2 database with geoipupdate"
description: "A simple automation to download & update your GeoLite2 databases with geoipupdate"
---
<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` database from Maxmind to use for geoblocking on your Pangolin host. It's utilizing Maxmind's [geoipupdate](https://github.com/maxmind/geoipupdate/tree/main) Docker container to achieve this.
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)
@@ -23,7 +23,7 @@ Maxmind's service is free of charge for development, personal or community use.
* 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 database 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).
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.
@@ -72,10 +72,10 @@ services:
image: ghcr.io/maxmind/geoipupdate
restart: unless-stopped
environment:
- 'GEOIPUPDATE_ACCOUNT_ID=' # Account ID
- 'GEOIPUPDATE_LICENSE_KEY=' # API key
- 'GEOIPUPDATE_EDITION_IDS=GeoLite2-Country' # Which db should be downloaded
- 'GEOIPUPDATE_FREQUENCY=72' # Update intervall in hours
- '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'
```
@@ -91,13 +91,14 @@ Navigate to `/config` within the same folder and open it with a text editor.
cd config
```
Add this line to the `server` object
Add these lines to the `server` object
```yaml
server:
maxmind_db_path: "./config/GeoLite2/GeoLite2-Country.mmdb"
maxmind_asn_path: "./config/GeoLite2/GeoLite2-ASN.mmdb"
```
This entry tells the Pangolin application where to find the database.
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.
@@ -106,6 +107,6 @@ Restart your Pangolin stack with:
docker compose up -d
```
Et voilà, you are now able to define country rules for your ressources! 🏁
Et voilà, you are now able to define country rules and ASN rules for your ressources! 🏁
btw: you can use this exact database for your Traefik dashboard too -> [Community Guide](/self-host/community-guides/traefiklogsdashboard)
btw: you can use these exact databases for your Traefik dashboard too -> [Community Guide](/self-host/community-guides/traefiklogsdashboard)

2
self-host/how-to-update.mdx
View File

@@ -64,7 +64,7 @@ services:
plugins:
badger:
moduleName: github.com/fosrl/badger
version: v1.2.0 # Update to latest version
version: v1.3.0 # Update to latest version
```
<Warning>

2
self-host/manual/docker-compose.mdx
View File

@@ -213,7 +213,7 @@ experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.2.0"
version: "v1.3.0"
log:
level: "INFO"

2
self-host/manual/manual-install.mdx
View File

@@ -199,7 +199,7 @@ experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.2.0"
version: "v1.3.0"
log:
level: "INFO"

2
self-host/manual/unraid.mdx
View File

@@ -130,7 +130,7 @@ experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.2.0"
version: "v1.3.0"
log:
level: "INFO"