Add DNS management documentation (OpenSRS API, Hub UI, CLI examples)
This commit is contained in:
Louis Paul
parent
b9225a0d23
commit
3012fb6a41
99
DNS.md
Normal file
99
DNS.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
# DNS Management - gigafibre.ca
|
||||
|
||||
## Provider
|
||||
|
||||
- **Registrar**: OpenSRS (manage.opensrs.com)
|
||||
- **Account**: targo (louispaul@targointernet.com)
|
||||
- **API endpoint**: https://rr-n1-tor.opensrs.net:55443 (XCP/XML)
|
||||
- **Domain**: gigafibre.ca
|
||||
- **Server IP**: 96.125.196.67
|
||||
|
||||
## Managing DNS Records
|
||||
|
||||
### Option 1: Traefik Hub UI (recommended)
|
||||
|
||||
1. Go to https://hub.gigafibre.ca (or http://96.125.196.67:3080)
|
||||
2. Login: admin / targo2026
|
||||
3. Click **DNS Records** in sidebar
|
||||
4. Add/delete A records directly
|
||||
|
||||
The Hub calls the OpenSRS API internally. No additional tools needed.
|
||||
|
||||
### Option 2: Quick Deploy (DNS + Route + SSL in one step)
|
||||
|
||||
1. In Traefik Hub, click **Deploy Service**
|
||||
2. Fill in image, subdomain, port
|
||||
3. Click **Deploy**
|
||||
4. DNS record + Traefik route + SSL certificate created automatically
|
||||
|
||||
### Option 3: CLI via curl (OpenSRS XCP API)
|
||||
|
||||
The OpenSRS API uses XML over HTTPS with HMAC-MD5 signature.
|
||||
|
||||
**Authentication:**
|
||||
- Header `X-Username`: reseller username
|
||||
- Header `X-Signature`: MD5(MD5(xml + api_key) + api_key)
|
||||
- IP whitelist required in manage.opensrs.com > Account Settings > API Settings
|
||||
|
||||
**Get current records:**
|
||||
|
||||
```bash
|
||||
API_KEY="your-api-key"
|
||||
XML='<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE OPS_envelope SYSTEM "ops.dtd"><OPS_envelope><header><version>0.9</version></header><body><data_block><dt_assoc><item key="protocol">XCP</item><item key="action">GET_DNS_ZONE</item><item key="object">DOMAIN</item><item key="attributes"><dt_assoc><item key="domain">gigafibre.ca</item></dt_assoc></item></dt_assoc></data_block></body></OPS_envelope>'
|
||||
SIG=$(echo -n "$(echo -n "${XML}${API_KEY}" | md5sum | cut -d' ' -f1)${API_KEY}" | md5sum | cut -d' ' -f1)
|
||||
curl -s -4 -X POST "https://rr-n1-tor.opensrs.net:55443" \
|
||||
-H "Content-Type: text/xml" -H "X-Username: targo" -H "X-Signature: ${SIG}" \
|
||||
-d "${XML}"
|
||||
```
|
||||
|
||||
**Set records (replaces ALL A records):**
|
||||
|
||||
```bash
|
||||
XML='<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE OPS_envelope SYSTEM "ops.dtd"><OPS_envelope><header><version>0.9</version></header><body><data_block><dt_assoc><item key="protocol">XCP</item><item key="action">SET_DNS_ZONE</item><item key="object">DOMAIN</item><item key="attributes"><dt_assoc><item key="domain">gigafibre.ca</item><item key="records"><dt_assoc><item key="A"><dt_array><item key="0"><dt_assoc><item key="subdomain"></item><item key="ip_address">96.125.196.67</item></dt_assoc></item><item key="1"><dt_assoc><item key="subdomain">www</item><item key="ip_address">96.125.196.67</item></dt_assoc></item><item key="2"><dt_assoc><item key="subdomain">oss</item><item key="ip_address">96.125.196.67</item></dt_assoc></item></dt_array></item></dt_assoc></item></dt_assoc></item></dt_assoc></data_block></body></OPS_envelope>'
|
||||
```
|
||||
|
||||
**IMPORTANT**: SET_DNS_ZONE replaces the entire zone. Always GET first, modify, then SET.
|
||||
|
||||
## Current A Records
|
||||
|
||||
| Subdomain | IP | Service |
|
||||
|-----------|-----|---------|
|
||||
| @ (root) | 96.125.196.67 | Default |
|
||||
| www | 96.125.196.67 | Default |
|
||||
| oss | 96.125.196.67 | Oktopus |
|
||||
| git | 96.125.196.67 | Gitea |
|
||||
| dispatch | 96.125.196.67 | Dispatch App |
|
||||
| hub | 96.125.196.67 | Traefik Hub |
|
||||
| traefik | 96.125.196.67 | Traefik Dashboard |
|
||||
| erp | 96.125.196.67 | ERPNext (future) |
|
||||
| monitor | 96.125.196.67 | Device Monitor (future) |
|
||||
| timesheet | 96.125.196.67 | Targo Timesheet (disabled) |
|
||||
|
||||
## Adding a new subdomain (full workflow)
|
||||
|
||||
1. **Add DNS** (Hub UI > DNS Records > Add, or CLI)
|
||||
2. **Add Traefik route** (Hub UI > Routes > Add, or docker labels)
|
||||
3. **Wait 1-5 min** for DNS propagation
|
||||
4. **SSL auto-generated** by Traefik Let's Encrypt on first HTTPS request
|
||||
|
||||
## Traefik Hub internals
|
||||
|
||||
The Hub manages DNS via these components:
|
||||
- **Backend**: Node.js + dockerode (server.js)
|
||||
- **OpenSRS client**: Built-in, uses HTTPS + XML + MD5 signature
|
||||
- **Config**: Environment variables in traefik-hub/docker-compose.yml
|
||||
- `OPENSRS_USER=targo`
|
||||
- `OPENSRS_KEY=<api-key>`
|
||||
- `OPENSRS_DOMAIN=gigafibre.ca`
|
||||
- `SERVER_IP=96.125.196.67`
|
||||
- **Routes file**: /opt/traefik/dynamic/routes.yml (Traefik file provider, watched live)
|
||||
- **Docker socket**: /var/run/docker.sock (container management)
|
||||
|
||||
## OpenSRS API gotchas
|
||||
|
||||
1. **IP whitelist required** - Add your public IP in manage.opensrs.com > Account Settings > API Settings
|
||||
2. **SET replaces everything** - Always GET first, modify the array, then SET
|
||||
3. **XML format only** - No JSON API available
|
||||
4. **Signature is double-MD5** - MD5(MD5(body + key) + key)
|
||||
5. **Propagation**: 1-15 minutes for new records
|
||||
6. **Rate limits**: Not documented but ~60 requests/minute is safe
|
||||
Loading…
Reference in New Issue
Block a user