mirror of
https://github.com/hanzoai/dns.git
synced 2026-11-02 07:41:40 +00:00
120 lines
2.5 KiB
Plaintext
120 lines
2.5 KiB
Plaintext
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-HANZODNS" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIhanzodns\fP - REST API for dynamic DNS zone and record management.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
The hanzodns plugin exposes a REST API that allows creating, reading, updating, and deleting DNS zones and records at runtime. Records added through the API are immediately available for DNS resolution by CoreDNS.
|
|
|
|
.PP
|
|
The plugin runs a side-car HTTP server (default \fB\fC:8443\fR) alongside CoreDNS and stores records in-memory. The store is designed to be swappable for a persistent backend (e.g., PostgreSQL) in the future.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
hanzodns [ADDR]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBADDR\fP - the address to listen on for the HTTP API (default \fB\fC:8443\fR).
|
|
|
|
|
|
.SH "AUTHENTICATION"
|
|
.PP
|
|
Set the \fB\fCHANZO_DNS_API_KEY\fR environment variable to require Bearer token authentication on all API endpoints (except \fB\fC/api/v1/health\fR). When unset, all requests are allowed.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
Authorization: Bearer <HANZO\_DNS\_API\_KEY>
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "API ENDPOINTS"
|
|
.RS
|
|
.TS
|
|
allbox;
|
|
l l l
|
|
l l l .
|
|
\fBMethod\fP\fB Path\fP\fB Description\fP
|
|
GET \fB\fC/api/v1/health\fR Health check (no auth)
|
|
GET \fB\fC/api/v1/zones\fR List all zones
|
|
POST \fB\fC/api/v1/zones\fR Create a zone
|
|
GET \fB\fC/api/v1/zones/{zone}\fR Get zone details
|
|
DELETE \fB\fC/api/v1/zones/{zone}\fR Delete a zone
|
|
GET \fB\fC/api/v1/zones/{zone}/records\fR List records in a zone
|
|
POST \fB\fC/api/v1/zones/{zone}/records\fR Create a record
|
|
GET \fB\fC/api/v1/zones/{zone}/records/{id}\fR Get a record
|
|
PATCH \fB\fC/api/v1/zones/{zone}/records/{id}\fR Update a record
|
|
DELETE \fB\fC/api/v1/zones/{zone}/records/{id}\fR Delete a record
|
|
.TE
|
|
.RE
|
|
|
|
|
|
.SH "RECORD TYPES"
|
|
.PP
|
|
A, AAAA, CNAME, MX, TXT, SRV, NS, SOA, CAA
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Enable the API on the default port:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
hanzodns
|
|
forward . 8.8.8.8
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Listen on a custom port:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
hanzodns :9443
|
|
forward . 8.8.8.8
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Create a zone and record via curl:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
curl \-X POST http://localhost:8443/api/v1/zones \\
|
|
\-H "Authorization: Bearer $HANZO\_DNS\_API\_KEY" \\
|
|
\-H "Content\-Type: application/json" \\
|
|
\-d '{"zone": "example.com"}'
|
|
|
|
curl \-X POST http://localhost:8443/api/v1/zones/example.com/records \\
|
|
\-H "Authorization: Bearer $HANZO\_DNS\_API\_KEY" \\
|
|
\-H "Content\-Type: application/json" \\
|
|
\-d '{"name": "www", "type": "A", "content": "1.2.3.4", "ttl": 300}'
|
|
|
|
dig @localhost www.example.com A
|
|
|
|
.fi
|
|
.RE
|
|
|