0
# DNS Management
1

2
Comprehensive DNS management for custom domains, including zone management, record manipulation, and DNS configuration for Surge deployments.
3

4
## Capabilities
5

6
### DNS Records Management
7

8
View and manage DNS records for domains hosted on Surge.
9

10
```javascript { .api }
11
/**
12
 * View and manage DNS records for domain
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function dns(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# View DNS records for domain
22
surge dns example.com
23

24
# Add DNS record
25
surge dns example.com add A www 192.168.1.1
26

27
# Add CNAME record
28
surge dns example.com add CNAME api api.example.com
29

30
# Remove DNS record by ID
31
surge dns example.com rem 12345
32

33
# List all DNS operations
34
surge dns --help
35
```
36

37
**Supported Record Types:**
38
- **A**: IPv4 address records
39
- **AAAA**: IPv6 address records
40
- **CNAME**: Canonical name records
41
- **MX**: Mail exchange records
42
- **TXT**: Text records
43
- **NS**: Name server records
44

45
**Library Usage:**
46
```javascript
47
surge.dns({})(process.argv.slice(2));
48
```
49

50
### DNS Zone Management
51

52
Full DNS zone management and configuration.
53

54
```javascript { .api }
55
/**
56
 * Full DNS zone management for domain
57
 * @param hooks - Optional lifecycle hooks
58
 * @returns Command function
59
 */
60
function zone(hooks?: HookConfig): CommandFunction;
61
```
62

63
**CLI Usage:**
64
```bash
65
# View complete DNS zone
66
surge zone example.com
67

68
# Zone management interface
69
surge zone example.com --edit
70
```
71

72
**Zone Management Features:**
73
- View complete DNS zone configuration
74
- Bulk DNS record operations
75
- Zone file import/export
76
- DNS propagation checking
77

78
**Library Usage:**
79
```javascript
80
surge.zone({})(process.argv.slice(2));
81
```
82

83
## DNS Record Operations
84

85
### Adding DNS Records
86

87
**A Records (IPv4):**
88
```bash
89
# Point domain to IP address
90
surge dns example.com add A @ 192.168.1.1
91

92
# Point subdomain to IP
93
surge dns example.com add A www 192.168.1.1
94
```
95

96
**AAAA Records (IPv6):**
97
```bash
98
# Point domain to IPv6 address
99
surge dns example.com add AAAA @ 2001:db8::1
100

101
# Point subdomain to IPv6
102
surge dns example.com add AAAA www 2001:db8::1
103
```
104

105
**CNAME Records:**
106
```bash
107
# Point subdomain to another domain
108
surge dns example.com add CNAME api api.example.com
109

110
# Point subdomain to Surge
111
surge dns example.com add CNAME blog blog.example.surge.sh
112
```
113

114
**MX Records (Mail):**
115
```bash
116
# Add mail server
117
surge dns example.com add MX @ mail.example.com 10
118

119
# Add backup mail server
120
surge dns example.com add MX @ backup.example.com 20
121
```
122

123
**TXT Records:**
124
```bash
125
# Add SPF record
126
surge dns example.com add TXT @ "v=spf1 include:_spf.google.com ~all"
127

128
# Add domain verification
129
surge dns example.com add TXT @ "verification-code-12345"
130

131
# Add DKIM record
132
surge dns example.com add TXT selector._domainkey "k=rsa; p=public-key-here"
133
```
134

135
### Viewing DNS Records
136

137
**List All Records:**
138
```bash
139
surge dns example.com
140
```
141

142
**Record Display Format:**
143
```
144
ID    Type  Name  Value                TTL   Status
145
---   ----  ----  -------------------- ----  ------
146
001   A     @     192.168.1.1          300   Active
147
002   A     www   192.168.1.1          300   Active  
148
003   CNAME api   api.example.com      300   Active
149
004   MX    @     mail.example.com 10  300   Active
150
005   TXT   @     "v=spf1..."          300   Active
151
```
152

153
### Removing DNS Records
154

155
**Remove by ID:**
156
```bash
157
surge dns example.com rem 001
158
```
159

160
**Remove Multiple Records:**
161
```bash
162
surge dns example.com rem 001 002 003
163
```
164

165
## DNS Configuration
166

167
### Custom Domain Setup
168

169
**Step 1: Configure DNS**
170
```bash
171
# Point domain to Surge
172
surge dns example.com add CNAME @ example.surge.sh
173

174
# Or use A record if CNAME not supported for apex
175
surge dns example.com add A @ 45.55.110.124
176
```
177

178
**Step 2: Deploy to Domain**
179
```bash
180
# Deploy project to custom domain
181
surge ./build example.com
182
```
183

184
**Step 3: Verify Configuration**
185
```bash
186
# Check DNS propagation
187
dig example.com
188

189
# Verify HTTPS
190
curl -I https://example.com
191
```
192

193
### Subdomain Configuration
194

195
**Multiple Subdomains:**
196
```bash
197
# API subdomain
198
surge dns example.com add CNAME api api.example.surge.sh
199

200
# Blog subdomain
201
surge dns example.com add CNAME blog blog.example.surge.sh
202

203
# CDN subdomain
204
surge dns example.com add CNAME cdn cdn.example.surge.sh
205
```
206

207
### Email Configuration
208

209
**Google Workspace:**
210
```bash
211
# MX records for Gmail
212
surge dns example.com add MX @ aspmx.l.google.com 1
213
surge dns example.com add MX @ alt1.aspmx.l.google.com 5
214
surge dns example.com add MX @ alt2.aspmx.l.google.com 5
215

216
# SPF record
217
surge dns example.com add TXT @ "v=spf1 include:_spf.google.com ~all"
218
```
219

220
**Custom Mail Server:**
221
```bash
222
# Primary mail server
223
surge dns example.com add MX @ mail.example.com 10
224

225
# Backup mail server  
226
surge dns example.com add MX @ backup.example.com 20
227

228
# SPF record
229
surge dns example.com add TXT @ "v=spf1 mx ~all"
230
```
231

232
## Advanced DNS Features
233

234
### DNS Propagation
235

236
**Check Propagation Status:**
237
```bash
238
# Check DNS propagation globally
239
dig @8.8.8.8 example.com
240
dig @1.1.1.1 example.com
241

242
# Check from multiple locations
243
nslookup example.com 8.8.8.8
244
nslookup example.com 1.1.1.1
245
```
246

247
**Propagation Timing:**
248
- **TTL**: Time-to-live affects propagation speed
249
- **Global Propagation**: Can take 24-48 hours
250
- **Local Cache**: Clear DNS cache for testing
251

252
### Load Balancing
253

254
**Round Robin DNS:**
255
```bash
256
# Multiple A records for load balancing
257
surge dns example.com add A @ 192.168.1.1
258
surge dns example.com add A @ 192.168.1.2
259
surge dns example.com add A @ 192.168.1.3
260
```
261

262
**Geographic Distribution:**
263
```bash
264
# Different servers for different regions
265
surge dns example.com add A us 192.168.1.1
266
surge dns example.com add A eu 192.168.2.1
267
surge dns example.com add A asia 192.168.3.1
268
```
269

270
### DNS Security
271

272
**CAA Records (Certificate Authority Authorization):**
273
```bash
274
# Allow only specific CAs to issue certificates
275
surge dns example.com add CAA @ "0 issue letsencrypt.org"
276
surge dns example.com add CAA @ "0 issuewild letsencrypt.org"
277
```
278

279
**DMARC Policy:**
280
```bash
281
# Email authentication policy
282
surge dns example.com add TXT _dmarc "v=DMARC1; p=reject; rua=mailto:dmarc@example.com"
283
```
284

285
## DNS Best Practices
286

287
### Record Management
288

289
1. **Use Appropriate TTL**: Balance between performance and flexibility
290
2. **Monitor Changes**: Track DNS record modifications
291
3. **Test Before Deployment**: Verify DNS changes in staging
292
4. **Document Records**: Keep record of all DNS configurations
293

294
### Performance Optimization
295

296
1. **Short TTL for Testing**: Use low TTL during testing, increase for production
297
2. **CNAME Chains**: Avoid long CNAME chains that slow resolution
298
3. **Multiple A Records**: Use for redundancy and load distribution
299
4. **Geographic DNS**: Consider geographic distribution for global users
300

301
### Security Considerations
302

303
1. **Secure DNS Providers**: Use reputable DNS providers
304
2. **Monitor Changes**: Set up alerts for DNS modifications
305
3. **Access Control**: Limit who can modify DNS records
306
4. **DNSSEC**: Consider DNSSEC for additional security
307

308
## Troubleshooting
309

310
### Common DNS Issues
311

312
**DNS Not Propagating:**
313
- Check TTL settings
314
- Verify record syntax
315
- Clear local DNS cache
316
- Test from multiple locations
317

318
**Wrong IP Resolution:**
319
- Check A/AAAA record values
320
- Verify CNAME targets
321
- Check for conflicting records
322

323
**Email Not Working:**
324
- Verify MX record priorities
325
- Check SPF record syntax
326
- Test mail server connectivity
327

328
### Debugging Tools
329

330
**Command Line Tools:**
331
```bash
332
# Query DNS records
333
dig example.com
334
nslookup example.com
335

336
# Check MX records
337
dig MX example.com
338

339
# Check TXT records
340
dig TXT example.com
341

342
# Trace DNS resolution
343
dig +trace example.com
344
```
345

346
**Online Tools:**
347
- DNS Checker websites
348
- MX Toolbox for mail testing
349
- SSL Labs for certificate verification
350
- DNS propagation checkers
351

352
### Error Resolution
353

354
**Record Not Found:**
355
- Verify record was created successfully
356
- Check DNS propagation status
357
- Confirm correct record type
358

359
**Invalid Record Format:**
360
- Check record syntax
361
- Verify value format for record type
362
- Ensure proper escaping of special characters
363

364
**Access Denied:**
365
- Verify domain ownership
366
- Check user permissions
367
- Ensure proper authentication