This is an old revision of the document!
Private Tiddlywiki
https://www.duckdns.org/
https://www.duckdns.org/spec.jsp
HTTP API Specification
The update URL can be requested on HTTPS or HTTP. It is recommended that you always use HTTPS
We provide HTTP services for unfortunate users that have HTTPS blocked
You can update your domain(s) with a single HTTPS get to DuckDNS
https://www.duckdns.org/update?domains={YOURVALUE}&token={YOURVALUE}[&ip={YOURVALUE}][&ipv6={YOURVALUE}][&verbose=true][&clear=true]
The domain can be a single domain - or a comma separated list of domains.
The domain does not need to include the .duckdns.org part of your domain, just the subname.
If you do not specify the IP address, then it will be detected - this only works for IPv4 addresses
You can put either an IPv4 or an IPv6 address in the ip parameter
If you want to update BOTH of your IPv4 and IPv6 records at once, then you can use the optional parameter ipv6
to clear both your records use the optional parameter clear=true
A normal good response is
OK
A normal bad response is
KO
if you add the &verbose=true parameter to your request, then OK responses have more information
OK
127.0.0.2 [The current IP address for your update - can be blank]
2002:DB7::21f:5bff:febf:ce22:8a2e [The current IPV6 address for your update - can be blank]
UPDATED [UPDATED or NOCHANGE]
HTTP Parameters
domains - REQUIRED - comma separated list of the subnames you want to update
token - REQUIRED - your account token
ip - OPTIONAL - if left blank we detect IPv4 addresses, if you want you can supply a valid IPv4 or IPv6 address
ipv6 - OPTIONAL - a valid IPv6 address, if you specify this then the autodetection for ip is not used
verbose - OPTIONAL - if set to true, you get information back about how the request went
clear - OPTIONAL - if set to true, the update will ignore all ip's and clear both your records
Special no-parameter request format
Some very basic routers can only make requests without parameters
For these requirements the following request is possible
https://duckdns.org/update/{YOURDOMAIN}/{YOURTOKEN}[/{YOURIPADDRESS}]
Restrictions
YOURDOMAIN - REQUIRED - only a single subdomain
YOURTOKEN - REQUIRED - your account token
YOURIPADDRESS - OPTIONAL - if left blank we detect IPv4 addresses, if you want to over-ride this, with a valid IPv4 or IPv6 address
TXT Record API
The TXT update URL can be requested on HTTPS or HTTP. It is recommended that you always use HTTPS
We provide HTTP services for unfortunate users that have HTTPS blocked
You can update your domain(s) TXT record with a single HTTPS get to DuckDNS
your TXT record will apply to all sub-subdomains under your domain e.g. xxx.yyy.duckdns.org shares the same TXT record as yyy.duckdns.org
https://www.duckdns.org/update?domains={YOURVALUE}&token={YOURVALUE}&txt={YOURVALUE}[&verbose=true][&clear=true]
The domain can be a single domain - or a comma separated list of domains.
The domain does not need to include the .duckdns.org part of your domain, just the subname.
to clear the TXT value of your records use the optional parameter clear=true
A normal good response is
OK
A normal bad response is
KO
if you add the &verbose=true parameter to your request, then OK responses have more information
OK
sometxt=thistext [The current TXT record for your update - can be blank]
UPDATED [UPDATED or NOCHANGE]
HTTP Parameters
domains - REQUIRED - comma separated list of the subnames you want to update
token - REQUIRED - your account token
txt - REQUIRED - the txt you require
verbose - OPTIONAL - if set to true, you get information back about how the request went
clear - OPTIONAL - if set to true, the update will ignore the txt parameter and clear the txt record
Note that the TXT record does not show up in the WEB interface
You can use online web based Dig tools to query your record
https://www.digwebinterface.com/?hostnames=test.duckdns.org&type=TXT&ns=resolver&useresolver=8.8.4.4
To see your TXT record on linux or osx you can query DNS directly
dig test.duckdns.org TXT
As stated before, this record will be also presented for any sub-subdomain queries
dig test.test.duckdns.org TXT
This can be used for example to prove your ownership with letsencrypt.org
========================
https://www.duckdns.org/install.jsp?tab=linux-cron&domain=n6xre
first step - choose a domain.
http://
n6xre
.duckdns.org
linux cron
if your linux install is running a crontab, then you can use a cron job to keep updated
we can see this with
ps -ef | grep cr[o]n
if this returns nothing - then go and read up how to install cron for your distribution of linux.
also confirm that you have curl installed, test this by attempting to run curl
curl
if this returns a command not found like error - then find out how to install curl for your distribution.
otherwise lets get started and make a directory to put your files in, move into it and make our main script
mkdir duckdns
cd duckdns
vi duck.sh
now copy this text and put it into the file (in vi you hit the i key to insert, ESC then u to undo) The example below is for the domain n6xre
if you want the configuration for a different domain, use the drop down box above
you can pass a comma separated (no spaces) list of domains
you can if you need to hard code an IP (best not to - leave it blank and we detect your remote ip)
hit ESC then use use arrow keys to move the cursor x deletes, i puts you back into insert mode
echo url="https://www.duckdns.org/update?domains=n6xre&token=58a1c3d7-8787-41dd-9790-e2d7d5c40e77&ip=" | curl -k -o ~/duckdns/duck.log -K -
now save the file (in vi hit ESC then :wq! then ENTER)
this script will make a https request and log the output in the file duck.log
now make the duck.sh file executeable
chmod 700 duck.sh
next we will be using the cron process to make the script get run every 5 minutes
crontab -e
copy this text and paste it at the bottom of the crontab
*/5 * * * * ~/duckdns/duck.sh >/dev/null 2>&1
now save the file (CTRL+o then CTRL+x)
lets test the script
./duck.sh
this should simply return to a prompt
we can also see if the last attempt was successful (OK or bad KO)
cat duck.log
if it is KO check your Token and Domain are correct in the duck.sh script
what now?
Well you probably want to setup port forwarding on your router to make use of your new DDNS name
we recommend portforward.com to learn all about this.
