Configuring OpenWRT DDNS for freedns.afraid.org

Overview

freedns.afraid.org is a DNS provider that offers free registration of subdomains on a long list of "public" (shared) top-level domains.
This is a more friendly alternative for use with Dynamic DNS clients, than many similar services, because it does not require a periodic "manual" intervention to renew a registered subdomain just to keep it active. Other such services seem to use the "manual renewal" as a tactic to "inconvenience" people into paying for their service.

Setting up the DDNS client in OpenWRT to monitor for changes in a dynamic IP address, and update freedns.afraid.org, is a little confusing, because the DDNS scripts do NOT use their "Direct URL" approach for IP updates.

Official Docs

The freedns.afraid.org docs describe settings that might work with some OpenWRT/DDNS configurations, but the DDNS client parameters didn't exactly work in my case. The other option, which uses cron and curl, might work, but isn't the usual/proper way to have OpenWRT handle DNS updates, and anything non-standard ends up burning extra time to document it well, or extra time later trying to remember how it is working.

"Direct URL" vs. DDNS Client

"Direct URL"

The biggest source of confusion while setting this up came from what freedns.afraid.org calls the "Direct URL." This URL has the path /dynamic/update.php?{authtoken}. It is intended to be called/fetched from anywhere within a NAT network, and the server extracts the "apparent" originating IP (outside all NAT layers) from the request, as the IP to associate with the subdomain name. The token embeds authentication information, and the reference to the subdomain, so the request requires no other parameters. This URL, and its "token" are NOT used by the OpenWRT DDNS client.

DDNS Client

freedns.afraid.org ALSO supports typical ddns client URLs with the path /nic/update, which accepts various URL parameters like hostname, and myip. THIS is what the OpenWRT DDNS client update script generates and uses. Authentication for this update option at freedns.afraid.org is HTTP basic, and requires the username:password for the freedns.afraid.org account, NOT the token, and NOT the FQDN of the subdomain (as the line option username 'yourhostname' in the docs incorrectly suggests).

DDNS IP resolution within NAT

One important aspect of the OpenWRT setup is whether the OpenWRT router is behind one or more NAT (network address translation) layers. If so, the default wan option for IP address source WON'T WORK, since it will discover an IP address that is still "hidden" within the private network. The DDNS client needs to reach outside the NAT/private network to get the "public facing" IP. See instructions below re: using the URL option instead.

How To

Now, with some of the confusing bits cleared up (let's hope), here are the steps to get things going.

1. Sign up an account at freedns.afraid.org
2. Decide on a suitable subdomain name, and add it to the account under one of the public domains controlled by freedns.afraid.org.
   • i.e. Click "Add" on https://freedns.afraid.org/subdomain/
   • Note: There are other options (transfer domain, etc.) too, but establishing a "registered" FQDN is the goal for this step.
3. If not already installed, add the DDNS client/service to OpenWRT.
   • See: https://openwrt.org/docs/guide-user/services/ddns/client
   • Optional: Also install the LuCI components to manage the DDNS service.
4. Add a DDNS "service" for freedns.afraid.org (using an example FQDN of mychosenname.example.com) (names/values in parens are for direct option entries in /etc/config/ddns without LuCI UI)
   • Lookup Hostname (lookup_host): mychosenname.example.com
   • DDNS Service Provider (service_name): Choose "afraid.org-basicauth"
   • Domain (domain): mychosenname.example.com
   • Username (username): freedns.afraid.org account username
   • Password (password): freedns.afraid.org account password
5. Switch the DDNS service's IP address source from Network to URL IP lookup (Advanced tab in LuCI). This uses the checkip.dyndns.com utility to reach all the way out from all internal network layers and echo back the "public" IP, instead of resolving the first-layer private address (i.e. when the "wan" side of an internal router is still within a NAT/private network).
   • IP address source (ip_source): Choose "URL" (web)
   • URL to detect (ip_url): http://checkip.dyndns.com

Notes

Private IP Error

Either the DDNS scripts, or maybe the freedns.afraid.org update service rejected a private/"non-routable" (i.e. RFC-1918) IP address with:

 WARN : Updating IP at DDNS provider failed...
...
ERROR : No or private or invalid IP '192.168.0.2' given! Please check your configuration

LuCI vs. afraid.org-v2-token

The DDNS client in OpenWRT has another DDNS Service provider option named afraid.org-v2-token. This sounds like it would support the "Direct URL" approach, but...

1. Best guess for where to fill in the token is:
   • Optional Parameter (param_opt)
   • Or possibly Optional Encoded Parameter (param_opt_encoded)
   • These were generated by LuCI, but not documented here
2. LuCI still requires 'username' and 'password', which are not used (so, presumably, they could be filled in with anything like notused).
3. The server response on an update indicates the (local/LAN) IP is still being included in the request, so the IP address source option must still be changed from Network to URL
4. Whatever request URL this configuration is constructing and sending to freedns.afraid.org, it does NOT seem to match the "Direct URL" format, and does not work.