mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-10-29 23:19:12 +01:00
107 lines
5.5 KiB
Plaintext
107 lines
5.5 KiB
Plaintext
---
|
|
title: "Domains"
|
|
icon: "globe"
|
|
description: "Learn how to configure domains for your Pangolin resources and understand the different domain types available"
|
|
---
|
|
|
|
Domains allow you to access your Pangolin resources through custom URLs. Pangolin supports different domain types depending on your deployment model and requirements. You can also attach [redirects](/manage/redirects) to a domain hostname to forward matching requests to another URL.
|
|
|
|
<Tip>
|
|
In Pangolin Cloud, a domain is not required. You can use our provided domain
|
|
endings like `.hostlocal.app` or `.tunneled.to` for your resources on any of
|
|
the paid plans.
|
|
</Tip>
|
|
|
|
## Domain Types
|
|
|
|
| Type | DNS Record | Coverage | Availability |
|
|
| --------------------- | ---------- | ---------------------------------------------------------------------- | -------------------------- |
|
|
| **Wildcard** | A / AAAA | Base domain and all subdomains (e.g. `example.com`, `app.example.com`) | Self-Hosted |
|
|
| **Domain Delegation** | NS | Base domain and all subdomains, managed entirely by Pangolin | Cloud or Enterprise w/ DNS |
|
|
| **Single Domain** | CNAME | Only the exact hostname provided (no subdomains) | Cloud or Enterprise w/ DNS |
|
|
|
|
<Note>
|
|
Wildcard (A record) domains are the most common setup for Self-Hosted, since
|
|
you already control the server's DNS and just point it at your VPS IP.
|
|
</Note>
|
|
|
|
## Delegating a Domain to Pangolin Cloud
|
|
|
|
Domain delegation and single-domain (CNAME) setups exist because Pangolin Cloud and Enterprise clustered mode doesn't run on a server whose single IP you control - your traffic is routed and terminated on various nodes. For Pangolin to issue certificates and route traffic for your domain, it needs to be able to create and update DNS records on your behalf.
|
|
|
|
- **Self-Hosted**: You point A/AAAA records at your own VPS's IP address. DNS stays with your existing provider; Pangolin never needs access to it.
|
|
- **Cloud**: There's no single static IP that's "yours" to point at, and Pangolin needs to create records (for certificate validation, routing, and new resources) without you manually updating DNS every time. Delegation and CNAME setups solve this by giving Pangolin either full control over the zone (NS delegation) or a single record it can manage (CNAME).
|
|
|
|
Domain delegation is the more powerful option since new subdomains work automatically. It also lets you manage the entire DNS zone through Pangolin, including creating and updating records as needed.
|
|
|
|
## Setting It Up
|
|
|
|
### Self-Hosted (Wildcard / A Records)
|
|
|
|
Refer to the [DNS & Networking Section](/self-host/dns-and-networking).
|
|
|
|
### Cloud & Enterprise (NS Delegation or CNAME)
|
|
|
|
**Changing nameservers hands over the whole zone, not individual records.** If you point the nameservers for your root domain (e.g. `example.com`) at Pangolin, Pangolin becomes authoritative for **every** record on that domain - including MX/email, TXT/SPF, and any other subdomains you weren't intending to move. Once delegated, you manage DNS for that zone through Pangolin, not your old provider.
|
|
|
|
<Warning>
|
|
Some registrars like Cloudflare included only let you delegate NS records at subdomains, and **don't allow you to add NS records on the root zone** at all or still include their nameservers on the root. In this case if you need to use NS delegation, delegate a subdomain of the domain or use CNAME records.
|
|
</Warning>
|
|
|
|
<Steps>
|
|
<Step title="Add the domain in the Pangolin dashboard">
|
|
From your organization's domain settings, add the domain and choose either **Domain Delegation** or **Single Domain (CNAME)**. Pangolin will show you the exact records to configure.
|
|
</Step>
|
|
<Step title="Configure DNS at your registrar/provider">
|
|
<Tabs>
|
|
<Tab title="Domain Delegation (NS)">
|
|
Change the nameservers for the domain (or subdomain) to Pangolin's, as shown in the dashboard:
|
|
|
|
```dns
|
|
Type: NS
|
|
Name: test.example.com
|
|
Value: ns1.pangolin-ns.net
|
|
ns2.pangolin-ns.net
|
|
ns3.pangolin-ns.net
|
|
```
|
|
|
|
This is done at your registrar or in your current DNS provider's nameserver settings, not as a normal DNS record.
|
|
|
|
</Tab>
|
|
<Tab title="Single Domain (CNAME)">
|
|
Add a CNAME for the hostname and for its ACME challenge, pointing to the values Pangolin gives you:
|
|
|
|
```dns
|
|
Type: CNAME
|
|
Name: test.example.com
|
|
Value: 0nbn5rpcq4wthq6.cname.pangolin.net
|
|
```
|
|
```dns
|
|
Type: CNAME
|
|
Name: _acme-challenge.test.example.com
|
|
Value: _acme-challenge.0nbn5rpcq4wthq6.cname.pangolin.net
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
</Step>
|
|
<Step title="Wait for verification">
|
|
Pangolin checks for the records automatically. NS delegation can take longer to propagate than a CNAME since it changes how the entire zone (or subzone) resolves.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Serving DNS Records
|
|
|
|
<Note>
|
|
Only available on Pangolin Cloud and Pangolin Enterprise when running with
|
|
the DNS server or in clustered mode.
|
|
</Note>
|
|
|
|
Pangolin can serve arbitrary DNS records on a NS delegated domain. Currently, Pangolin supports serving A, AAAA, CNAME, MX, TXT, SRV, and NS records. Records will not be served until a domain has been verified.
|
|
|
|
To create a DNS record on a NS delegated domain, navigate to the domain settings in the Pangolin dashboard and add the desired record type with the appropriate name and value.
|
|
|
|
<Frame caption="Custom DNS Records in the Pangolin dashboard">
|
|
<img src="/images/custom-dns-records.png" alt="Custom DNS Records" />
|
|
</Frame>
|