Dynamic DNS Using The Linode API

DynDNS recently ended their free services. In this article we will take a look at the Linode API and create a simple way to mimmick the DynDNS service with your own custom domain names.

Why use a Dynamic DNS service?

Dynamic DNS services are great for when you need to communicate to your home network easily and efficiently. They enable you to assign a domain name to your home network's IP, and if your ISP ever changes it, the dynamic DNS service will make sure that the IP for your domain is updated and kept in sync.

DynDNS have provided a free service to do this for many years, but they recently announced that they would be ending their free service effective on May 7th, 2014. Since adding another yearly expenditure wasn't too appealing, I took to the internet to find the best alternative. Since I already own a Linode, I discovered that Linode has an amazing API that can be used to perform a DynDNS-like service quite easily at no additional cost. Let's take a look!

Setting Up Your Domain

If you haven't purchased a domain name yet, you should do so now. I've had a lot of luck with Namecheap, but any domain name registrar will work. If you've already setup your domain on Linode, then feel free to skip to the next step.

Once you have purchased your domain, you need to login to your account manager for your registrar and replace their name servers with Linode's. This will be in a different location for each registrar, but it shouldn't be too hard to find! The Linode name servers are:

Once you have replaced those, login to your Linode Manager and select the DNS Manager link at the top. Select the Add a Domain Zone link and input your new domain name, administrator email, and ensure that Insert Default Records is set to yes. When you are done click the Add a Master Zone button.

The next screen will have all of the information about your domain including your name and mail server records. For our purposes we only need to focus on the A/AAAA Records.

To direct your domain to your home network, you need to replace the current IP with your home IP. If you do not know your home IP, a quick Google search should do the trick.

It may take some time for these changes to propagate, but once they do you will be able to access your home network from your domain! Now, lets take a look at how we can use the Linode API to make sure that we keep our IP synced with our domain name in case our ISP decides to change it.

Creating a New User

Before we move further, let's take a moment to discuss a small security precaution. In the following steps, you'll be creating an API key for a user on your Linode account. This key will give user access to perform actions on your account in place of a username and password. Depending on which user you assign this key to, it can dictate how much access the user has.

For example, If you assign an API key to your main Linode user account, then the API key will have access to to anything on your account. This is potentially dangerous if your API key ever becomes public. So, It's highly recommended that we create a secondary user and limit their access to the domain you setup at the beginning of this article.

To setup a new user, Login to your Linode account and navigate to Accounts and then select the Users and Permissions tab. You will be prompted to provide your password for security purpose and then it will allow you to create another user by selecting the Add a User option. The next screen will display a form to assign a username, password, and email to the new user along with the permissions associated with the user. In our case, make sure that the Yes - this user can only do what I specify option is selected and then select Save Changes to create the user.

The next screen will display all of the options that you have to grant or restrict to the user. In this case, all you want to do is check the "All Privs" checkbox on the domain that you've added underneath the DNS Zone Grants section. This will prevent the user (and consequentially the API key) from making changes to anything but the domain we have specified.

Creating a Linode API Key

First, we need to create our API key. To do so, simply login to your Linode and select the My Profile link in the top left corner.

Upon arrival, you will be prompted to input your password again for verification puposes. Once you have done so, select API Keys. This screen will list out any of your previously created API Keys and allow you to create new ones. To create a new API key, simply give your key a label (I called mine Dynamic DNS) and ensure that expires is set to never and then click create.

Obtaining Our Domain and Resource IDs

Next, you need to use your API key to retrieve your Domain and Resource ID's that you will then use to create the URL that will update your IP as it changes.

To find your Domain ID, simply paste your API key into the following URL and view it in your browser.

This will return a JSON object listing all of the domains that are registered on your Linode account. Simply locate the domain that you will be using to access your home network and take note of the value in the DOMAINID property.

To find your Resource ID, simply input your API key and your newly obtained Domain ID in the following URL and view it in your browser.

This will also return a JSON object. Find the record that contains a NAME property with a value of "www" and a TYPE of "A". Make note of the RESOURCEID value associated with that object and next we will create our final URL.

Now that you have your API key, Domain ID, and Resource ID you can finally build the full URL you will use to call the Linode API to keep your IP dynamically updated.[remote_addr]

Like the URLs before, you simply plug in the information we discovered in the previous step. The main difference is that this URL targets the domain.resource.update API action and has an additional target parameter which is assigned a value of [remote_addr]. The [remote_addr] is a dynamic placeholder value that will automatically pull the current IP from the computer the URL is accessed from and assign it to the domain in your Linode DNS Manager.

Setting Up A Cron Job

The final step is to create and run a cron job on a machine that is on your home network using the Linode API URL that you just created.

A cron job is a Linux command that is used to schedule and execute repetitive commands or scripts at a timed interval.

This will create the bridge between your home network and your Linode to make sure that Linode always knows when our home network's IP has changed.

It is important to note that you must run this cron job from a computer on your home network! If you run the cron job from any computer outside of your network it will reassign the IP to that network and will only cause you trouble.

To create your cron job, open your terminal and input:

crontab -e

This command will open your personal cron configuration file. This will likely have several jobs already included. To add another, navigate to the bottom of the file and create a new line. On the new line, input:

*/30 * * * * /bin/echo `/bin/date`: `/usr/bin/wget -qO- --no-check-certificate\&api_action=domain.resource.update\&domainid=your-domain-id\&resourceid=your-resource-id\&target=[remote_addr]` >> /var/log/linode_dyndns.log

Make sure you swap in your API key, Domain ID, and Resource ID into this URL, otherwise the API call will fail!

This cron job simply visits your Linode API URL every 30 minutes and sends along your network IP to the Linode DNS Manager so it can update the IP registered to your domain name. The response is then logged to a file named linode_dyndns.log with the current date and time so we can keep track of the responses and properly debug our cron job if we run into any problems.

Once this has been completed, you can save and close your cron configuration file and you're all set. Your machine will now use the cron job you've added to automatically keep everything in sync.


We've saved a few bucks, learned a little bit about the wonderful Linode API, and got our feet wet with cron. While DynDNS provides a great service, it's nice to have the option of using a custom domain and to get more out of a service you already use.

If you would like to learn more about the Linode API or cron, be sure to check out the additional reading below.

Additional Reading