CyberMind-FR
c6fb79ed3b
New packages: - secubox-app-backup: Unified backup for LXC containers, UCI config, services - luci-app-backup: KISS dashboard with container list and backup history - secubox-app-mailserver: Custom Postfix+Dovecot in LXC with mesh backup Enhanced dnsctl with: - generate: Auto-create subdomain A records - suggest: Name suggestions by category - mail-setup: MX, SPF, DMARC record creation - dkim-add: DKIM TXT record management Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
119 lines
3.8 KiB
Markdown
119 lines
3.8 KiB
Markdown
# secubox-app-dns-provider
|
|
|
|
Programmatic DNS record management via provider REST APIs. Part of the SecuBox ecosystem.
|
|
|
|
## Overview
|
|
|
|
Manages DNS zones through OVH, Gandi, and Cloudflare APIs. Provides a CLI tool (`dnsctl`) for record CRUD, HAProxy vhost sync, DNS propagation verification, and ACME DNS-01 certificate issuance.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
dnsctl (CLI)
|
|
├── load_provider() → sources /usr/lib/secubox/dns/{provider}.sh
|
|
├── cmd_list/add/rm → delegates to dns_list/dns_add/dns_rm
|
|
├── cmd_sync → iterates HAProxy UCI vhosts → dns_add per domain
|
|
├── cmd_verify → nslookup against 1.1.1.1, 8.8.8.8, 9.9.9.9
|
|
└── cmd_acme_dns01 → exports provider env vars → acme.sh --dns
|
|
```
|
|
|
|
## Provider Adapters
|
|
|
|
Each adapter in `/usr/lib/secubox/dns/` implements:
|
|
|
|
| Function | Description |
|
|
|---|---|
|
|
| `dns_list(zone)` | List all records in zone |
|
|
| `dns_add(zone, type, subdomain, target, ttl)` | Create record |
|
|
| `dns_rm(zone, type, subdomain)` | Delete record |
|
|
| `dns_verify(fqdn)` | Check resolution |
|
|
| `dns_test_credentials()` | Validate API keys |
|
|
|
|
### Supported Providers
|
|
|
|
- **OVH** — HMAC-SHA1 signed API v1 (app_key + app_secret + consumer_key)
|
|
- **Gandi** — LiveDNS v5 with Bearer token
|
|
- **Cloudflare** — API v4 with Bearer token + zone_id
|
|
|
|
## UCI Configuration
|
|
|
|
```
|
|
/etc/config/dns-provider
|
|
config dns_provider 'main' → enabled, provider, zone
|
|
config ovh 'ovh' → endpoint, app_key, app_secret, consumer_key
|
|
config gandi 'gandi' → api_key
|
|
config cloudflare 'cloudflare' → api_token, zone_id
|
|
```
|
|
|
|
## CLI Usage
|
|
|
|
### Basic Operations
|
|
|
|
```bash
|
|
dnsctl status # Show config status
|
|
dnsctl test # Verify API credentials
|
|
dnsctl list # List zone records
|
|
dnsctl add A myservice 1.2.3.4 # Create A record
|
|
dnsctl add CNAME www mycdn.net # Create CNAME
|
|
dnsctl update A myservice 5.6.7.8 # Update existing record
|
|
dnsctl get A www # Get record value
|
|
dnsctl rm A myservice # Remove record
|
|
dnsctl domains # List all domains in account
|
|
```
|
|
|
|
### HAProxy Sync
|
|
|
|
```bash
|
|
dnsctl sync # Sync HAProxy vhosts to DNS A records
|
|
dnsctl verify myservice.example.com # Check propagation (1.1.1.1, 8.8.8.8, 9.9.9.9)
|
|
```
|
|
|
|
### Subdomain Generator
|
|
|
|
```bash
|
|
dnsctl generate gitea # Auto-create gitea.zone with public IP
|
|
dnsctl generate api prod # Create prod-api.zone
|
|
dnsctl suggest web # Show subdomain name suggestions
|
|
dnsctl suggest mail # Suggestions: mail, smtp, imap, webmail, mx
|
|
dnsctl suggest dev # Suggestions: git, dev, staging, test, ci
|
|
```
|
|
|
|
### DynDNS
|
|
|
|
```bash
|
|
dnsctl dyndns # Update root A record with WAN IP
|
|
dnsctl dyndns api 300 # Update api.zone with 5min TTL
|
|
```
|
|
|
|
### Mail DNS Setup
|
|
|
|
```bash
|
|
dnsctl mail-setup # Create MX, SPF, DMARC records
|
|
dnsctl mail-setup mail 10 # Custom hostname and priority
|
|
dnsctl dkim-add mail '<public-key>' # Add DKIM TXT record
|
|
```
|
|
|
|
### SSL Certificates
|
|
|
|
```bash
|
|
dnsctl acme-dns01 example.com # Issue cert via DNS-01 challenge
|
|
dnsctl acme-dns01 '*.example.com' # Wildcard cert via DNS-01
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- `curl` — HTTP client for API calls
|
|
- `openssl-util` — HMAC-SHA1 signing (OVH)
|
|
- `jsonfilter` — JSON parsing (OpenWrt native)
|
|
- `acme.sh` — Certificate issuance (optional, for DNS-01)
|
|
|
|
## Files
|
|
|
|
```
|
|
/etc/config/dns-provider UCI configuration
|
|
/usr/sbin/dnsctl CLI controller
|
|
/usr/lib/secubox/dns/ovh.sh OVH adapter
|
|
/usr/lib/secubox/dns/gandi.sh Gandi adapter
|
|
/usr/lib/secubox/dns/cloudflare.sh Cloudflare adapter
|
|
```
|