DNS Dynamo

Introduction

There are two ways to update your Dynamo DNS service, with a third coming very soon.

With a Device

Many devices such as routers, surveillance cameras, and NAS arrays support the use of dynamic DNS services (sometimes called "DDNS"). Almost all of those support an industry-standard API published by DynDNS.org in 1999, and KisoLabs provides a compatible API.

If your device has an option for a server hostname and supports DynDNS.org, then it will work with KisoLabs' DNS Dynamo.

Skip to the section on using DNS Dynamo with your internet-connected device.

Using the Basic API

Developers, device manufacturers and all KisoLabs users can implement their own custom dynamic DNS client for our basic API.

Our basic API is designed to be simple, lightweight, and easy to implement on edge devices (your computer, for example, instead of your router).

Skip to the section on using the DNS Dynamo basic API.

DNS Dynamo Client for Windows

We're working hard on a reliable and robust client for DNS Dynamo that you can run on your computer and keep your IP address updated. It requires no configuration to get it to start working right out of the box, and can run on any computer (even those using a NAT IP address).

The client will be released for all x86 and x64 versions of Windows XP through Windows 8 (and Windows 2012), and best of all it will be released under an open-source license.

DNS Dynamo with a Network Device

Many device manufacturers have chosen to support only a couple of dynamic DNS providers. If KisoLabs' DNS Dynamo isn't supported by your device, you may be able to use it with some custom settings. There are two options available, depending upon whether your device supports a custom DNS service, or custom DNS entries:

Option #1 - Custom Dynamic DNS Service

If your Dynamic DNS (DDNS) configuration screen has a field for "Server Address", then you are probably in luck! Enter the following into the "Server Address" field:

  1. update01-dynamo.kisolabs.net

Then set the rest of the fields as described in Network Device Configuration Fields, below.

Option #2 - Custom DNS Servers

If you're using a router that allows you to provide seperate DNS servers for your network connection and for your DHCP clients (or you are not using your router for DHCP), or if your device is something other than a router and does not need access to recursive DNS, then this method will allow you to "trick" your device into using KisoLabs. It will cause your device to access KisoLabs' servers when it attempts to access dyndns.org.

If your network device is a router, go into your WAN configuration and make a note of the DNS servers listed (usually called DNS 1 and DNS 2). Now go to your DHCP configuration, and enter those DNS servers in the appropriate fields. (If you are using your router for DHCP and no DNS fields are listed in your DHCP configuration screen, then you cannot use this method.)

If your network device is not a router or does not provide DHCP, then just continue on.

Go to your WAN configuration (or network configuration) and change the DNS servers to the following:

  1. DNS 1: 54.245.231.113
  2. DNS 2: 50.56.238.47

Now go to your dynamic DNS (DDNS) configuration and change the DDNS provider to "DynDNS.org" or "DynDNS.com" (depending upon which one is listed -- choose DynDNS.org if both are listed).

Network Device Configuration Fields

In the username and password fields, do not use your KisoLabs username and password. Instead, copy and paste the "Device Username" and "Device Password" from your KisoLabs DNS Dynamo configuration.

The host name field is probably required by your network device, but is not required by KisoLabs. You may enter any value (for example "x").

Make sure that DDNS is enabled, and save your settings.

Basic API

Unlike other dynamic DNS solutions that require you to run proprietary software on your router or use a complex API, KisoLabs leaves calling Dynamo DNS up to you. It has an exceedingly simple API: Just request the URL below from any computer connected to the internet via your dynamic IP address.

https://update01-dynamo.kisolabs.net/[Your Update Token]

The DNS Dynamo update API can be accessed via plain-text HTTP by using http:// in place of https://, however it is not recommended for security reasons.

Optional Parameters

Optional parameters take the form of query string parameters or form POST data. As of now, Dynamo DNS supports only one optional parameter.

Request parameter

Parameter Name Type  
ip IP IPv4 Address
(Optional)
The IP address to be used in place of the IP address making the request. This field may contain any valid IPv4 address.

Return Codes

The API will return a status code as the body of the HTTP response. Any response other than one of the codes listed below indicates a fatal error condition. (Red text indicates an error condition, whereas green texts inidicates normal operation.)

Code Meaning
UP,OK Your IP address has changed, has been updated in our system, and has been successfully pushed out to all DNS servers.
UP,ER Your IP address has changed, has been updated in our system, but has not been successfully pushed out to all DNS servers. The error portion can be ignored, as the change will migrate to all DNS servers with 5-10 minutes.
NC There was no change to your IP address since the last API call.
NR There is no record of your token at the update server. This is a temporary condition, and should only be seen in the first few minutes after setting up your Dynamo DNS service. If this error persists for more than two API calls in a row, KisoLabs' support should be contacted.
ND There is no DNS record to update for your token. This is a temporary condition, and should only be seen in the first few minutes after setting up your Dynamo DNS service. If this error persists for more than two API calls in a row, KisoLabs' support should be contacted.
TF Calls to the Dynamo DNS API are too frequent. The API should be called no more frequently than once every 5 minutes. When receiving this status code, no updates are being made to your IP address. This condition is temporary: Just wait 5 minutes and call the API again. (Note that you must wait an additional 5 minutes after receiving a response of TF. For example, calling the API every 4 minutes will result in a response of TF for all calls excepting the first call.)
NT No token was found within the API call URL. Make sure that you have copied the full token from the box above, and that the token is 42 characters in length.
IN The optional IP address parameter was found to contain data, but that data was invalid as an IP address. No update was made.
ER There has been a general error in processing your request. If this persists for more than two API calls in a row, KisoLabs' support should be contacted.

Note: All of these response codes will be associated with an HTTP status code of 200, even if the Dynamo DNS code is an error condition. Any other HTTP status code would indicate a problem with the Dynamo DNS service or may be due to a malformed HTTP request.

Examples

Sample GET Request with IP Parameter

Note that the HTTP request header fields User-Agent, Accept, Accept-Language, and Connection are not required and are ignored by the server. They are shown here as this request is intended to demonstrate that of a standard web browser (in this case, Firefox 15). The Host header is required.

  1. GET http://update01-dynamo.kisolabs.net/1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ123456 ?ip=10.1.1.33 HTTP/1.1
  2. Host: update01-dynamo.kisolabs.net
  3. User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/15.0.1
  4. Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
  5. Accept-Language: en-us,en;q=0.5
  6. Connection: keep-alive

Sample POST Request with IP Parameter

Unlike the GET request depicted above, User-Agent, Accept, Accept-Language, and Connection have been omitted for the sake of example. They remain optional, and will be ignored by the server if included.

  1. POST http://update01-dynamo.kisolabs.net/1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ123456 HTTP/1.1
  2. Host: update01-dynamo.kisolabs.net
  3.  
  4. ip=10.1.1.33

Note: In line 1 of both examples above there is no line break within the HTTP request. The line is word wrapped in the examples for readability.

Sample Response

The response from the server will have the same format regardless of whether the request is a GET or POST. The only headers that will vary between responses are Date (which will contain the date and time of the response) and Content-Length (which will be appropriate to the length of the content).

The content is in UTF-8 encoded plaintext, but as the characters in the response do not exceed the scope of ANSI characters it should be interpretable in most western character sets.

  1. HTTP/1.1 200 OK
  2. Date: Thu, 25 Oct 2012 19:05:57 GMT
  3. Server: Apache
  4. Vary: Host
  5. Expires: Thu, 19 Nov 1981 08:52:00 GMT
  6. Cache-Control: max-age=1, no-cache
  7. Pragma: no-cache
  8. Content-Length: 5
  9. Connection: close
  10. Content-Type: text/plain; charset=utf-8
  11.  
  12. UP,OK

Allowing Updates to Propagate

Although we use relatively small TTL values by default (5 minutes) for our Dynamo DNS addresses, other DNS servers may override that value when caching your information. Hence you may not see a change to your IP address for up to a few hours, in extreme cases. This may render your computer inaccessible during that time. This is not a failing of the Dynamo DNS service, but it is an issue common to all dynamic DNS and static DNS services.

Additionally, you have control over your TTL value and may set it to a significantly longer time if you so choose. Changes to your DNS information will not be visible to the internet at large for at least that time period.

If your computer is inaccessible and you believe that your IP address has changed, just log into the KisoLabs website and visit this page. You will be able to see your current IP address and the date on which it was changed. You may then test access to your computer(s) using the IP address directly. You may also do a DNS lookup using nslookup or dig against your ISP's DNS server to see if they are reporting the same IP address as the KisoLabs website. If not, then it is just a matter of waiting for the DNS changes to propagate.

Google offers public DNS servers that are a good way to check for propagation if you are unsure of the DNS configuration at your location. Their servers are accessible at: 8.8.8.8 and 8.8.4.4

Calling the API

There are numerous ways in which to call the update URL. You can call it manually from your browser to test or refresh it. To keep it updating around the clock, you can use a scheduled task in Windows, a cron job in Unix/Linux/FreeBSD/OSX, or write your own application.

If you write an application that implements the Dynamo DNS API and want to share it with the KisoLabs community, we'd love to hear from you. You can post about it on our forum or let us know directly. If you'd like, we could even include a link in this section of the documentation (with proper attribution, of course!)

Windows Applications

These applications can be run as a Windows scheduled task and can be configured to call your Dynamo DNS URL. You can set your task to run as frequently as every 5 minutes, or at any longer interval that you'd like. (These applications have not all been tested by KisoLabs, nor do we support them).

Windows Scripts

Sample scripts to access a URL from a scheduled task are listed below. (These links have not all been tested by KisoLabs, nor do we support their content).

Windows PowerShell

In Windows PowerShell (available from Microsoft if it's not included with your version of Windows), the following command is sufficient to update the Dynamo DNS API:

  1. (new-object System.Net.WebClient).DownloadString( 'http://update01-dynamo.kisolabs.net/[Your Update Token]')

Linux / Unix

There are many flavors of Linux and Unix, as well as myriad command line tools that can request a URL. What is probably the most universally-accessible form of requesting the Dynamo DNS API is as follows:

  1. wget -qO- http://update01-dynamo.kisolabs.net/[Your Update Token] &> /dev/null

Dynamo DNS Advanced

Dynamo DNS Advanced allows you to use Dynamo DNS with your own domain. You can use your dynamic IP address in any DNS field and have it update automatically whenever your IP address changes.

Using Dynamo DNS Advanced is easy: Follow the directions for Dynamo DNS (above), and use your IP Address Token anywhere in your DNS configuration where you would want your dynamic IP address to appear. The IP Address Token looks like this:

dd:1234567890ABCDEF

The token is dd: followed by 16 numbers and/or upper-case letters. (Note that the letters are case sensitive and must be upper-case.)

As an example, you may create an A record for the host www and put your IP Address Token (dd:1234567890ABCDEF) in the data field. Once you update your dynamic IP address using the Dynamo DNS API, you will then receive your IP address in response to a DNS query for the host www under your domain.

Note: It is recommended that you update your IP address using the Dynamo DNS API at least once before configuring your DNS records. If there is no valid IP address matching your IP Address Token, the address 127.0.0.1 will be used as a placeholder. That placeholder IP may then become cached by third-party DNS servers and it could take some time for your updated IP to become resolvable.

IP Address Token

An advantage of Dynamo DNS Advanced is that you can use your IP Address Token in any KisoLabs DNS configuration. For example, if you are using our DNS Serv Pro product for another domain, you can put your token in any DNS field and it will be translated to your dynamic IP address.

You can use your IP address token in multiple zones, meaning that you can host many different internet services from one dynamic IP address without the need for CNAMEs, web forwarding, or other measures.

If you have multiple Dynamo DNS Advanced services, each with its own dynamic IP address, you can mix and match IP Address Tokens between those services and all other DNS services within your account.

© KisoLabs 2017
w01
KisoLabs