dynamic.name: DynDNS over DNS

Start

Dynamic.name is a Dynamic DNS (DynDNS) alternative that uses a different approach than has been traditionally done in the past by using the DNS protocol itself as the client mechanism. This approach bypasses most firewall configurations and removes the need for any additional software to update your IP, making it much easier to deploy and embed while adding no overhead to your system.

To use this service you will need to use our simple web-based API to create a username that will represent a subdomain on dynamic.name (ex. username.dynamic.name). An additional objective of this service is for it to be anonymous in its nature, so no (e-mail) verification is done, this means if you forget your password you will never recover your subdomain.

Once you have created your subdomain you can navigate to the usage section to gain a more detailed understanding and configure your systems to update, or continue reading the no frills quick start & automatic setup guides below.

Quick Start

This is for those who just want to get up and running with the most common use case, a UNIX-based environment with an IPv4 IP. The following steps expect you to replace MYSUBDOMAIN, MYPASSWORD, and XXXXXXXXXXXXXXXX (example passcode) with your own values in all steps.

Step #1: Create a new subdomain

$ curl https://MYSUBDOMAIN:MYPASSWORD@api.dynamic.name/create
201 Created: Your initial passcode is: XXXXXXXXXXXXXXXX

Assuming a successful response like above, copy the passcode returned to use in steps #2 and #3.

Step #2: Verify your subdomain updates properly

$ nslookup -nosearch -type=A XXXXXXXXXXXXXXXX.MYSUBDOMAIN.dynamic.name update.dynamic.name
Server:         update.dynamic.name
Address:        XXX.XXX.XXX.XXX#53

Name:   xxxxxxxxxxxxxxxx.mysubdomain.dynamic.name
Address: XXX.XXX.XXX.XXX

Assuming a successful response like above, you should see your public-facing IP returned.

Step #3: Add cronjob to keep your IP updated

$ (crontab -l; echo "*/5 * * * * nslookup -nosearch -type=A XXXXXXXXXXXXXXXX.MYSUBDOMAIN.dynamic.name update.dynamic.name") | crontab -

This is the same command as in step #2, but now will run every 5 minutes to keep your IP current.

Step #4: Use your subdomain anywhere (example)

$ ssh me@MYSUBDOMAIN.dynamic.name

Automatic setup

If you understand and are comfortable with the steps in quick start guide above you can automatically accomplish the same (and more) using one of the following scripts.

UNIX-Based: dynamic-setup.sh (Shell)

$ sh ./dynamic-setup.sh

Windows: dynamic-setup.ps1 (PowerScript)

C:\> powershell -ExecutionPolicy Bypass "C:\path\to\dynamic-setup.ps1"

You may also be able to double-click on the file to execute it, but the default powerscript security policy will not allow it.

Security advisory

By design, this service is at risk of Man-in-the-middle (MITM) attacks. This is due to the fact the passcode is transmitted in clear text over DNS, while it's unlikely to occur it is advised you have data like SSH keys saved in advance to detect such an event. If you are interested in additional steps to help mitigate MITM risks please view the "advanced security" section inside the usage section.

API

The dynamic.name API is intended to be used for account (subdomain) creation and general maintenance. For most users this will be a one-time event to create your subdomain and get your passcode, from that point you will want to view the usage.

Two pieces of information are required for all API requests, a subdomain (aka. username) and a password. This information is used in conjunction with Basic HTTP access authentication, a universally supported mechanism in all HTTP clients and browsers.

All subdomains are created on a first-come, first-served basis and are yours for the life of this service. It's important to note there is no password recovery mechanism, so if you forget your password you will never recover your subdomain.

The subdomain you choose is required to be 6 to 16 alphanumeric characters, it may contain dashes as long as they are not at the beginning or end. The password must also be 16 characters or less.

For the sake of simplicity this documentation uses curl (a common command-line HTTP client) to perform all API requests, you may use any number of other clients (or even browsers).

Create a subdomain

curl https://SUBDOMAIN:PASSWORD@api.dynamic.name/create

If successful, the response will be a 2XX HTTP Code and contain your passcode (also included in the "X-Passcode" header). If not, you will see a HTTP error code and a description of the error condition.

Get the passcode for a subdomain

curl https://SUBDOMAIN:PASSWORD@api.dynamic.name/passcode

If successful, the response will be a 2XX HTTP Code and contain your passcode (also included in the "X-Passcode" header). If not, you will see a HTTP error code and a description of the error condition.

Generate a new passcode for a subdomain

curl https://SUBDOMAIN:PASSWORD@api.dynamic.name/passcode/new

If successful, the response will be a 2XX HTTP Code and contain your new passcode (also included in the "X-Passcode" header). If not, you will see a HTTP error code and a description of the error condition.

Delete a subdomain

curl https://SUBDOMAIN:PASSWORD@api.dynamic.name/delete

If successful, the response will be a 2XX HTTP Code and your subdomain will be deleted. If not, you will see a HTTP error code and a description of the error condition.

API Tool

This GUI tool is an optional method to execute API calls from your current web browser, instead of curl or similar command-line utilities. If you're using a command-line utility already you should skip this and view the usage section. The tool can be found by going to https://api.dynamic.name in your browser, or using the framed version below.

https://api.dynamic.name:

Usage

After you've created your subdomain using the API you can update your subdomain's IP to the IP of the computer you're using with one of the following common system commands (nslookup or host). Make sure to replace PASSCODE (not password!) and SUBDOMAIN with your own values.

IPv4:

Windows / OSX / UNIX:

nslookup -nosearch -type=A PASSCODE.SUBDOMAIN.dynamic.name update.dynamic.name

Linux / OSX / UNIX:

host -t A PASSCODE.SUBDOMAIN.dynamic.name update.dynamic.name

If successful, your current IP will be returned. If not, an empty response or DNS error code will be returned.

IPv6:

Windows / Linux / OSX / UNIX:

nslookup -nosearch -type=AAAA PASSCODE.SUBDOMAIN.dynamic.name update6.dynamic.name

Linux / OSX / UNIX:

host -t AAAA PASSCODE.SUBDOMAIN.dynamic.name update6.dynamic.name

If successful, your current IP will be returned. If not, an empty response or DNS error code will be returned.

Once the command(s) above are executed successfully your subdomain (ex. subdomain.dynamic.name) will resolve to the IP the command was originally executed on.

Automatic updates

The final and most important step is to schedule a task to keep the IP up to date using crontab for UNIX-based OSes, or schtasks if you're using Windows.

UNIX-based:

(crontab -l; echo "*/5 * * * * nslookup -nosearch -type=A PASSCODE.SUBDOMAIN.dynamic.name update.dynamic.name") | crontab -

Windows:

If you have administrator (SYSTEM) access on the Windows machine, start cmd.exe with "Run as administrator" for the following command.

schtasks /create /tn "Dynamic.name IP Updater" /ru SYSTEM /tr "nslookup -nosearch -type=A PASSCODE.SUBDOMAIN.dynamic.name update.dynamic.name" /sc minute /mo 5

If you don't have administrator access you can run it as a normal user, however a command window will momentarily pop up every time it is run and will likely drive you insane. As such, this will only update once an hour for this example.

schtasks /create /tn "Dynamic.name IP Updater" /tr "nslookup -nosearch -type=A PASSCODE.SUBDOMAIN.dynamic.name update.dynamic.name" /sc hourly

Update verification (optional)

To verify your (automatic) updates are working consistently you may do a TXT lookup on your subdomain to show when the last update occurred. For example:

nslookup -nosearch -type=TXT SUBDOMAIN.dynamic.name update.dynamic.name

If successful, the response would look something like "updated: 2000-01-01 00:00:00 -0400 (~ seconds ago)"

Advanced security (optional)

An additional layer of security exists to help mitigate some (but not all) aspects of MITM attacks in the form of passcode hash windows. These passcode hash windows work by creating a hash that includes your current passcode and an identifier based on the current time.

Once you create one of these hashed passcodes you can use it in place of your normal passcode, thereby never transmitting your real passcode over the internet and making the transmitted passcode useless after the time window (1000 seconds) is up.

Both MD5 and SHA1 hash algorithms are supported, using the pseudo-code logic below:

MD5:

MD5_PASSCODE = HEX(
  MD5SUM(
    PASSCODE + ":" + FLOOR(CURRENT_UNIX_TIME_SECS / 1000)
  )
)

SHA1:

SHA1_PASSCODE = HEX(
  SHA1SUM(
    PASSCODE + ":" + FLOOR(CURRENT_UNIX_TIME_SECS / 1000)
  )
)

Now MD5_PASSCODE and/or SHA1_PASSCODE can be used in place of PASSCODE.

The following is a (UNIX-based) shell implementation of the pseudo-code above.

MD5:

echo -n "PASSCODE:$(expr $(date +%s) / 1000)" | md5sum

SHA1:

echo -n "PASSCODE:$(expr $(date +%s) / 1000)" | sha1sum

As a final (UNIX-based) example, the following one-liner will update your (IPv4) IP using a MD5 hash of your passcode, assuming you set YOUR_SUDBDOMAIN and YOUR_PASSCODE accordingly.

export SD="YOUR_SUDBDOMAIN" PC="YOUR_PASSCODE" && nslookup -nosearch -type=A $(echo -n "$PC:$(expr $(date +%s) / 1000)" | md5sum | awk '{print $1".'$SD'.dynamic.name"}') update.dynamic.name

"What is my IP?" support (optional)

For situations where you simply want to know the public IP of the system you're currently on, with no account needed, you can use the special subdomain my.dynamic.name to do so:

IPv4:

Windows / OSX / UNIX:

nslookup -nosearch -type=A my.dynamic.name update.dynamic.name

Linux / OSX / UNIX:

host -t A my.dynamic.name update.dynamic.name

IPv6:

Windows / Linux / OSX / UNIX:

nslookup -nosearch -type=AAAA my.dynamic.name update6.dynamic.name

Linux / OSX / UNIX:

host -t AAAA my.dynamic.name update6.dynamic.name