Skip to content

Commit 644b99b

Browse files
jsiebensjsiebens
committed
chore: update docs
1 parent 1ab135a commit 644b99b

File tree

2 files changed

+200
-0
lines changed

2 files changed

+200
-0
lines changed

‎mkdocs/docs/configuration/derp.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# DERP Configuration
2+
3+
DERP (Designated Encrypted Relay for Packets) servers are relay servers that help Tailscale clients establish connections when direct connections aren't possible due to NAT, firewalls, or other network impediments. ionscale provides flexible DERP configuration options to support various deployment scenarios.
4+
5+
## Embedded DERP Server
6+
7+
ionscale includes a built-in DERP server that is enabled by default. This provides an out-of-the-box relay solution without requiring additional infrastructure.
8+
9+
### Configuration
10+
11+
The embedded DERP server can be configured in your ionscale configuration file:
12+
13+
```yaml
14+
derp:
15+
server:
16+
disabled: false # Set to true to disable the embedded DERP server
17+
region_id: 1000 # The region ID for the embedded DERP server
18+
region_code: "ionscale" # The region code (short name)
19+
region_name: "ionscale Embedded DERP" # Human-readable region name
20+
```
21+
22+
Additional networking parameters that affect the DERP server:
23+
24+
```yaml
25+
# The HTTP(S) listen address for the control plane (also used for DERP)
26+
listen_addr: ":8080"
27+
28+
# The STUN listen address when using the embedded DERP
29+
stun_listen_addr: ":3478"
30+
31+
# The DNS name of the server HTTP(S) endpoint as accessible by clients
32+
public_addr: "ionscale.example.com:443"
33+
34+
# The DNS name of the STUN endpoint as accessible by clients
35+
stun_public_addr: "ionscale.example.com:3478"
36+
```
37+
38+
!!! important
39+
For the embedded DERP server to function properly, clients must be able to reach your ionscale server at the configured `public_addr` and `stun_public_addr`. Ensure these addresses are publicly accessible and have the appropriate ports open in your firewall.
40+
41+
## External DERP Sources
42+
43+
In addition to or instead of the embedded DERP server, ionscale can use external DERP servers. This is useful for:
44+
45+
- Using Tailscale's global DERP infrastructure
46+
- Setting up your own geographically distributed DERP servers
47+
- Optimizing connection paths for globally distributed teams
48+
49+
To configure external DERP sources:
50+
51+
```yaml
52+
derp:
53+
sources:
54+
- https://controlplane.tailscale.com/derpmap/default # Tailscale's default DERP map
55+
- https://example.com/my-custom-derpmap.json # Custom DERP map
56+
- git::https://github.com/example/derpmap//config.json # From a git repository
57+
- file:///etc/ionscale/derpmaps/custom.json # From a local file
58+
```
59+
60+
The `derp.sources` field accepts a list of URLs that point to JSON files containing DERP map configurations. These sources are loaded at server startup and merged with the embedded DERP configuration (if enabled).
61+
62+
!!! info "Source locations"
63+
ionscale uses HashiCorp's [go-getter](https://github.com/hashicorp/go-getter) library to fetch external sources, which supports multiple protocols and source types:
64+
65+
- **HTTP/HTTPS**: `https://example.com/derpmap.json`
66+
- **Local files**: `file:///path/to/derpmap.json`
67+
- **Git repositories**: `git::https://github.com/user/repo//path/to/file.json`
68+
- **S3 buckets**: `s3::https://s3.amazonaws.com/bucket/derpmap.json`
69+
- **GCS buckets**: `gcs::https://www.googleapis.com/storage/v1/bucket/derpmap.json`
70+
71+
This flexibility allows you to store and manage your DERP maps in various locations based on your organization's needs.
72+
73+
!!! note
74+
At the time of writing, ionscale only loads external DERP sources at startup and does not automatically poll them for changes. To apply changes to external DERP sources, you will need to restart the ionscale server.
75+
76+
## Instance and Tailnet DERP Configuration
77+
78+
ionscale provides a flexible DERP configuration model:
79+
80+
### Default Instance Configuration
81+
82+
By default, all tailnets use the DERP map defined at the instance level, which includes:
83+
84+
- The embedded DERP server (if enabled)
85+
- Any external DERP sources configured in your ionscale configuration file
86+
87+
You can view the instance-level DERP map with:
88+
89+
```bash
90+
ionscale system get-derp-map [--json]
91+
```
92+
93+
### Tailnet-Specific Configuration
94+
95+
Each tailnet can be configured with its own custom DERP map. This gives you the flexibility to:
96+
97+
- Provide optimized DERP configurations for teams in different regions
98+
- Test new DERP setups on specific tailnets before broader deployment
99+
- Create specialized network paths for particular use cases
100+
101+
When a tailnet doesn't have a custom DERP map configured, it automatically uses the instance's default DERP map.
102+
103+
Managing tailnet-specific DERP maps:
104+
105+
```bash
106+
# View a tailnet's current DERP map
107+
ionscale tailnets get-derp-map --tailnet <tailnet-id> [--json]
108+
109+
# Set a custom DERP map for a specific tailnet
110+
ionscale tailnets set-derp-map --tailnet <tailnet-id> --file <derpmap.json>
111+
112+
# Remove the custom configuration and revert to the instance default
113+
ionscale tailnets reset-derp-map --tailnet <tailnet-id>
114+
```
115+
116+
## Creating Custom DERP Maps
117+
118+
A DERP map is a JSON structure containing regions and nodes. Here's an example:
119+
120+
```json
121+
{
122+
"Regions": {
123+
"1": {
124+
"RegionID": 1,
125+
"RegionCode": "nyc",
126+
"RegionName": "New York City",
127+
"Nodes": [
128+
{
129+
"Name": "1a",
130+
"RegionID": 1,
131+
"HostName": "derp1.example.com",
132+
"DERPPort": 443,
133+
"STUNPort": 3478
134+
}
135+
]
136+
},
137+
"2": {
138+
"RegionID": 2,
139+
"RegionCode": "sfo",
140+
"RegionName": "San Francisco",
141+
"Nodes": [
142+
{
143+
"Name": "2a",
144+
"RegionID": 2,
145+
"HostName": "derp2.example.com",
146+
"DERPPort": 443,
147+
"STUNPort": 3478
148+
}
149+
]
150+
}
151+
}
152+
}
153+
```
154+
155+
Important fields:
156+
157+
- `RegionID`: A unique identifier for the region (1-999 for custom regions, 1000+ reserved for ionscale)
158+
- `RegionCode`: A short code for the region (e.g., "nyc", "sfo")
159+
- `RegionName`: A human-readable name for the region
160+
- `Nodes`: A list of DERP servers in the region
161+
- `Name`: A unique name for the node within the region
162+
- `HostName`: The DNS name of the DERP server
163+
- `DERPPort`: The port for DERP traffic (typically 443)
164+
- `STUNPort`: The port for STUN traffic (typically 3478)
165+
166+
To apply a custom DERP map to a tailnet:
167+
168+
```bash
169+
# Create the DERP map file
170+
cat > my-derpmap.json <<EOF
171+
{
172+
"Regions": {
173+
"1": {
174+
"RegionID": 1,
175+
"RegionCode": "custom",
176+
"RegionName": "My Custom DERP",
177+
"Nodes": [
178+
{
179+
"Name": "derp1",
180+
"RegionID": 1,
181+
"HostName": "derp.example.com",
182+
"DERPPort": 443,
183+
"STUNPort": 3478
184+
}
185+
]
186+
}
187+
}
188+
}
189+
EOF
190+
191+
# Apply it to a tailnet
192+
ionscale tailnets set-derp-map --tailnet <tailnet-id> --file my-derpmap.json
193+
```
194+
195+
!!! tip
196+
DERP servers primarily help with establishing connections when direct peer-to-peer connections aren't possible. Having DERP servers geographically close to your users can improve connection establishment times and provide better fallback performance.
197+
198+
!!! note
199+
Changes to DERP maps are automatically distributed to clients during their regular polling. There's no need to manually update clients when changing DERP configurations.

‎mkdocs/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ nav:
1717
- Getting started: ./getting-started/index.md
1818
- Creating a tailnet: ./getting-started/tailnet.md
1919
- Configuration:
20+
- DERP: ./configuration/derp.md
2021
- OIDC: ./configuration/auth-oidc.md
2122
- DNS providers: ./configuration/dns-providers.md
2223
- Reference: ./configuration/reference.md

0 commit comments

Comments
 (0)