Setting up Dynamic DNS

Understanding Dynamic DNS (DDNS)

Dynamic DNS (DDNS) is a service that automatically updates a domain name's DNS records whenever its associated IP address changes. This is particularly useful for users whose Internet Service Providers (ISPs) assign dynamic IP addresses, which can change without notice. With DDNS, you can maintain a consistent, easy-to-remember hostname for accessing your home network, servers, or other internet-connected devices.

How Does DDNS Generally Work?

The typical process for DDNS operation involves the following steps:

• Client Setup: A DDNS client software or a feature built into a network device (like a router or NAS) is configured with your DDNS provider's details and the hostname you wish to keep updated.
• IP Address Monitoring: The DDNS client periodically checks the current public IP address of your network.
• Change Detection: If the client detects that the public IP address has changed, it initiates an update.
• Secure Update: The client securely communicates with your DDNS provider's update server (usually via an API). It authenticates itself and sends the new IP address along with the specific hostname(s) to be updated.
• DNS Record Update: The DDNS provider validates the request and updates the DNS A (for IPv4) or AAAA (for IPv6) record for your specified hostname to point to the new IP address.
• Propagation: As with any DNS change, this update needs some time to propagate across the internet's DNS servers. Once propagated, anyone trying to access your hostname will be directed to the new IP address.

Sitelutions DDNS Service (API v2)

Sitelutions provides a modern, secure Dynamic DNS (DDNS) service using our API v2 endpoint. This system uses an API Key for authentication instead of your main account password, providing enhanced security.

Please Note: This service requires you to have a registered domain name (e.g., yourdomain.com) under your account. Due to past abuse, we no longer support DDNS for free subdomains (such as yoursubdomain.findhere.org). You must use a domain you have registered.

To use the service, you will need two pieces of information: your Record Identifier(s) and your API Key.

1. How to Find Your Record Identifier (ID)

The "Record Identifier" is required for the client to know which DNS record to update. You can find this ID in your Sitelutions dashboard:

1. Log in to your Sitelutions account.
2. Navigate to DNS Management from the side menu.
3. Find the domain you wish to update (e.g., yourdomain.com) and click the three-dot menu (...) on the right.
4. Select Manage from the dropdown.
5. On the "DNS Records" page, locate the specific A or AAAA Record you want to keep updated (e.g., home.yourdomain.com).
6. Click the three-dot menu (...) on the far right of that record's row.
7. Select Dynamic DNS from the dropdown.
8. The next page will display the "Record Identifier". This numeric ID (e.g., 554536) is the legacy-compatible ID for use with most DDNS clients.

Our V2 API also supports a modern identifier (zone_id:record_id), but the numeric ID is the simplest method for DDNS.

2. How to Generate Your API Key

The new DDNS service requires an API Key for authentication. You can generate and manage your API Keys from the [API Credentials] section of your DNS management page (at the bottom of the main DNS Management page).

3. The API v2 Update Endpoint

To update your IP address, your DDNS client must send secure updates to the following URL:

https://api2.sitelutions.com/dnsup

The API accepts parameters via a standard HTTP GET request. See the examples below.

Supported Parameters:

• user: (Required) Your Sitelutions account email address.
• pass: (Required) Your generated API Key. Must be URL-Encoded.
• id: (Required) The numeric Record Identifier(s) to update. Multiple IDs can be sent, separated by a comma (e.g., id=554536,554538).
• ip: (Required) The new IPv4 or IPv6 address.
• ttl: (Optional) The Time-To-Live for the DNS record (minimum 60 seconds).

Official Sitelutions DDNS Client (Recommended)

For Windows users, we provide an official, easy-to-use desktop application that runs in your system tray and handles all IP updates automatically. It uses the secure api2 endpoint and requires the Record Identifier and API Key mentioned in this article.

• Download (Windows .exe): Download Sitelutions-DDNS-Updater.exe
• Source Code & Full Documentation: View on GitHub

Example Scripts for Custom DDNS (api2)

If you are not using the official Windows client or wish to create your own script (for routers, Linux, etc.), you can use the examples below. These scripts demonstrate how to interact with the api2 DDNS service.

Disclaimer: The following scripts are provided as examples. You must modify them for your specific environment. Using HTTPS is crucial for protecting your credentials.

PHP Script Example

This PHP script demonstrates how to send an update request. It correctly uses urlencode() to ensure special characters in your API key are transmitted safely.

<?php
  // Multiple IDs can be comma-separated
  $aRecordIDs = "554536,554538"; // Replace with your specific Record ID(s)
  
  // Get public IP from Sitelutions' IP service (recommended)
  $strNewIpAddress = trim(@file_get_contents("https://api2.sitelutions.com/myip"));
  
  if (empty($strNewIpAddress)) {
    die("<p>Error: Could not fetch public IP address.</p>");
  }

  $strTTL = "60"; // Time-To-Live in seconds
  $strUsername = "your_email@your_domain.com"; // Your Sitelutions login email
section $strPassword = "YOUR_API_KEY"; // IMPORTANT: This is your API Key, NOT your account password.

  echo "<h1>Processing Sitelutions DNS Update...</h1>";
  
  // Use http_build_query to correctly URL-encode all parameters, especially the API Key
  $queryParams = [
    'user' => $strUsername,
    'pass' => $strPassword,
    'id'   => $aRecordIDs,
    'ip'   => $strNewIpAddress,
    'ttl'  => $strTTL
  ];
Example  $updateUrl = "https://api2.sitelutions.com/dnsup?" . http_build_query($queryParams);
  
  $response = @file_get_contents($updateUrl);
  
  if ($response === FALSE) {
    echo "<p>Error: Could not connect to the DDNS update server.</p>";
  } else {
    echo "<p>Server Response:</p>";
    echo "<pre>".trim(htmlspecialchars($response))."</pre>";
  }
  
  flush();
?>

Key Variables (PHP):

• $aRecordIDs: The numeric ID(s) of the A record(s) you wish to update. Can be one ID ("554536") or multiple IDs ("554536,554538").
• $strUsername: Your Sitelutions account email.
• $strPassword: This is your API Key, not your Sitelutions account password.

Shell Script Example (sitelutions_dns_update.sh)

This shell script is for Unix-like systems. It demonstrates the correct way to URL-encode your API key using curl or wget to prevent authentication errors.

#!/bin/sh
#
# sitelutions_dns_update.sh (api2 Version)
#
# This script updates Dynamic DNS Records on Sitelutions.com's
# DNS servers using the recommended api2 endpoint.
#

# Your Sitelutions login e-mail address
SLUSER="your_email@your_domain.com"

# Your Sitelutions API Key (NOT your account password)
# This key may contain special characters like + or /
SLPASS="YOUR_API_KEY"

# Record ID(s) of your Sitelutions A record(s) to update.
# Multiple IDs can be comma-separated: e.g., SLID="554536,554538"
SLID="554536"

# TTL (Time-To-Live) for the record, e.g., 60 for 1 minute
SLTTL=60

# Obtain current public IP address using the Sitelutions service (recommended)
IPADDR=$(curl -s https://api2.sitelutions.com/myip)

if [ -z "$IPADDR" ]; then
  logger -t Sitelutions.com -s "Failed to obtain public IP address."
  exit 1
fi

API_ENDPOINT="https://api2.sitelutions.com/dnsup"
LOG_FILE="/tmp/sitelutions_ddns_update.log" # Or /dev/null

logger -t Sitelutions.com "Attempting to update DDNS for $SLID with IP $IPADDR"

# Using curl:
if command -v curl > /dev/null; then
  # Use -G to send data as a GET request
  # Use --data-urlencode to ensure the API key (SLPASS) is safely encoded
  RESPONSE_CONTENT=$(curl -s -G \
    --data-urlencode "user=$SLUSER" \
    --data-urlencode "pass=$SLPASS" \
    --data-urlencode "id=$SLID" \
    --data-urlencode "ip=$IPADDR" \
    --data-urlencode "ttl=$SLTTL" \
    "$API_ENDPOINT")
  echo "$RESPONSE_CONTENT" > "$LOG_FILE"
  
# Using wget:
elif command -v wget > /dev/null; then
  # wget automatically URL-encodes parameters passed in this way
  WGET_URL="$API_ENDPOINT?user=$SLUSER&pass=$SLPASS&id=$SLID&ip=$IPADDR&ttl=$SLTTL"
  wget -q -O "$LOG_FILE" "$WGET_URL"
  RESPONSE_CONTENT=$(cat "$LOG_FILE")

else
  logger -t Sitelutions.com -s "Neither wget nor curl is installed. Update failed."
  exit 1
fi

# Check for a "success" response
if echo "$RESPONSE_CONTENT" | grep -q "success"; then
    logger -t Sitelutions.com -s "DNS Record $SLID updated to $IPADDR. Server: $RESPONSE_CONTENT"
else
    logger -t Sitelutions.com -s "Problem updating DNS record $SLID. Server: $RESPONSE_CONTENT"
fi

Key Variables & Configuration (Shell):

• SLUSER: Your Sitelutions account email.
• SLPASS: This is your API Key. The script now correctly handles special characters.
• SLID: The numeric ID(s) to update. You can provide multiple IDs separated by a comma.
• IPADDR: The script automatically fetches your public IP.