pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-07-18 11:59:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #118 from LaurenceJJones/docs/rename-geo-blocking-to-geo-location

Browse Source 
enhance(geo): reduce confusion between setup and usage
This commit is contained in:
Owen Schwartz
2026-05-12 14:00:05 -07:00
committed by GitHub
parent 22e5aa55a0 c18640c8ff
commit 1c1c483576
11 changed files with 128 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs.json
View File

@@ -190,8 +190,8 @@
"self-host/advanced/container-cli-tool",
"self-host/advanced/database-options",
"self-host/advanced/integration-api",
"self-host/advanced/enable-geoblocking",
"self-host/advanced/enable-asnblocking",
"self-host/advanced/enable-geolocation",
"self-host/advanced/enable-asn-lookup",
"self-host/advanced/metrics",
"self-host/advanced/clustering",
"self-host/advanced/traefik-log-rotation",
@@ -388,6 +388,14 @@
]
},
"redirects": [
{
"source": "/self-host/advanced/enable-geoblocking",
"destination": "/self-host/advanced/enable-geolocation"
},
{
"source": "/self-host/advanced/enable-asnblocking",
"destination": "/self-host/advanced/enable-asn-lookup"
},
{
"source": "/telemetry",
"destination": "/self-host/telemetry"

8
manage/access-control/rules.mdx
View File

@@ -71,13 +71,13 @@ We use a IP database to geolocate the IP address but this is not always accurate
Select the "ALL" option to match all countries for allowing or denying access.
To enable geoblocking, follow this guide to set up the geolocation database: [Geoblocking Guide](/self-host/advanced/enable-geoblocking).
To use country rules, follow this guide to set up the geolocation database: [Enable Geo-location](/self-host/advanced/enable-geolocation).
### Region
Region match rules allow you to specify allowed or denied regions for requests based on their IP address. This is useful for geo-restrictions or compliance with regional regulations. Regions are made up of a list of countries in that region (e.g. "EU" includes France, Germany, etc.) so this is a more broad match than country.
To enable follow the above guide to set up the geolocation database: [Geoblocking Guide](/self-host/advanced/enable-geoblocking).
To use region rules, follow this guide to set up the geolocation database: [Enable Geo-location](/self-host/advanced/enable-geolocation).
### CIDR
@@ -102,7 +102,7 @@ Pretty simple: you can match on simply an IP address like your home IP to bypass
ASN (Autonomous System Number) match rules allow you to specify allowed or denied ASNs for requests based on their IP address. This is useful for blocking or allowing traffic from specific ISPs or organizations.
To enable ASN blocking, follow this guide to set up the ASN database: [ASN Blocking Guide](/self-host/advanced/enable-asnblocking).
To use ASN rules, follow this guide to set up the ASN lookup database: [Enable ASN Lookup](/self-host/advanced/enable-asn-lookup).
**Examples:**
@@ -112,4 +112,4 @@ To enable ASN blocking, follow this guide to set up the ASN database: [ASN Block
### Community Contributed Rules
Some common bypass paths for common self hosted apps can be found [in the community contributed rules](/self-host/community-guides/rules).
Some common bypass paths for common self hosted apps can be found [in the community contributed rules](/self-host/community-guides/rules).

3
manage/asnblocking.mdx
View File

@@ -10,7 +10,7 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<Note>
ASN blocking is available in Pangolin community! Protect your resources by blocking or allowing specific networks and service providers.
ASN blocking is available in Pangolin Community Edition. It depends on Pangolin's ASN lookup database. Follow [Enable ASN Lookup](/self-host/advanced/enable-asn-lookup) before creating ASN rules.
</Note>
## Benefits of ASN Blocking
@@ -117,4 +117,3 @@ Identify and block ASNs associated with automated bot traffic:
2. Create **Deny** rules for ASNs showing bot-like behavior
3. Regularly review and update your blocklist

18
manage/geoblocking.mdx
View File

@@ -1,6 +1,6 @@
---
title: "Geo-blocking"
description: "Configure geo blocking to restrict access based on geographic location"
description: "Configure geo-blocking to restrict access based on geographic location"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
@@ -10,12 +10,12 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<Note>
Geoblocking is available in Pangolin community! Make sure to follow this guide for how to enable: [Enabling Geo Blocking](/self-host/advanced/enable-geoblocking)
Geo-blocking is available in Pangolin Community Edition. It depends on Pangolin's geo-location database, which is also used by other location-aware features such as analytics. Follow [Enable Geo-location](/self-host/advanced/enable-geolocation) before creating country or region rules.
</Note>
## Benefits of Geo Blocking
## Benefits of Geo-blocking
Geo blocking provides several important security and compliance advantages:
Geo-blocking provides several important security and compliance advantages:
### Security Benefits
- **Reduce Attack Surface**: Block access from regions with high levels of malicious activity or where you don't expect legitimate users
@@ -23,15 +23,15 @@ Geo blocking provides several important security and compliance advantages:
- **Compliance Requirements**: Meet regulatory requirements that restrict data access based on geographic location
- **Resource Protection**: Prevent unnecessary load on your services from regions where you don't operate
## Implementing Geo Blocking with Bypass Rules
## Implementing Geo-blocking with Bypass Rules
Geo blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with country-based matching. You can create rules that either allow or deny access based on the visitor's country.
Geo-blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with country-based matching. You can create rules that either allow or deny access based on the visitor's country.
<Frame caption="Screenshot of resources rules from the Pangolin Dashboard.">
<img src="/images/country_rules.png" alt="Pangolin Dashboard"/>
</Frame>
### Setting Up Geo Blocking Rules
### Setting Up Geo-blocking Rules
1. Navigate to your target resource and select the **Rules** tab
2. Create a new rule and select **Country** as the match type
@@ -40,7 +40,7 @@ Geo blocking in Pangolin is implemented using [bypass rules](/manage/access-cont
- **Deny**: Block all access from specific countries
- **Pass to Auth**: Let users from specific countries proceed to authentication
### Common Geo Blocking Patterns
### Common Geo-blocking Patterns
#### Allow Only Specific Countries
Create a "Deny" rule that blocks all countries except those you want to allow:
@@ -63,7 +63,7 @@ Create targeted deny rules for specific countries while allowing all others:
3. Set appropriate priorities
#### Regional Access Control
Combine geo blocking with other rule types for sophisticated access control:
Combine geo-blocking with other rule types for sophisticated access control:
1. **Path + Country**: Block admin paths (`/admin/*`) from all countries except your headquarters
2. **IP + Country**: Allow specific IPs from restricted countries (for VPN users or partners)

77
self-host/advanced/enable-asn-lookup.mdx Normal file
View File

@@ -0,0 +1,77 @@
---
title: "Enable ASN Lookup"
description: "Configuration requirements to enable ASN lookup features in Pangolin"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Pangolin uses an ASN database to map request IP addresses to autonomous systems, such as cloud providers, residential ISPs, VPN providers, and corporate networks. That ASN data powers ASN access rules and ASN blocking patterns.
To enable ASN lookup features in Pangolin self-hosted, download the MaxMind ASN database, place it in the `config/` directory, and point Pangolin at the database 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>
You can automate this process with a MaxMind Docker container. See the [GeoLite2 Automation community guide](/self-host/community-guides/geolite2automation) for an example.
</Tip>
## Install with the Installer
You can use the installer to download and place the database for you. Download the latest installer:
```bash
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
```
Then run the installer again:
```bash
./installer
```
## Manual Installation
<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 `config/config.yml` 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.
<Note>
After the ASN lookup database is enabled, use [access control rules](/manage/access-control/rules) or the [ASN Blocking](/manage/asnblocking) guide to create blocking or allow rules.
</Note>

71
self-host/advanced/enable-asnblocking.mdx
View File

@@ -1,71 +0,0 @@
---
title: "Enable ASN Blocking"
description: "Configuration requirements to enable ASN blocking in Pangolin"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
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.

36
self-host/advanced/enable-geoblocking.mdx → self-host/advanced/enable-geolocation.mdx
View File

@@ -7,31 +7,33 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Pangolin uses a GeoIP database to map request IP addresses to approximate locations. That location data powers multiple features, including country and region access rules, geo-blocking patterns, and analytics.
Pangolin uses a geolocation database for several geolocation features like geoblocking and analytics. To enable geolocation features in Pangolin self-hosted, you must download and place the Maxmind geoip database into the `config/` directory and update the config file. This can be done for free.
To enable geo-location features in Pangolin self-hosted, download a MaxMind GeoIP database, place it in the `config/` directory, and point Pangolin at the database file. This can be done for free.
<Tip>
Remember to keep the GeoIP database updated regularly, as IP-to-country 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!
You can automate this process with a MaxMind Docker container. See the [GeoLite2 Automation community guide](/self-host/community-guides/geolite2automation) for an example.
</Tip>
You can use the installer to download and place the database for you, just grab the latest installer:
## Install with the Installer
You can use the installer to download and place the database for you. Download the latest installer:
```bash
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
```
```bash
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
```
Then run the installer again:
```bash
./installer
```
```bash
./installer
```
### Manual Installation Steps
## Manual Installation
<Steps>
<Step title="Download and extract the GeoIP database">
@@ -52,7 +54,7 @@ Then run the installer again:
```
</Step>
<Step title="Update the Pangolin config file">
Update your Pangolin configuration to point to the new GeoIP database file. Edit your `config/config.yml` file to include the following entry:
Update your Pangolin configuration to point to the new GeoIP database file. Edit `config/config.yml` to include the following entry:
```yaml
server:
@@ -63,9 +65,13 @@ Then run the installer again:
Restart your Pangolin instance to apply the changes:
```bash
docker compose restart pangolin
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.
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.
<Note>
After the geo-location database is enabled, use [access control rules](/manage/access-control/rules) or the [Geo-blocking](/manage/geoblocking) guide to create blocking or allow rules.
</Note>

2
self-host/community-guides/geoblock.mdx
View File

@@ -13,7 +13,7 @@ This is a community guide and is not officially supported. If you have any issue
</Note>
<Warning>
Legacy guide. Pangolin now supports native geoblocking. If you previously installed this plugin, follow [Remove GeoBlock Plugin](/self-host/community-guides/remove-geoblock-plugin) before enabling native geoblocking.
Legacy guide. Pangolin now supports native geo-blocking. If you previously installed this plugin, follow [Remove GeoBlock Plugin](/self-host/community-guides/remove-geoblock-plugin) before enabling native geo-blocking.
</Warning>
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.

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

@@ -13,7 +13,7 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
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.
This automation lets your system automatically download and update the `GeoLite2-Country` and `GeoLite2-ASN` databases from MaxMind. Pangolin uses these databases for geo-location features such as country or region rules, geo-blocking, analytics, and ASN blocking. It uses MaxMind's [geoipupdate](https://github.com/maxmind/geoipupdate/tree/main) Docker container to do 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)

2
self-host/community-guides/overview.mdx
View File

@@ -35,7 +35,7 @@ For additional information, consult the following resources:
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.
Pangolin now supports native geo-blocking. 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 geo-blocking.
</Note>
For more details, please refer to the following resources:

6
self-host/community-guides/remove-geoblock-plugin.mdx
View File

@@ -12,10 +12,10 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
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.
Pangolin now supports native geo-blocking. If you previously installed the Traefik GeoBlock plugin, remove it before enabling native geo-blocking 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.
After cleanup, follow [Enable Geo-location](/self-host/advanced/enable-geolocation) to configure the geo-location database used by native geo-blocking in Pangolin.
</Note>
## Remove the GeoBlock plugin
@@ -69,4 +69,4 @@ After cleanup, follow [Enable Geo-blocking](/self-host/advanced/enable-geoblocki
## Next steps
Follow [Enable Geo-blocking](/self-host/advanced/enable-geoblocking) to configure native geoblocking in Pangolin.
Follow [Enable Geo-location](/self-host/advanced/enable-geolocation) to configure the geo-location database used by native geo-blocking in Pangolin.