docs-v2/self-host/dns-and-networking.mdx

---
title: "DNS & Networking"
description: "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.

<Steps>
<Step title="Create wildcard record">
  Create a wildcard subdomain record for your domain:
  
  ```
  Type: A
  Name: *
  Value: YOUR_VPS_IP_ADDRESS
  TTL: 300 (or default)
  ```
  
  <Check>
  This allows any subdomain (e.g., `app.example.com`, `api.example.com`) to resolve to your VPS.
  </Check>
</Step>

<Step title="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)
  ```
  
  <Info>
  This is only needed if you want to use `example.com` (not just subdomains) as a resource.
  </Info>
</Step>

<Step title="Wait for propagation">
  DNS changes can take 5 minutes to 48 hours to propagate globally.
  
  <Tip>
  Use Google DNS (8.8.8.8) or your provider's DNS to test changes faster.
  </Tip>
</Step>
</Steps>

## Port Configuration

### Required Ports

Pangolin requires these ports to be open on your VPS:

<CardGroup cols={3}>
<Card title="TCP Port 80">
  **HTTP/SSL Verification**
  
  - Let's Encrypt domain validation
  - Non-SSL resources
  - Can be disabled with wildcard certs
</Card>

<Card title="TCP Port 443">
  **HTTPS Traffic**
  
  - Pangolin web dashboard
  - SSL-secured resources
  - Essential for operation
</Card>

<Card title="UDP Port 51820">
  **WireGuard Tunnel**
  
  - Newt client connections
  - Gerbil tunnel endpoint
  - Secure traffic routing
</Card>
</CardGroup>

### Docker Port Exposure

By default, Pangolin exposes these ports on all interfaces:

```yaml
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 and client connections
```

### Firewall Configuration

Ensure your VPS firewall allows these ports:

<Tabs>
<Tab title="Cloud Provider">
  Configure security groups/firewall rules in your cloud provider's dashboard to allow:
  
  - TCP ports 80 and 443
  - UDP port 51820
</Tab>

<Tab title="UFW (Ubuntu)">
  ```bash
  sudo ufw allow 80/tcp
  sudo ufw allow 443/tcp
  sudo ufw allow 51820/udp
  sudo ufw enable
  ```
</Tab>

<Tab title="firewalld (CentOS/RHEL)">
  ```bash
  sudo firewall-cmd --permanent --add-port=80/tcp
  sudo firewall-cmd --permanent --add-port=443/tcp
  sudo firewall-cmd --permanent --add-port=51820/udp
  sudo firewall-cmd --reload
  ```
</Tab>
</Tabs>

## Internal Network Configuration

### Default Subnet Settings

Pangolin uses these default network settings:

```yaml
gerbil:
  block_size: 24
  site_block_size: 30
  subnet_group: 100.89.137.0/20
```

**What this means:**
- **Gerbil network**: Uses first /24 subnet in `100.89.137.0/20` range
- **Site allocation**: Each site gets a /30 subnet (4 IPs)
- **CGNAT range**: Avoids conflicts with most private networks

<Info>
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).
</Info>

<Warning>
**Important**: If this subnet conflicts with your network, change it in your config **before** registering your first Gerbil.
</Warning>

### Customizing Network Settings

If you need to change the default network:

```yaml
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 port
```

<Tip>
For heavy WireGuard usage, consider increasing `site_block_size` to 29 (8 IPs) or 28 (16 IPs) per site.
</Tip>

## Docker Networking

### Local Services

When deploying services in Docker alongside Pangolin:

<AccordionGroup>
<Accordion title="Container Communication">
  **For services in the same Docker Compose:**
  
  - Use service names as hostnames
  - Example: `http://pangolin:8080`
  - Docker Compose creates internal network automatically
</Accordion>

<Accordion title="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`
</Accordion>

<Accordion title="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
</Accordion>
</AccordionGroup>