🔖
onifast-dns
Authoritative-only DNS server built on miekg/dns with SQLite persistence.
DNS Server
Authoritative Only
SQLite Backed
onifast-dns is a lightweight, authoritative-only DNS server built on the high-performance github.com/miekg/dns library. It is designed to be strictly authoritative — serving only the zones it knows about, and immediately returning REFUSED for any domain outside its authority. This prevents DNS amplification attacks and avoids acting as an open resolver.
Key Capabilities
Self-Contained Security
Prevents open resolver relay vulnerabilities by serving only locally configured domains.
SQLite Persistence
Records are stored in a fast SQLite database and managed instantly via the Onifast panel.
Wildcard Support
Full dynamic wildcard subdomain processing for multi-tenant and SaaS host schemes.
Resolution Logic
Query resolution follows a strict three-step waterfall:
- Exact Match — Look up the queried name (with and without trailing dot) in the SQLite
dns table.
- Wildcard Match — If no exact match is found, walk up the label hierarchy looking for
*.parent.zone entries.
- Authority Check — If the parent zone is owned by this server, returns
NXDOMAIN. If the zone is unknown, returns REFUSED.
Important Authority Rule
The server never forwards queries externally. It is strictly authoritative for the domains registered in the panel, acting as a secure and fast resolver hub.
Port Allocation
| Port |
Protocol |
Description |
| 53 |
UDP |
Standard DNS queries (low-latency, primary path) |
| 53 |
TCP |
DNS over TCP (used for zone transfers, large responses) |
Zone Lifecycle
When a domain is added via the control panel, initZone(domain) is called automatically. This initializes the default record set:
| Record Host |
Type |
Value |
example.com. |
NS |
ns1.yourserver.com. |
example.com. |
NS |
ns2.yourserver.com. |
example.com. |
A |
Server Public IP |
www.example.com. |
A |
Server Public IP |
When a domain is deleted from the panel, deleteZone(domain) cleans up the records completely. Individual records (MX, TXT, CNAME, etc.) are managed in the DNS editor panel.
Wildcard Support
Wildcard records (e.g. *.example.com) are fully supported. If no exact match is found for a query like sub.example.com, the server looks for *.example.com and substitutes the queried name into the answer. This enables dynamic subdomains for SaaS schemes.
# Wildcard A record for all subdomains
*.example.com. 3600 IN A 203.0.113.5
Supported Record Types
| Type |
Example Value |
Description |
| A |
203.0.113.5 |
Standard IPv4 address |
| AAAA |
2001:db8::1 |
Standard IPv6 address |
| CNAME |
alias.example.com. |
Canonical name alias (requires trailing dot) |
| MX |
10 mail.example.com. |
Mail exchange (priority + hostname) |
| TXT |
"v=spf1 include:... ~all" |
Text record (SPF, DKIM, site verifications) |
| NS |
ns1.example.com. |
Nameserver delegation links |
| SOA |
Auto-generated on zone init |
Start of Authority parameters |
All records have a configurable TTL (default: 3600 seconds).
Database Schema
DNS records are stored at /home/root/onifast/config/onifast-dns.db in the central directory:
CREATE TABLE dns (
bucket TEXT, -- e.g. 'Records'
domain TEXT, -- e.g. 'example.com.' or '*.example.com.'
value TEXT, -- JSON array of DNSRecord objects
owner TEXT, -- panel username
PRIMARY KEY (bucket, domain)
);
Example JSON value stored inside the value column:
[
{"name": "example.com.", "type": "A", "value": "203.0.113.5", "ttl": 3600},
{"name": "example.com.", "type": "MX", "value": "10 mail.example.com.", "ttl": 3600}
]
Central Config File
Central configuration values are read from /home/root/onifast/config/serverconfig.json, falling back to users/root.json:
| Key |
Description |
Default |
bind_config.ns1 |
Primary nameserver hostname (added to all zones) |
ns1.example.com |
bind_config.ns2 |
Secondary nameserver hostname link |
ns2.example.com |
bind_config.server_ip |
Public IP automatically mapped to A records on initialization |
127.0.0.1 |
Systemd Service Configuration
The service is managed as a standard background daemon:
[Unit]
Description=Onifast DNS Server
After=network.target
[Service]
ExecStart=/home/root/go/cmd/onifast-dns/onifast-dns
Restart=always
[Install]
WantedBy=multi-user.target
Manual Verification Checks
Execute the following commands to check direct DNS resolution performance on the local loopback:
# Test A record
dig @localhost example.com A
# Test MX record
dig @localhost example.com MX
# Test wildcard resolution
dig @localhost subdomain.example.com A
# Test NXDOMAIN for unknown subdomain of known zone
dig @localhost nonexistent.example.com A
# Expected: NXDOMAIN (AUTHORITY section)
# Test REFUSED response for unknown external zone
dig @localhost google.com A
# Expected: REFUSED