DNS API standard or specification

I'm developing a Dynamic DNS (DDNS) server. Lightweight and open source so that others volunteers can easily deploy their own in their country to make web more robust.
And I want to give a simple instruction to users to issue certs.
The key feature would be a DNS SEC support and to implement this a client must sign it's A record with the private key and upload the DS file to my DDNS server.
So I need an API endpoint to update records.
But also I want to support the certbot, so I need the same or similar API endpoint for it.

The problem is that it looks like there is no any REST or any other http based API for DNS updates.
In order to keep all simple I'm going to choose one supported API of a DNS hosting and just implement it.
Could you please recommend me which one is more stable or popular or well-designed.

The certbot has out of the box support of OVH and it's API that looks fine.
But can I specify my custom API url? Looks like can't and this makes the existing plugin useless for me.
Maybe you can make it configurable?

I saw that there is a 3rd party plugin for PowerDNS which also have a REST like API.
It should support any api endpoints, but it's intended for administrator and not for public usage.
But I wish to my non-experienced clients not to install anything additionally.

As an additional constraint I need to support WiFi routers with OpenWrt.
And the built-in wget there (currently) can make only GET or limited POST request.
That's why DDNS providers uses a GET request to update an IP for a subdomain.
I saw sources of a DuckDNS plugin and there was also a GET call to create a TXT record.
Maybe some default plugins also uses the GET requests then I may use that API instead of OVH.
How often the certbot is used with the DuckDNS? Maybe it make sense to include it out of the box to make the https configuration easier for unexperieced users who just want to get acces to their IP camera.

Generally speaking your team and community have a reputation to ask main DNS providers to make a generalized and standardized API.
Maybe you can start the process of negotiation with mist used DNS hostings?

Also I saw there is some Lexicon project that tries to handle all APIs. Does the certbot using it? If not then why?

Thank you for any comments.

P.S. my dddns server GitHub - yurt-page/go-ddnsd: Dynamic DNS server with DynDNS API support and automatic registration

1 Like

RFC2136 is the standard for dynamic DNS updates and is supported by pretty much every ACME client.

I’m not aware of a REST based standard but it’s an interesting idea!


The nsupdate looks weird for me because as far I understood it sends a DNS message over (unstable) UDP with a special opcode Update. It also needs for TSIG auth.
The nsupdate on openwrt takes more that 50kb which is kind of a lot. And it's not installed by default. Anyway the certbot is too heavy for most OpenWrt routers but acme.sh works fine.
I need the REST and ideally with GET only

1 Like

then you will need to make one


I haven't read your client, and I'm only going by what would seem to be the simplest solution [in my head].
Given this train of thought:

  • the DDNS operator has access to update the DNS zone.
  • the DDNS operator owns the DNS zone.
  • external users would have to create an account to manage their entry in operators' zone.
  • that creation would likely occur via HTTPS
  • why not use HTTPS to continue the service?
  • client does a GET|PUT|HEAD|Whatever to:
    [where any access is allowed]
    [where only authenticated access is allowed]
  • in either case, the source IP is retrieved from the HTTPS request and used to update that account entry [given a verified acct/pw]

So, the client side only needs a cron type scheduled entry to:
curl -I HTTPS://public.DDNS-service.example.com/{account#}/{secured-PW}

In any case, I would like to hear more about your client [will go their soon] and your progress.
I really do think this is something that many people would enjoy doing within their own zones.


DDNS (like duckdns, no-ip etc) is sometimes a little different to a standard hosted DNS provider and usually has more limited functionality.

How you shape the API depends a little on scale - eg how many zones will your query return (can it return 1000s, does it require paging).

For client examples in Go (which GitHub - yurt-page/go-ddnsd: Dynamic DNS server with DynDNS API support and automatic registration seems to be written in) check out DNS Providers :: Let’s Encrypt client and ACME library written in Go.

Ultimately your API will likely have some necessary differences, in which case I would also suggest that you write a certbot plugin, a lego provider and possibly a Posh-ACME plugin

An alternative approach is to implement the acme-dns protocol (which is just a couple of endpoints) and url encoded basic auth to authenticate ( e.g. https://user:key@api.domain.com/) as many existing acme-dns clients support this and you would get instant coverage.


Thank you for you input. That cleared a lot for me and motivated to move forward.

@rg305 If I understood your idea correctly we may extend DNS-Over-HTTP endpoint to support PUT method with update of DNS records. We may also use a PATCH method for a partial update/add of one record.
As usual with REST we can't always nicely match resource (e.g. file) operation to RPC. But still the idea is worth to be considered.

@webprofusion thank you for letting me know about the acme-dns protocol. It's exactly what I'm looking for.
It has a good README acme-dns/README.md at master · joohoi/acme-dns · GitHub
And it's author wrote a good article on the topic A Technical Deep Dive: Securing the Automation of ACME DNS Challenge Validation | Electronic Frontier Foundation

It already have a certbot plugin GitHub - acme-dns/acme-dns-client: A client software for https://github.com/joohoi/acme-dns but it must be installed manually and this makes it hard to use for unexperienced users. It must be included to the certbot out of the box. It's written in Go while the cerbot uses Python and this makes it's harder to make it a part of basic package. Maybe we can rewrite it to Python. UPD GitHub - joohoi/acme-dns-certbot-joohoi: Certbot client hook for acme-dns

Maybe instead we may add it's support to the Lexicon library which is written in Python and use it by the certbot.

The acme-dns is supported by acme.sh

Also it's not supported yet by Lego which is Golang library Welcome :: Let’s Encrypt client and ACME library written in Go.
UPD it's supported lego/providers/dns/acmedns at master · go-acme/lego · GitHub

Unfortunately it uses a POST request with JSON to create records. As I mentioned before this makes a problem for routers with dynamic dns.

So I checked DDNS providers and from what I saw we have not that much chooses here.

  1. Dyn.com is a first and most supported DDNS provider. But it's paid and expensive and not open source. The DynDNS uses a GET /nic/update?domains=example.com&myip= request to update the A record of a domain. But they have a very bad API to create subdomains which uses sessions. Here is how it's implemented in the acme.sh acme.sh/dns_dyn.sh at master · acmesh-official/acme.sh · GitHub
  2. (probably) most popular free DDNS is DuckDNS.org and their api for creating a TXT record is GET based and implementation is simple acme.sh/dns_duckdns.sh at master · acmesh-official/acme.sh · GitHub
  3. Dinu.com is less popular and badly maintained (I still waiting an email for registration) but it has kind of rich REST based API API | Dynu and again widely supported. So it uses POST and DELETE methods which is a problem for routers. See acme.sh/dns_dynu.sh at master · acmesh-official/acme.sh · GitHub

So to summarize I see that the DuckDNS is a best option. It's already supported by the Lego but not by the Lexicon. For routers manufactures it will be easier to add it's support.
I going to discuss with the acme-dns author Joona Hoikkala the idea to just switch it to use the DuckDNS API.
UPD Support of DuckDNS.org API · Issue #323 · joohoi/acme-dns · GitHub
This will makes it immediately supported by many existing clients.

Anyway, even today we should include the DuckDNS plugin to the cerbot core. It's already have a Python plugin and even some snap package. This is a really popular DNS hosting. And additionally I just need an option to override API base URL from the official DuckDNS.org to a custom. This looks like an easy thing to do and will help a lot for many people who have an IP camera at home or making a self hosting.

Please tell me if I should rise an issue in Github for this.

1 Like

Yes, it updates DNS using DNS standards which seems perfectly logical to me. Those standards can be used over UDP or TCP. I'm not sure why you'd say UDP is unstable though. It's stable enough to power basically the entire Internet DNS infrastructure.

TSIG auth is only required of the DNS server is configured to require it. Many configurations simply use IP whitelisting.

I wouldn't personally use DuckDNS as a model. The TXT record support you need to satisfy ACME challenges has the limitation that you can only create a single TXT record at a time (the value for which is cloned to all of the domains associated with your account). That means you can't get a wildcard cert that also contains the apex domain name without validating your challenges serially instead of in parallel like most other providers.


This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.