DDNS Client

If you want to set up a DDNS Server instead, please see ddns.server.

Tested with:
o OpenWrt Attitude Adjustment 12.09
o

OpenWrt Barrier Breaker r37816

Introduction
DDNS stands for Dynamic DNS. Simply put, using this service gives a name to your ip. So if
you're hosting something on your line, people wouldn't have to bother typing your IP. They can
just type in your domain name! It also helps when your ip changes. Users won't need to discover
what your new ip is, they can simply type your domain name.
This guide will help you configure your ddns service, so that your router auto-updates your ip to
your ddns. The simplest method possible would be through LuCI (the default webUI for
openwrt).

Requirements
First of all, you'll need to pick and register a DNS name with a compatible DDNS service. Note
the DNS name, your service username and password for use below.
Here is a list of suggested DDNS providers.

http://freedns.afraid.org free
http://noip.com free but requires annoying account confirmation every 30 days

http://changeip.com

http://duckdns.org

http://system-ns.com

https://dns.he.net/

http://dnsdynamic.org

http://zoneedit.com
support.)

http://dyndns.org non-free except if you donated in 1998-2001. 30-day free trial needs
credit card number.

free
free - generated config on site
free

free - if you have your own domain name, hurricaneelectricfreedns.

free
non-free (dns update by https required, curl needed. See SSL

http://dyndns.fr

non-free

Any other service that can update when some URL is accessed. The script is quite
versatile.

For a longer list of additional DDNS providers, see:

http://www.dmoz.org/Computers/Internet/Protocols/DNS/DNS_Providers/Dynamic_DNS
/
http://dnslookup.me/dynamic-dns/

Using LuCI
Step 1: Install the Packages
Login into your router through your browser. Go to Administration (top right) > System (top left)
> Software > Update Package Lists Let it update, go back to Software. Find luci-app-ddns and
install the package.
Installing the package luci-app-ddns will automatically install the package ddns-scripts,
which contains the scripts that actually update the dynamic DNS name (see below).
After luci-app-ddns is installed, just press any other link on the Openwrt LuCI WebUI, and the
page will refresh itself and Dynamic DNS will appear under Services > Dynamic DNS. If those
tabs don't show up, run /etc/init.d/uhttpd restart or reboot the router.
Beginning ddns-scripts Version 1.0.0-23 you need to enable ddns service in "System"-"Startup"
or run: /etc/init.d/ddns enable to enable updates being send on reboot and hotplug events.

Step 2: Configuration
In LuCI, go to Services > Dynamic DNS.
There is a default configuration called "MYDDNS" ready to edited.
Variable

Description

Example
check this to enable
this configuration

Enable

Self-explanatory

Event interface

The DDNS scripts use the Linux hotplug events

system. When this specified network interface
comes up, a related ifup hotplug event will cause
DDNS script to start to monitor (and update) the wan
external IP address of . Select the WAN interface
that will have the external IP address to use in the
DDNS registration.

Which DDNS online service do you use? Choose

one
The DNS name to update (this name must already
Hostname
be registered with the the DDNS service)
Username
Username of your DDNS service account
Password of your DDNS service account (ensure
Password
this password does not have "$1" or $ with any
number following in it, as this breaks the script)
This tells the script how to determine your
Source of IP address
interface external IP address. See below for a
description.
This will be named based on the section of
"Source of IP address". Select the network,
Network/Interface/URL
interface physical name, or type in the URL to use
to determine the external IP address.
Self Explanatory. Checks below 5 minutes make
Check for changed IP
no sence because from testing, it takes this time
every
until the global DNS servers be in sync
Check-time unit
The unit for the value above
Even if the detected external IP address has not
Force update every
changed, update the DDNS name anyway after
this time interval
Force-time unit
Unit for the value above
Service

dyndns.org
your.domain.name
yourusername
yourpassword
Usually "network"

Usually "wan"

10
min
72
h

Click "Save & Apply" to save changes.

Further details

A full list of supported settings (some not supported by LuCI WebUI) and their
description you will find in UCI documentation.
freedns.afraid.org specific settings:
o

put the authorisation token from the update url (the part after
http://freedns.afraid.org/dynamic/update.php?) in the password field.

DO enter the host into the Hostname field. Although it is not used for the update,
it is used to check the host's current IP address (via nslookup).

Source of IP address ("ip_source" in the configuration file)

o

The "ip_source" option can be "network", "interface", "script" or "web", with

"network" as the default

If "ip_source" is "network" you specify a network section in your /etc/network

config file (e.g. "wan", which is the default) with the "ip_network" option. If you
specify "wan", you will update with whatever the ip for your wan is.

If "ip_source" is "interface" you specify a hardware interface (e.g. "eth1") and

whatever the current ip of this interface is will be associated with the domain
when an update is performed.

If "ip_source" is "script" you specify a script to obtain ip address. The "ip_script"

option should contain path to your script. This option is not available through the
LuCI web interface.

The last possibility is that "ip_source" is "web", which means that in order to
obtain our ip address we will connect to a website (specified in the URL field),
and use the first valid ip address listed on that page. Use this option if the
OpenWrt device is behind a NAT device and does not have a real external IP
address assigned to the WAN interface being monitored. The correct URL will
depend on the DDNS service being used. Check with the service's documentation
to determine if they offer this feature and, if so, what the correct URL is.

For the DynDNS service, the URL is http://checkip.dyndns.org

Multiple URLs can be used by separating the entries with a space.

Step 3: Start ddns-scripts

Normally, the DDNS scripts are automatically started through a hotplug event. The very
first time they are configured, there is no ifup event to start them.
The simplest option is to reboot the router. This will automatically start the scripts as part
of the normal interface startup process.

If a reboot should be avoided, the scripts can be started manually by generating a hotplug
event from the command line (see below for details)

Beginning ddns-scripts Version 1.0.0-23 you need to enable ddns service in

"System"-"Startup" to enable updates being send on reboot and hotplug events.

You can also start/stop/restart the service without reboot or generating a hotplug event.

Step 4: You're done!

If the wan interface changes its address, the DDNS account is updated automatically.
Additionally, an unconditional update is sent periodically. The interval is specified by the
force update option.

Additional DDNS registration entries

In LuCI, go to Services > Dynamic DNS.

Use the text entry box and "Add" button to add additional DDNS configurations
o Do not use a - character in the DDNS configuration name

Using ddns-scripts directly

The ddns-scripts package can be installed and used on its own without luci-app-ddns. No web
GUI will be available in this case. This section describes how to use the command line to use
ddns-script directly.

Step 1: Installation
Install the ddns-scripts package.
opkg update
opkg install ddns-scripts

Step 2: Configuration
The configuration is stored in /etc/config/ddns which contains more thorough documentation.
In order to enable Dynamic DNS you need at least one section, and in that section the enabled
variable must be set to "1".
Each section represents an update to a different service. This sections specifies several things:

service (dyndns.org, etc.)

domain (set this to all.dnsomatic.com for DNS-o-Matic)

username

password (sometimes it is the api token, not your login password)

ip_source (wan, eth0, web)

Optionally, the following may be specified:

update_url (needed if the service isn't supported by /usr/lib/ddns/services)

check_interval

force_interval

Use the check_interval variable to specify how often to check whether an update is necessary,
and the force_interval variable to specify how often to force an update. Specify the units for
these values with the check_unit and force_unit variables. Units can be "days", "hours",
"minutes" or "seconds". The default value for check_interval is "600", and the default
value for check_unit is "seconds" (check_interval = 10 minutes). The default value for

force_interval

is "72", and the default value for force_unit is "hours" (force_interval =

72 hours).
Default configuration
This is the default configuration in /etc/config/ddns as of OpenWrt Attitude Adjustment 12.09.
config service "myddns"
option enabled
option interface

"0"
"wan"

option
option
option
option

service_name
domain
username
password

"dyndns.org"
"mypersonaldomain.dyndns.org"
"myusername"
"mypassword"

option
option
option
option
option
option

force_interval
force_unit
check_interval
check_unit
retry_interval
retry_unit

"72"
"hours"
"10"
"minutes"
"60"
"seconds"

#option ip_source
#option ip_network

"network"
"wan"

#option ip_source
#option ip_interface

"interface"
"eth0.1"

#option ip_source
#option ip_script

"script"
"path to your script"

option ip_source
option ip_url

"web"
"http://checkip.dyndns.com/"

#option update_url
"http://[USERNAME]:
[PASSWORD]@members.dyndns.org/nic/update?hostname=[DOMAIN]&myip=[IP]"

Configuration using the uci program

A short example for a dyndns.org service to configure via UCI CLI:
root@OpenWrt:~#
root@OpenWrt:~#
root@OpenWrt:~#
root@OpenWrt:~#
root@OpenWrt:~#
root@OpenWrt:~#

uci
uci
uci
uci
uci
uci

set ddns.myddns.enabled=1
set ddns.myddns.domain=host.dyndns.org
set ddns.myddns.username=
set ddns.myddns.password=
set ddns.myddns.enabled=1
commit ddns

Configuration for duckdns.org

Add Duck DNS to ''services''

The reason you want to add Duck DNS to the services file is because this will allow you to
configure other ddns services if needed, and it allows for proper https usage with curl. Edit
/usr/lib/ddns/services and add this to the end of the file:
# Duck DNS
"duckdns.org"
"http://www.duckdns.org/update?
domains=[DOMAIN]&token=[PASSWORD]&ip=[IP]"
Duck DNS https (SSL) Support

duckdns.org uses a CA that is either self-signed, or not listed in the Curl CA bundle. curl will
throw error 60 when trying to update over https. The only way I was able to get curl to update
Duck DNS over https was to have curl ignore certificate checks with curl -k. Modify
/usr/lib/ddns/dynamic_dns_updater.sh as follows:
Find this string of code:
retrieve_prog="${retrieve_prog}--cacert $cacert "

Replace it with this:

retrieve_prog="${retrieve_prog}-k "

Find this string of code:

retrieve_prog="${retrieve_prog}--capath $cacert "

Replace it with this:

retrieve_prog="${retrieve_prog}-k "
Duck DNS ddns-scripts ''config'' example

Uncomment use_https and cacert if you want to use https (SSL).

config service
option
option
option
option
option
option
option
option
option
option
option
option
#option
#option

"myddns"
enabled
interface
service_name
domain
username
password
force_interval
force_unit
check_interval
check_unit
ip_source
ip_url
use_https
cacert

"1"
"wan"
"duckdns.org"
"DOMAIN"
"LEAVE BLANK"
"xxxxxxx-your-token-xxxx-xxxxxxxxxxxx"
"12"
"hours"
"10"
"minutes"
"web"
"http://wtfismyip.com/text"
"1"
"/etc/ssl/certs/cacert.pem"

Configuration for namecheap.com

An example for a namecheap.com domain with an A-record with name '@'.
config service 'myddns'
option enabled '1'

option interface 'wan'

option force_interval '72'
option force_unit 'hours'
option check_interval '10'
option check_unit 'minutes'
option retry_interval '60'
option retry_unit 'seconds'
option service_name 'namecheap.com'
option domain 'yourdomain.info'
option username '@'
option password 'xxxxxxx-your-token-xxxx-xxxxxxxxxxxx'
option ip_source 'network'
option ip_network 'wan'
#option use_https '1'
#option cacert '/etc/ssl/certs/cacert.pem'

Note that with the namecheap protocol, the username option is translated to the host argument
in the update request. Therefore, it should be the hostname on the DNS record, not the username
that you use to log into the namecheap.com site. In this example, the script will update the '@'
(full domain) DNS A-record. To update a subdomain A-record, enter the name of the subdomain
instead. To get your password, log into the namecheap.com site, enter the management console
for the domain, and click the Dynamic DNS menu option.
Make a record for each subdomain. Using Luci, enter a label for the subdomain into the Add
field (near lower left of page)and click the (+), or hand edit the /etc/config/ddns file and add a
new stanza.
Example /etc/config/ddns records to update two subdomains at namecheap:
config service
option
option
option
option
option
option
option
option
option
option
option
option
option
option

'myddns'
interface 'wan'
force_unit 'hours'
check_interval '20'
check_unit 'minutes'
retry_interval '60'
retry_unit 'seconds'
password 'YourNamecheapDDNSpassword'
enabled '1'
ip_source 'interface'
ip_interface 'pppoe-wan'
service_name 'namecheap.com'
force_interval '72'
domain 'Your.Domain'
username 'www'

config service
option
option
option
option
option
option
option

'mail'
interface 'wan'
force_unit 'hours'
check_interval '20'
check_unit 'minutes'
retry_interval '60'
retry_unit 'seconds'
password 'YourNamecheapDDNSpassword'

option
option
option
option
option
option
option

enabled '1'
ip_source 'interface'
ip_interface 'pppoe-wan'
service_name 'namecheap.com'
force_interval '24'
domain 'Your.Domain'
username 'mail'

You can hand test the records for 'www' and 'mail', labeled 'myddns' and 'mail' with:
/usr/lib/ddns/dynamic_dns_updater.sh myddns
/usr/lib/ddns/dynamic_dns_updater.sh mail

Look at the return XML and see that the Error Count is 0 to validate a successful update. Check
each record, one at a time. Use <Ctrl-C> to kill the test daemons.

Manually starting ddns-scripts

The ddns-scripts monitoring script starts when hotplug ifup event happens. This will happen
automatically at system startup when the named interface comes up. The simplest way to start
ddns-scripts is to reboot, but to avoid a reboot, it can be started manually from the command line.
After setting "enabled" to 1 and configuring other settings as above, manually generate an ifup
hotplug event for the desired interface.

This will case the the hotplug script /etc/hotplug.d/25-ddns to run

o For INTERFACE, type the specified ddns-scripts interface name (the interface
name from /etc/config/network, usually 'wan')

root@OpenWrt:~# ACTION=ifup INTERFACE=wan /sbin/hotplug-call iface

As an alternative, ddns-scripts can be called at a lower level
o type the specified ddns-scripts interface name (the interface name from
/etc/config/network, usually 'wan')
sh
. /usr/lib/ddns/dynamic_dns_functions.sh # note the leading period
start_daemon_for_all_ddns_sections "wan"
exit
Beginning ddns-scripts Version 1.0.0-23
o simply enable/disable start/stop/restart like every other service
root@OpenWrt:~# /etc/init.d/ddns enable
root@OpenWrt:~# /etc/init.d/ddns start

Verification

Verify the ddns-scripts interface monitor script is running

One instance of this script should be running for each ddns-scripts configuration defined

ps | grep dynamic_dns_updater.sh
Verify the correct IP address by pinging

the dynamic DNS name

Alerting

ddns-scripts does not send any alerts when it detects or updates the DDNS IP address
Marius Gedminas posted a two-line patch to ddns-scripts available at
http://patchwork.openwrt.org/patch/1072/. This change adds syslog output when an IP
change is detected. It can be manually added to /usr/lib/ddns/dynamic_dns_updater.sh.
o

For ddns-scripts ver. 1.0.0-21 (the version OpenWrt Attitude Adjustment 12.09),
the line numbers to look for are after original lines 294 and 325

If OpenWrt is configured to send syslog output to a remote syslog server (see

log.overview), that server can be configured to perform various alerting actions

Debugging
If something goes wrong, you can see a log of activity by calling
/usr/lib/ddns/dynamic_dns_updater.sh myddns

Note: myddns is the name of the service config entry in /etc/config/ddns file.
If you only see the update_url= output you forgot the enable flag for the service.
For example if you see badauth in Update Output, you have to change your password which
contains only letters and numbers. Because busybox's (v1.15.3) wget implementation has an
issue handling encoded URLs.
Sometimes the scripts mess up and many instances of the updater will be fired. In this case, use
this command to kill them all and start again
root@OpenWrt:~# ps | grep dynami[c] | awk '{print $1}' | xargs kill
root@OpenWrt:~# ACTION=ifup INTERFACE=wan /sbin/hotplug-call iface

Tweaks
Full API documentation available here: https://www.dyndns.com/developers/specs/syntax.html
To enable wildcard domains (*.foo.dyndns.org) on dyndns.org, replace the line in
/usr/lib/ddns/services with:

"dyndns.org"
"http://[USERNAME]:
[PASSWORD]@members.dyndns.org/nic/update?
wildcard=ON&hostname=[DOMAIN]&myip=[IP]"

To retain the wildcard setting on dyndns.org, replace the line in /usr/lib/ddns/services with:
"dyndns.org"
"http://[USERNAME]:
[PASSWORD]@members.dyndns.org/nic/update?
wildcard=NOCHG&hostname=[DOMAIN]&myip=[IP]"

To add dyndns protocol compatible services like dyndns.fr, add a line in

/usr/lib/ddns/services with:
"dyndns.fr"
"http://[DOMAIN]:
[PASSWORD]@dyndns.dyndns.fr/update.php?hostname=[DOMAIN]&myip=[IP]"

To add dyndns protocol compatible services like dyndnspro.com, add a line in

/usr/lib/ddns/services with:
"dyndnspro.com"
"http://[DOMAIN]:
[PASSWORD]@dyndns.dyndnspro.com/update.php?hostname=[DOMAIN]&myip=[IP]"

To add dyndns protocol compatible services like dynamicdomain.net, add a line in

/usr/lib/ddns/services with:
"dynamicdomain.net"
"http://[DOMAIN]:
[PASSWORD]@dyndns.dynamicdomain.net/update.php?hostname=[DOMAIN]&myip=[IP]"

To add dyndns protocol compatible services like dyndns.it, add a line in

/usr/lib/ddns/services with:
"dyndns.it"
"http://[USERNAME]:[PASSWORD]@dyndns.it/nic/update?
hostname=[DOMAIN]&myip=[IP]"

To add dyndns protocol compatible services like no-ip.com, add a line in

/usr/lib/ddns/services with:
"no-ip.org"
"http://[USERNAME]:[PASSWORD]@dynupdate.noip.com/nic/update?hostname=[DOMAIN]&myip=[IP]"

To add dyndns protocol compatible services like duckdns.org, add a line in

/usr/lib/ddns/services with:
"duckdns.org"
"http://www.duckdns.org/update?
domains=[DOMAIN]&token=[PASSWORD]&ip=[IP]"

To add dyndns protocol compatible services like system-ns.com, add a line in

/usr/lib/ddns/services with:

"system-ns.com"
"http://system-ns.com/api?
type=dynamic&domain=[DOMAIN]&command=set&token=[PASSWORD]&ip=[IP]"

To add dyndns protocol compatible services like two-dns.de, add a line in

/usr/lib/ddns/services with:
"two-DNS"
"http://[USERNAME]:[PASSWORD]@update.twodns.de/update?
hostname=[DOMAIN]&ip=[IP]"
# with https Support
"two-DNS_https"
"https://[USERNAME]:
[PASSWORD]@update.twodns.de/update?hostname=[DOMAIN]&ip=[IP]"
# needs:
# option use_https
1
# option cacert
/etc/ssl/certs/Example_CA.pem
# and install curl
# as shown below

SSL support
By default ddns-scripts uses wget for DNS updates over http, and curl for DNS updates over
https (SSL). In order for ddns-scripts to perform DNS updates over https (SSL), you will need
to install the curl package, and add the appropriate root certificate for your ddns provider.
Busybox provides its own version of wget; however, it does not support https (SSL). You can
either follow the instructions at SSL and Certificates in wget or install curl and see the correct
way below.

The correct way using curl

There is no need to modify /usr/lib/ddns/services. Automatic change of URI scheme from
http to https is controlled by the use_https variable. Install curl and add the following to
/etc/config/ddns (replace cacert path to the correct one, either a file or a directory):
option use_https
option cacert

1
/etc/ssl/certs/Example_CA.pem

Note that you need to download a Certificate Authority bundle as curl's pre-packaged bundle is
out of date. Curl does maintain a current CA bundle here: http://curl.haxx.se/ca/
Use the following commands to download the Curl CA bundle:
root@OpenWrt:~# mkdir -p /etc/ssl/certs/
root@OpenWrt:~# wget -P /etc/ssl/certs/ http://curl.haxx.se/ca/cacert.pem

Curl SSLv2,3 Support

If your DDNS provider is using SSLv2 or SSLv3 Curl will throw error code 35 because it can't
connect unless you specify the correct SSL version. To fix this, you must modify
/usr/lib/ddns/dynamic_dns_updater.sh as such:

For SSLv2 replace sslv3 with sslv2

Find this string of code:
retrieve_prog="${retrieve_prog}--cacert $cacert "

Replace it with the following:

retrieve_prog="${retrieve_prog}--sslv3 --cacert $cacert "

Find this string of code:

retrieve_prog="${retrieve_prog}--capath $cacert "

Replace it with the following:

retrieve_prog="${retrieve_prog}--sslv3 --capath $cacert "

If your ddns provider uses a self-signed certificate, or if the certificate issuer is not listed in the
curl CA bundle, curl will throw error code 60 and not open a connection to the ddns provider.
To fix this, you must modify /usr/lib/ddns/dynamic_dns_updater.sh as such:
Warning: This allows curl to connect to https sites without SSL certificates. Only do this if no
other options are available, and if you ultimately trust your ddns provider.
Find this string of code:
retrieve_prog="${retrieve_prog}--cacert $cacert "

Replace it with the following:

retrieve_prog="${retrieve_prog}-k "

Find this string of code:

retrieve_prog="${retrieve_prog}--capath $cacert "

Replace it with the following:

retrieve_prog="${retrieve_prog}-k "

Using wget
If you want to stick to wget, then you should set SSL_CERT_DIR variable in
/usr/lib/ddns/dynamic_dns_functions.sh before calling
/usr/lib/ddns/dynamic_dns_updater.sh because /etc/profile is not sourced in daemon
mode.

Using wget with self-signed SSL certificates

Note: this is also a workaround for the wget ssl bug mentioned on SSL and Certificates in
wget#A Caveat
If your service provider uses a self-signed certificate, one options is to use the no-checkcertificate option with wget (read the disclaimer here:
http://www.gnu.org/software/wget/manual/html_node/HTTPS-_0028SSL_002fTLS_0029Options.html#HTTPS-_0028SSL_002fTLS_0029-Options).
Replace the retrieve_prog line in /usr/lib/ddns/dynamic_dns_updater.sh with this:
retrieve_prog="/usr/bin/wget --no-check-certificate -O - ";

An another workaround for wget's SSL bug and https://freedns.afraid.org (I've tested only this
one.) is to install curl and replace the retrieve_prog line in /usr/lib/ddns/dynamic_dns_updater.sh
with this:
retrieve_prog="/usr/bin/curl";

Using webif
Packages
updatedd updatedd-mod-dyndns updatedd-mod-noip luci webif

Other methods
DDNS scripts have been a surprisingly dynamic(lol) part of OpenWrt. There have been many
other scripts and packages used.

ez-ipupdate (no longer maintained?)

updatedd (used in webif) Supports many other services

JimWright's White Russian dyndns.org script (probably based off a script mbm posted in
the forum)

exobyte's Kamikaze dyndns.org script (based of JimWright's)

run nsupdate from /etc/udhcpc.user to update an authoritative master configured for

DDNS.