Documentation

Set up a client

Each subdomain has its own tokens, created from its page in your account. Replace the subdomain, identifier and secret in the examples with those of the token; the subdomain page shows the same blocks already filled in.

API addresses

Address	Use
`api.nomadns.net`	DynDNS2 updates and ACME API, over IPv4 and IPv6
`api4.nomadns.net`	same routes, reachable over IPv4 only
`api6.nomadns.net`	same routes, reachable over IPv6 only
`/ip`	on these three addresses: returns the connection’s IP address as plain text, without authentication

DynDNS2 update

One request per subdomain, authenticated with HTTP Basic using the token’s identifier and secret:

GET https://api.nomadns.net/nic/update?hostname=subdomain.nomadns.net&myip=203.0.113.7,2001:db8::7
Authorization: Basic base64(identifier:secret)

myip accepts an IPv4 address, an IPv6 address or both separated by a comma. Without myip, the connection’s address is used for its family and the other family is left unchanged. Only public addresses are accepted.

Reply	Meaning
`good`	address changed and published by the primary server
`nochg`	same address, nothing is changed
`badauth`	identifier or secret refused (HTTP 401)
`notfqdn`	hostname missing or outside nomadns.net
`nohost`	unknown subdomain, or not the token’s subdomain
`numhost`	several names in hostname
`abuse`	subdomain or account suspended, or limit exceeded
`badagent`	method other than GET or POST
`911`	service error or slower publication than expected (HTTP 503); an address change stays recorded and the retry gets nochg

Limits: 120 requests per hour per subdomain, 60 address changes per day per subdomain (including web changes, which always remain available), 10 authentication failures per 10 minutes per IP address.

Settings by client

ddclient and acme.sh were checked against the API; the OpenWrt and Fritz!⁠Box settings follow their documentation.

ddclient

protocol=dyndns2
server=api.nomadns.net
ssl=yes
usev4=webv4, webv4=https://api4.nomadns.net/ip
usev6=webv6, webv6=https://api6.nomadns.net/ip
login=identifier
password='secret'
subdomain.nomadns.net

OpenWrt (ddns-scripts)

config service 'nomadns_v4'
    option enabled '1'
    option lookup_host 'subdomain.nomadns.net'
    option domain 'subdomain.nomadns.net'
    option username 'identifier'
    option password 'secret'
    option update_url 'https://[USERNAME]:[PASSWORD]@api.nomadns.net/nic/update?hostname=[DOMAIN]&myip=[IP]'
    option use_https '1'
    option cacert '/etc/ssl/certs'
    option ip_source 'network'
    option ip_network 'wan'

Fritz!Box

IPv4 only: the IPv6 address a Fritz!⁠Box provides is its own, not the served machine’s.

URL : https://api.nomadns.net/nic/update?hostname=<domain>&myip=<ipaddr>
Domaine / Domain : subdomain.nomadns.net
Utilisateur / User : identifier
Mot de passe / Password : secret

acme.sh (DNS-01)

ACMEDNS_BASE_URL is required: without it, acme.sh sends the identifier and secret to the public auth.acme-dns.io service.

export ACMEDNS_BASE_URL=https://api.nomadns.net
export ACMEDNS_USERNAME=acme-identifier
export ACMEDNS_PASSWORD='secret'
export ACMEDNS_SUBDOMAIN=subdomain
acme.sh --issue --dns dns_acmedns -d subdomain.nomadns.net

Check the result

The subdomain page shows the “Served” state when all three name servers publish the address. From a terminal:

dig +short A subdomain.nomadns.net @ns1.nomadns.net
dig +short AAAA subdomain.nomadns.net @ns1.nomadns.net