Available in v0.5.2
- Consistent nameserver records and authenticated DNS-01 challenge replication across multiple nodes.
- Private deployments with a local certificate authority and explicit backend CIDR allowlists.
- Certificate and key export for services that handle their own TLS, including ocserv.
Upgrading from v0.4.x? Follow the migration guide before replacing an existing installation. Migration guide
Use the public service
No account or domain registration is required. Your backend must be an allowed public IP running an HTTP service on port 80, reachable from DNSBox.
Replace 198.51.100.20 with your server's public IPv4 address:
https://198-51-100-20.dnsbox.ioDNS resolves the hostname to a DNSBox proxy. The proxy terminates HTTPS and forwards HTTP to the IP encoded in the hostname. It does not install a certificate on your server.
Let's Encrypt validates the hostname through DNS-01. The certificate is for that hostname, not for the raw IP address. The first TLS connection can take longer while a certificate is issued.
The browser-to-DNSBox connection uses HTTPS. The DNSBox-to-backend connection uses HTTP. WebSocket upgrades are supported.
An IPv6 backend can be encoded as 2a01-4f8-c17-b8f--1.dnsbox.io. A single hyphen represents a colon; a double hyphen represents ::.
Check DNS resolution, then HTTPS. Use your own reachable HTTP backend for this test:
dig +short 198-51-100-20.dnsbox.io
curl -v https://198-51-100-20.dnsbox.io/The DNS answer is the proxy address. A valid TLS connection and a successful backend HTTP response are separate checks.
Run inside a private network
Local TLS mode works without public DNS, port forwarding or Internet access. DNSBox creates its own certificate authority. Clients must trust that CA.
Example: DNSBox on 192.168.1.2, with HTTP backends in 192.168.1.0/24:
./dnsboxd --domain=home.arpa --ip=192.168.1.2 \
--tls-mode=local --allowed-cidrs=192.168.1.0/24 \
--dns-listen=192.168.1.2:53 --https-listen=192.168.1.2:443 \
--data-dir=/var/lib/dnsboxForward only the home.arpa zone from your LAN resolver to 192.168.1.2. DNSBox is authoritative for its zone; it is not a general recursive resolver.
Issue one local certificate to create the CA, then install /var/lib/dnsbox/ca/root.crt in each client's trusted CA store. Keep root.pem private. The deployment guide includes the bootstrap command.
For a backend at 192.168.1.50, open https://192-168-1-50.home.arpa. LAN clients need access to DNSBox's DNS and HTTPS ports; DNSBox needs access to the backend's HTTP port.
Self-host with Let's Encrypt
Use a domain or subdomain you control and delegate its DNS zone to your DNSBox nameserver. A single node can serve the zone; multiple nodes provide redundancy.
For public DNS-01 validation, allow incoming UDP 53 and TCP 53, plus outbound HTTPS and DNS resolution. Incoming port 80 is not required. Port 443 only needs to be reachable by your intended clients.
Private HTTP backends can use publicly trusted hostname certificates when DNS-01 validation is public. Allow those backends explicitly with --allowed-cidrs and configure DNS and routing for your clients.
With multiple nodes, configure the same nameserver roster and records on every node, plus mutual TLS for challenge replication. Every configured peer must acknowledge the challenge before issuance proceeds.
Linux, macOS and Windows release archives are available. The installer supports --no-systemd for manual startup or another supervisor. It does not disable your system resolver.
Certificates for ocserv and other services
The public service does not export its private keys. If your service needs certificate files, self-host DNSBox with a delegated zone you control.
Run --issue with an IP-encoded hostname under that zone. DNSBox writes a PEM certificate chain and private key to <data-dir>/certs, then exits. ACME issuance serves DNS but leaves HTTPS port 443 free.
Point that hostname directly to your service using an explicit A/AAAA record. For ocserv, configure server-cert and server-key. DNSBox's HTTP proxy does not implement OpenConnect or DTLS.
Arrange renewal and reload your service after the files change. A one-shot command does not renew certificates after it exits. Do not run two DNSBox processes against the same data directory.
Questions
Can I use private IPs with the public service?
No. The public proxy is for allowed public backends. Run your own instance with an explicit CIDR allowlist for private addresses.
What happens when my IP changes?
The IP is part of the hostname. Use a new hostname for the new IP; clients using the old name will still target the old address.
Does DNSBox prove ownership of the backend IP?
DNS-01 proves control of the DNS hostname. It does not verify ownership of the backend IP or the content served there.
Are certificates renewed automatically?
A running DNSBox service renews its managed certificates. Exported certificates need a renewal process and a reload of the service using them.
What if the backend is offline?
DNS and TLS may still work, but the proxy cannot return the application's content. Check the backend's HTTP listener, firewall and reachability.
Where can I report a problem?
Open a GitHub issue with the DNSBox version, deployment mode and relevant error messages. Remove private keys, tokens and other secrets.
Technical reference
- Authoritative DNS over UDP and TCP. Encoded hostnames resolve to the configured proxy address, not directly to the backend.
- Custom A, AAAA, CNAME, MX and TXT records; apex ALIAS records with background refresh.
- ACME DNS-01 or a local CA. Cluster replication carries temporary TXT challenges; certificate private keys remain on their own nodes.
- The management API binds to loopback only, at 127.0.0.1:8080 by default. Remote access uses an SSH tunnel.