Page content


A simplified DNS server with a RESTful HTTP API to provide a simple way to automate ACME DNS challenges. Sounds promising, right ? Let’s give try ;)


fireup a new OpenBSD VM

  • let’s do it in London.
  • ip:

patch, update, add go

doas su -
pkg_add -Vu
pkg_add go

clone repo and build acme-dns

cd /root
git clone
cd acme-dns
export GOPATH=/tmp/acme-dns
go build
cp acme-dns /usr/local/sbin/

Create Selfsign Cert

the RESTful API need’s a Cert. Let’s use a selfsigned Cert for this demonstration.

cd /etc/ssl
openssl req -nodes -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 356

Prepare Folders

mkdir -p /etc/acme-dns /var/lib/acme-dns

Build Config File

VM IP: FQDN: london.your.domain


cat << 'EOF' > /etc/acme-dns/config.cfg
# DNS interface. Note that systemd-resolved may reserve port 53 on
# In this case acme-dns will error out and you will need to define the listening interface

# for example: listen = ""
listen = ""

# protocol, "both", "both4", "both6", "udp", "udp4", "udp6" or "tcp", "tcp4", "tcp6"
protocol = "both"

# domain name to serve the requests off of
domain = ""

# zone name server
nsname = "london.your.domain"

# admin email address, where @ is substituted with .
nsadmin = "YOUR@EMAIL.NET"

# predefined records served in addition to the TXT
records = [
    # domain pointing to the public IP of your acme-dns server 
    " A",

    # specify that will resolve any * records
    " NS",

# debug messages from CORS etc
debug = false

# Database engine to use, sqlite3 or postgres
engine = "sqlite3"
connection = "/var/lib/acme-dns/acme-dns.db"

# listen ip eg.
ip = ""

# disable registration endpoint
disable_registration = false

# listen port, eg. 443 for default HTTPS
port = "443"

# possible values: "letsencrypt", "letsencryptstaging", "cert", "none"
tls = "cert"

# only used if tls = "cert"
tls_cert_privkey = "/etc/ssl/key.pem"
tls_cert_fullchain = "/etc/ssl/cert.pem"

# only used if tls = "letsencrypt"
acme_cache_dir = "api-certs"

# optional e-mail address to which Let's Encrypt will send expiration notices for the API's cert
notification_email = ""

# CORS AllowOrigins, wildcards can be used
corsorigins = [

# use HTTP header to get the client ip
use_header = false

# header name to pull the ip address / list of ip addresses from
header_name = "X-Forwarded-For"

# logging level: "error", "warning", "info" or "debug"
loglevel = "debug"

# possible values: stdout, TODO file & integrations
logtype = "stdout"
logformat = "text"

allow FW Port 53 TCP/UDP

pass in log quick proto udp from any to (self) proto 53

run acme-dns

root@london.your.domain# acme-dns                                                                                         
INFO[0000] Using config file                             file=/etc/acme-dns/config.cfg
INFO[0000] Connected to database                        
DEBU[0000] Adding new record to domain                   domain=london.your.domain. recordtype=A
DEBU[0000] Adding new record to domain                   domain=london.your.domain. recordtype=NS
DEBU[0000] Adding new record to domain                   domain=london.your.domain. recordtype=SOA
INFO[0000] Listening HTTPS                               host=""
INFO[0000] Listening DNS                                 addr="" proto=udp
INFO[0000] Listening DNS 

Update DNS Zone

add the following Lines to your DNS Server A
play NS

on some Clients

Register Subdomain

# Set Nameserver
curl -s -k -X POST "https://${ns}/register" |tee .register.json |jq
user=$(cat .register.json |jq -r '.username')
key=$(cat .register.json |jq -r '.password')
sub=$(cat .register.json |jq -r '.subdomain')

Set Token

curl -k -X POST -H "X-Api-User: ${user}" -H "X-Api-Key: ${key}" -d '{"subdomain": "'${sub}'", "txt": "___validation_token_received_from_the_ca___"}' https://${ns}/update

Verify Token

dig +short -t txt @${ns} ${sub}.${ns}

sha256: f5f89ee30a52096efca247bccf49a40d12f813e99f1143c5ab286aebcbde167b