Understanding Dynamic Domain Name Services (DDNS)

Post Stastics

  • This post has 2367 words.
  • Estimated read time is 11.27 minute(s).

By Writing A DDNS Update Applet

In the vast and interconnected world of the internet, domain names play a crucial role in identifying and accessing various websites and services. When you enter a website address into your browser, like www.example.com, it’s a domain name that allows your device to communicate with the correct server and retrieve the requested content. Behind the scenes, a complex system called the Domain Name System (DNS) enables this translation from human-readable domain names to machine-readable IP addresses.

DNS serves as a distributed directory that stores information about domain names and their corresponding IP addresses. It acts as a phone book of the internet, allowing your device to locate the correct server for a particular website or service. When you type a domain name into your browser, your device sends a DNS query to a DNS server, requesting the IP address associated with that domain name. Once the IP address is obtained, your device can establish a connection with the appropriate server to retrieve the desired content.

Traditionally, DNS has operated in a static manner, where the IP address associated with a domain name remains unchanged until explicitly modified. However, with the increasing use of dynamic IP addresses, especially in home networks and small businesses, the need for a more flexible system arose. This is where Dynamic Domain Name Services (DDNS) come into play.

Dynamic Domain Name Services (DDNS) allow for the automatic update of DNS records to reflect changes in IP addresses. Unlike traditional DNS, where IP addresses are manually configured and updated, DDNS automates this process by dynamically updating DNS records whenever an IP address changes. This dynamic updating is particularly useful for devices or networks with changing IP addresses, such as those connected to the internet through a dynamic IP allocation scheme.

To better understand DDNS, let’s consider a scenario where a home user wants to host a website or remotely access their home network. Typically, residential internet service providers assign dynamic IP addresses to their customers. These IP addresses are subject to change periodically, making it challenging to maintain a consistent connection to the home network or website.

In such cases, DDNS allows users to associate a domain name with their dynamic IP address. They can install DDNS software or configure DDNS settings on their network router or devices. The DDNS client then periodically checks the IP address and updates the DNS records accordingly. This way, even if the IP address changes, the associated domain name remains up-to-date, ensuring uninterrupted access to the hosted services.

DDNS services are offered by various providers, both free and paid, which facilitate the automatic update of DNS records. Users can choose a suitable DDNS provider, create an account, and configure their devices or routers to integrate with the chosen DDNS service. The DDNS provider typically offers a domain name or allows users to associate their existing domain name with the dynamic IP address, simplifying the setup process.

Writing Your Own DDNS Update Applet

So far we have explored the concept of Dynamic Domain Name Services (DDNS) and how they address the challenges posed by dynamic IP addresses. We started by understanding the traditional DNS system, which translates human-readable domain names into machine-readable IP addresses. Then, we delved into the need for DDNS, which automates the process of updating DNS records when IP addresses change. We also discussed how DDNS is particularly useful for home networks and small businesses with dynamic IP allocation. Now, let’s move on to building a DDNS updater application in Python using the request library and Namecheap’s DDNS API.

Registering a Domain Name and Setting Up DDNS on Namecheap

Before we can write our updater application we need a registered domain name.

Namecheap is a popular domain registration and web hosting provider that offers a range of services to help individuals and businesses establish their online presence. If you’re looking to register a domain name and set up Dynamic Domain Name Services (DDNS) on Namecheap, you can follow these steps:

  1. Domain Registration: Visit the Namecheap website (www.namecheap.com) and search for the desired domain name using the search bar on their homepage. Once you find an available domain name that suits your needs, proceed with the registration process. Follow the prompts to create an account, provide the necessary information, and complete the registration by making the required payment.
  2. Accessing the DNS Management Settings: After registering your domain name with Namecheap, you can access the DNS management settings to configure DDNS. Log in to your Namecheap account and navigate to the Domain List or Domain Dashboard section. Locate the domain name you registered and find the DNS settings or DNS management options.
  3. Configuring DDNS: In the DNS management settings, locate the Dynamic DNS (DDNS) section. Namecheap provides an interface to configure DDNS for your domain. Here, you can specify the hostname or subdomain you want to associate with your dynamic IP address. Enter the relevant details, such as the desired subdomain and the password you want to use for DDNS authentication.
  4. Instead of using Namecheap’s update application, we will be writing our own DDNS updater.

By following these steps, you can register a domain name with Namecheap and configure DDNS to ensure that your domain name remains associated with your dynamic IP address. Writing your own DDNS updater application gives you flexibility and control over the updating process, allowing you to automate the process seamlessly.

To create a DDNS updater application in Python, we can leverage the request library to make HTTP requests to Namecheap’s DDNS API. Namecheap provides an API that allows you to update DNS records associated with your domain name programmatically. Here are the steps to get started.

Securing the API Password with Environment Variables

To enhance security, it is recommended to store sensitive information like the Namecheap API password in an environment variable rather than hardcoding it in your code. This prevents accidental exposure of the password and allows for easier management. Here’s how you can set the environment variable on different platforms:

  • Linux and macO
export DDNS_API_PASSWORD='your_password'
  • Windows (Command Prompt):
set DDNS_API_PASSWORD='your_password'
  • Windows (PowerShell):

The Code

The Python script we’ll be examining is designed to update the NameCheap DDNS service. It retrieves the external IP address, stores it in a file, and performs the necessary DDNS updates using either command-line arguments or a configuration file. Let’s dive into the organization and operation of the code to understand how it accomplishes these tasks.


The code is organized into several sections, each with a specific purpose. Let’s take a closer look at each section:

Import Statements: The script begins with import statements that bring in the necessary modules and packages. These imports include argparse for command-line argument parsing, configparser for reading configuration files, datetime for timestamp handling, os for environment variable retrieval, requests for making HTTP requests, and CustomLogger for logging purposes.

DDNSUpdater Class: Following the import statements, the code defines the DDNSUpdater class. This class encapsulates the logic for updating the NameCheap DDNS service. It includes methods for retrieving the external IP address, storing the last IP address in a file, and updating the DDNS.

CustomLogger Class: The code also includes the CustomLogger class, which provides custom logging functionality. This class is utilized by the DDNSUpdater class to log messages at different levels, such as debug, info, warning, error, exception, trace, and critical.

Main Function: The main function serves as the entry point of the script. It parses command-line arguments using the argparse module, initializes a CustomLogger object for logging, and creates an instance of the DDNSUpdater class with the provided arguments. The script then retrieves the external IP address, stores it in a file, and updates the DDNS using the DDNSUpdater instance. Any exceptions that occur during the process are logged.

#!/usr/bin/env python
This script updates the NameCheap dynamic DNS (DDNS) service.

It retrieves the external IP address, stores it in a file, and
updates the DDNS using the provided arguments or a config file.

    python ddns_updater.py [--domain DOMAIN] [--host HOST] [--log-file LOG_FILE] [--ip-file IP_FILE]


import argparse
import configparser
import datetime
import os

import requests

from custom_logger import CustomLogger

class DDNSUpdater:
    DDNSUpdater is responsible for updating a NameCheap dynamic DNS (DDNS) service.

        logger (CustomLogger): An instance of CustomLogger for logging.
        config_file (str, optional): Path to the config file. Defaults to None.
        host (str, optional): Host/subdomain to update. Defaults to "@".
        domain (str, optional): Domain name for DDNS update. Defaults to "example.com".
        api_password (str, optional): API password for the DDNS service. Defaults to "1234567890".
        ip_file (str, optional): Name of the file to store the last IP address. Defaults to "last_ip.txt".
        log_file (str, optional): Name of the log file. Defaults to "test.log".

    def __init__(self, logger, config_file=None, host: str = "@", domain: str = "example.com",
                 api_password: str = "1234567890", ip_file="last_ip.txt", log_file: str = "test.log"):
        self.domain = domain
        self.host = host
        self.log_file = log_file
        self.ip_file = ip_file
        self.api_password = api_password
        self.logger = logger

        self.config = configparser.ConfigParser()
        if config_file:

    def read_config_value(self, section, key):
        Reads a value from the config file.

            section (str): Section name in the config file.
            key (str): Key name in the specified section.

            str: The value from the config file, or None if the section or key is not found.
            return self.config.get(section, key)
        except (configparser.NoSectionError, configparser.NoOptionError):
            return None

    def get_external_ip_address(self):
        Retrieves the external IP address.

            str: The external IP address.

            requests.exceptions.RequestException: If there is an error retrieving the IP address.
            response = requests.get("http://ipecho.net/plain")
            return response.text.strip()
        except requests.exceptions.RequestException as e:
            self.logger.error(f"Failed to retrieve external IP address: {str(e)}")

    def store_last_ip(self, ip_address):
        Stores the last IP address in a file.

            ip_address (str): The IP address to store.
        now = datetime.datetime.now().strftime('%m/%d/%Y - %H:%M:%S')
        line = f"{ip_address} @ {now}\n"
            with open(self.ip_file, 'w') as file:
        except IOError as e:
            self.logger.error(f"Failed to store last IP address: {str(e)}")

    def update_ddns(self):
        Updates the DDNS.

            str: The response from the DDNS update.

            requests.exceptions.RequestException: If there is an error updating the DDNS.
        url = f"https://dynamicdns.park-your-domain.com/update?host={self.host}&domain={self.domain}&password={self.api_password}"
            response = requests.get(url)
            return response.text.strip()
        except requests.exceptions.RequestException as e:
            self.logger.error(f"Failed to update DDNS: {str(e)}")

def main():
    Entry point of the script.
    parser = argparse.ArgumentParser(description="NameCheap Dynamic DNS Updater")
    parser.add_argument("--domain", "-d", help="Domain name for DDNS update")
    parser.add_argument("--host", "-hs", help="Host/subdomain to update")
    parser.add_argument("--log-file", "-lf", help="Log file name")
    parser.add_argument("--ip-file", "-ip", help="IP file name")
    args = parser.parse_args()

    logfile = args.log_file if args.log_file else "test.log"
    logger = CustomLogger(logfile)
    updater = DDNSUpdater(logger, config_file=None)

    updater.domain = args.domain
    updater.host = args.host
    updater.log_file = args.log_file
    updater.ip_file = args.ip_file
    updater.api_password = os.environ.get('DDNS_API_PASSWORD')

    # Perform the DDNS update
        external_ip = updater.get_external_ip_address()
        response = updater.update_ddns()
        logger.info(f"DDNS update response: {response}")
    except Exception as e:
        logger.error(f"An error occurred during DDNS update: {str(e)}")

if __name__ == '__main__':


The script operates as follows:

Argument Parsing: The script uses the argparse module to parse command-line arguments. Users can provide values for the domain, host, log file, and IP file.

Logger Initialization: A CustomLogger object is created to handle logging. It uses the specified log file or defaults to “test.log”. The logger is configured to use the system timezone if enabled.

DDNSUpdater Initialization: An instance of the DDNSUpdater class is created, passing the logger and other parameters. If a configuration file is provided, it is read and parsed. The DDNSUpdater instance is configured with the domain, host, log file, IP file, and API password.

IP Address Retrieval: The get_external_ip_address method of the DDNSUpdater instance is called to retrieve the external IP address. It makes an HTTP request to “http://ipecho.net/plain” and returns the response.

IP Address Storage: The retrieved IP address is stored in a file along with the current timestamp using the store_last_ip method of the DDNSUpdater instance.

DDNS Update: The update_ddns method of the DDNSUpdater instance is called to update the DDNS. It constructs a URL with the necessaryparameters (host, domain, and API password) and makes an HTTP GET request to the NameCheap DDNS service. The response from the update is returned.

Logging and Exception Handling: The script logs the update response or any exceptions that occur during the DDNS update process. The logger records debug, info, warning, error, exception, trace, and critical messages as needed.


The Python script we’ve explored provides a streamlined solution for updating the NameCheap DDNS service. By retrieving the external IP address, storing it in a file, and performing the necessary updates, the script automates the process and ensures that the associated domain name always points to the correct IP address. The code’s organization promotes modular and reusable components, making it easy to maintain and extend.

By understanding the organization and operation of the code, you can leverage and adapt it to suit your specific needs. Whether you’re working with NameCheap DDNS or similar services, this script serves as a foundation for automating dynamic DNS updates in your Python projects.


Leave a Reply

Your email address will not be published. Required fields are marked *