DNS & Networking
Configure your domain, DNS records, and network settings for Pangolin deployment
Pangolin requires proper DNS configuration and network setup to function correctly. This guide covers domain setup, DNS records, port configuration, and networking considerations.
DNS Configuration
Basic DNS Records
You'll need to create A (or AAAA for IPv6) records pointing to your VPS IP address.
Create wildcard record
Create a wildcard subdomain record for your domain:
Type: A
Name: *
Value: YOUR_VPS_IP_ADDRESS
TTL: 300 (or default)This allows any subdomain (e.g., app.example.com, api.example.com) to resolve to your VPS.
Create root domain record (optional)
If you plan to use your root domain as a resource:
Type: A
Name: @ (or leave blank)
Value: YOUR_VPS_IP_ADDRESS
TTL: 300 (or default)This is only needed if you want to use example.com (not just subdomains) as a resource.
Wait for propagation
DNS changes can take 5 minutes to 48 hours to propagate globally.
Use Google DNS (8.8.8.8) or your provider's DNS to test changes faster.
Port Configuration
Required Ports
Pangolin requires these ports to be open on your VPS:
TCP Port 80
HTTP/SSL Verification
- Let's Encrypt domain validation
- Non-SSL resources
- Can be disabled with wildcard certs
TCP Port 443
HTTPS Traffic
- Pangolin web dashboard
- SSL-secured resources
- Essential for operation
UDP Port 51820
Site Tunnels
This is the default port for Pangolin Sites to establish tunnels to the proxy.
UDP Port 21820
Client Tunnels
This is the default port for clients relaying through the server to Pangolin Sites. This port is only required for clients.
Always verify your exposed ports (e.g., with nmap or RustScan) and ensure you expose only the ports that are absolutely necessary. By tunneling out to the VPS, you are effectively including the VPS in your security boundary, so you must secure it as part of your overall network strategy. For more details, see Docker’s port publishing documentation.
Docker Port Exposure
By default, Pangolin exposes these ports on all interfaces:
gerbil:
ports:
- "80:80" # HTTP/SSL verification and non-SSL resources
- "443:443" # HTTPS for web UI and SSL resources
- "51820:51820" # WireGuard for Newt connections
- "21820:21820" # WireGuard for client connectionsFirewall Configuration
Ensure your VPS firewall allows these ports:
Configure security groups/firewall rules in your cloud provider's dashboard to allow:
- TCP ports 80 and 443
- UDP ports 51820 and 21820
Internal Network Configuration
Default Subnet Settings
Pangolin uses these default network settings:
gerbil:
block_size: 24
site_block_size: 30
subnet_group: 100.89.137.0/20What this means:
- Gerbil network: Uses first /24 subnet in
100.89.137.0/20range - Site allocation: Each site gets a /30 subnet (4 IPs)
- CGNAT range: Avoids conflicts with most private networks
The 100.89.137.0/20 range is in the CGNAT (Carrier-Grade NAT) space, which should avoid conflicts with typical private networks (192.168.x.x, 10.x.x.x, 172.16-31.x.x).
Important: If this subnet conflicts with your network, change it in your config before registering your first Gerbil.
Customizing Network Settings
If you need to change the default network:
gerbil:
block_size: 24 # Size of Gerbil's network block
site_block_size: 30 # Size of each site's network block
subnet_group: 10.0.0.0/8 # Custom subnet range
start_port: 51820 # WireGuard server portFor heavy WireGuard usage, consider increasing site_block_size to 29 (8 IPs) or 28 (16 IPs) per site.
Docker Networking
Local Services
When deploying services in Docker alongside Pangolin:
Container Communication
For services in the same Docker Compose:
- Use service names as hostnames
- Example:
http://pangolin:8080 - Docker Compose creates internal network automatically
Host Machine Access
To access services on the host machine:
- Use
172.17.0.1(Docker bridge gateway) - Or use
host.docker.internal(Docker Desktop) - Example:
http://172.17.0.1:3000
External Services
For services outside Docker:
- Use the host's public IP address
- Ensure firewall allows the required ports
- Consider using VPN or secure tunnels
Was this page helpful?