From 5fb97ff9c3730eced61c73d1cd7a66a059f08802 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 15:07:06 +0200 Subject: [PATCH 1/2] docs(ddns): add DigitalOcean example and split DNS note --- ddns.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/ddns.rst b/ddns.rst index 9807e179..c5b55ee2 100644 --- a/ddns.rst +++ b/ddns.rst @@ -85,6 +85,26 @@ Additional notes: - Consider enabling logging for the DDNS service to monitor updates and troubleshoot any issues. - Some providers may offer advanced features like wildcards and subdomain updates. Explore these options based on your specific needs. +Example: DigitalOcean (DO) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example matches the running ``fw.gs.nethserver.net`` setup on NethSecurity. +The DigitalOcean API token is intentionally redacted; replace it with your own token. :: + + uci set ddns.do=service + uci set ddns.do.service_name='digitalocean.com-v2' + uci set ddns.do.lookup_host='fw.gs.nethserver.net' + uci set ddns.do.domain='gs.nethserver.net' + uci set ddns.do.username='fw' + uci set ddns.do.password='REDACTED_DIGITALOCEAN_API_TOKEN' + uci set ddns.do.param_opt='1810744085' + uci set ddns.do.enabled='1' + uci set ddns.do.interface='wan' + uci set ddns.do.ip_source='network' + uci set ddns.do.ip_network='wan' + uci commit ddns + /etc/init.d/ddns restart + Example: afraid.org (FreeDNS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -135,6 +155,20 @@ The domain is named "nstest1.freeddns.it" and the username and password are "nst uci commit ddns /etc/init.d/ddns restart +Split DNS +^^^^^^^^^ + +Some deployments publish the same hostname inside the LAN and on the public internet. +If ``lookup_host`` resolves to a private address on the firewall itself, DDNS can compare the public WAN IP against the internal answer and keep retrying even when the provider update succeeded. + +The recommended fix is to make DDNS query an external resolver for the lookup instead of the local split-DNS answer. For example:: + + uci set ddns.do.dns_server='1.1.1.1' + uci commit ddns + /etc/init.d/ddns restart + +This keeps split DNS for LAN clients while the DDNS client validates the public record. + Using Luci ---------- From fa61d4fc69c11d6eef6680bbd4df3ed8b56bf0a3 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 15:14:19 +0200 Subject: [PATCH 2/2] docs(ddns): generalize examples and split DNS section --- ddns.rst | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/ddns.rst b/ddns.rst index c5b55ee2..377fc154 100644 --- a/ddns.rst +++ b/ddns.rst @@ -88,16 +88,16 @@ Additional notes: Example: DigitalOcean (DO) ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following example matches the running ``fw.gs.nethserver.net`` setup on NethSecurity. +The following example uses the fictional ``firewall.example.net`` setup on NethSecurity. The DigitalOcean API token is intentionally redacted; replace it with your own token. :: uci set ddns.do=service uci set ddns.do.service_name='digitalocean.com-v2' - uci set ddns.do.lookup_host='fw.gs.nethserver.net' - uci set ddns.do.domain='gs.nethserver.net' - uci set ddns.do.username='fw' + uci set ddns.do.lookup_host='firewall.example.net' + uci set ddns.do.domain='example.net' + uci set ddns.do.username='firewall' uci set ddns.do.password='REDACTED_DIGITALOCEAN_API_TOKEN' - uci set ddns.do.param_opt='1810744085' + uci set ddns.do.param_opt='21694203' uci set ddns.do.enabled='1' uci set ddns.do.interface='wan' uci set ddns.do.ip_source='network' @@ -105,6 +105,21 @@ The DigitalOcean API token is intentionally redacted; replace it with your own t uci commit ddns /etc/init.d/ddns restart +The relevant DigitalOcean fields are: + +- ``domain``: the domain managed in DigitalOcean +- ``username``: the hostname label to update +- ``password``: the personal access token +- ``param_opt``: the DNS record ID for that hostname + +To list the records and find the ID, run:: + + curl -X GET -H 'Content-Type: application/json' \ + -H "Authorization: Bearer TOKEN" \ + "https://api.digitalocean.com/v2/domains/DOMAIN/records" + +Replace ``TOKEN`` and ``DOMAIN`` with your own values. + Example: afraid.org (FreeDNS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -156,7 +171,7 @@ The domain is named "nstest1.freeddns.it" and the username and password are "nst /etc/init.d/ddns restart Split DNS -^^^^^^^^^ +--------- Some deployments publish the same hostname inside the LAN and on the public internet. If ``lookup_host`` resolves to a private address on the firewall itself, DDNS can compare the public WAN IP against the internal answer and keep retrying even when the provider update succeeded.