DDNS.org Syntax - API def

Introduction

DDNS.org offers a dyndns endpoint compatible with protocol v2 and v3 of dyndns.org

The protocol has been expanded to support and overcome Browser modification like the prohibition to embed authentication in URLs.

Here we show the full protocol accepted by DDNS.ORG.

Basic Syntax

All requests must be sent to endpoint update.ddns.org using HTTP protocol and Basic HTTP Authentication.

The basic request is the following:

https://update.ddns.org/nic/update?hostname=HOSTNAME

where:

  • HOSTNAME is the full hostname to update (ie. myhostname.fixip.org).

IP Update

After receiving this request, DDNS.ORG gets the public IP from where the request originates and sets the Hostname. In 60 seconds, the hostname starts to respond with the IP of the connection.

Response codes

The response for the request is one word followed by optional additional information.

Response Additional Data Example Meaning
ok IP Received ok 8.8.8.8 The IP has been accepted and the hostname has been updated.
nochg IP Received nochg 8.8.8.8 The IP is already assigned to the Hostname. The client should send updates only when the IP changes. Sending duplicate updates is considered abusive behavior.
badauth - badauth The server can not authenticate the request for the hostname using the user and password sent.
!donor - !donor The action requested is reserved to active account. The account can be expired.
abuse - abuse The account has been suspended due to abusive behavior
911 - 911 The server is experiencing a major issue. The client must wait 10 minutes before sending more updates.

Parameters

The request can include more parameters, all in the query string. All parameters that can be included in request follows. Only the hostname is required.

Parameter Values Example Meaning
hostname the full hostname hostname = myhost.fixip.org The hostname to update. This parameter must be present in every request
myip any public IP myip=8.8.8.8 The IP to use to update the hostname. If not present in the request, the server will use the IP address from which the request originates
wildcard ON or OFF wildcard=ON Activates/Deactivates all fourth level domains pointing to the main hostname. For example www.hostname.ipfix.it
username valid username username=fred The username to authenticate the request. Used instead of the 'Authorization' HTTP header with the parameter password
password valid password password=1234 The password to authenticate the request. Used instead of the 'Authorization' HTTP header with the parameter username
key valid hostkey key=xfgt The key to authenticate the request. Used instead of the 'Authorization' HTTP header and the username and password parameters
mx - deprecated Used in the past to assign a mailserver for the hostname
system - deprecated Used in the past to distinguish between dynamic and static domains

Examples

The update protocol is based on HTTP and can be easily tested using a web browser. In the following examples you should insert the values from your account.

Update hostname using the current connection IP:

The hostname will point to the IP of the connection from where the request is sent.

    https://update.ddns.org/nic/update?hostname=HOSTNAME

Update hostname with explicit IP to use:

The hostname will point to the IP sent.

    https://update.ddns.org/nic/update?hostname=HOSTNAME&myip=IPV4

{warning} DDNS.ORG accepts only public IPs. Private IPs like 192.168.x.x or 10.x.x.x are not assigned to hostnames.

Embed authentication with user and password

You can pass username and password as query string parameters without using an 'Authorization' Header

    https://update.ddns.org/nic/update?hostname=HOSTNAME&username=USERNAME&password=PASSWORD

Embed authentication with key

You can pass HOSTKEY as query string parameters without using an 'Authorization' Header

    https://update.ddns.org/nic/update?hostname=HOSTNAME&key=HOSTKEY

Technical Notes

  1. All interactions with the DDNS.ORG update platform are made via HTTP/HTTPS protocol using exclusively the GET method.
  2. The DDNS.ORG server is available at the address: update.ddns.org, on port 80 for HTTP and on port 443 for the HTTPS.
  3. Parameters are sent to the DDNS.ORG update platform as name/value pairs as part of the HTTP query string. Please note that all parameters are optional while only the hostname is mandatory. List of parameters
  4. Authentication is required for all requests. DDNS.ORG platform accepts different authentications method to update hostnames.
  5. The general authentication method uses Basic HTTP Authentication. This method, commonly used by browsers, requires a Header, containing user and password, encoded in base64. For more information consult https://en.wikipedia.org/wiki/Basic_access_authentication
  6. An alternative authentication method requires the inclusion of USERNAME and PASSWORD parameters in the query string.
  7. Last authentication method requires the inclusion of a KEY parameter in the query string. The key is specific for every hostname and can be generated on the Hostname Detail page.
  8. After every request, the client receives a RESPONSE from the DDNS.ORG update platform in a one-word code followed by any additional information. The client reading the RESPONSE can understand if the update requested has been successful. List of responses

RAW HTTP Request Example

The generic request to the DDNS.ORG update platform, using Basic HTTP Authentication:

GET /nic/update?hostname=[MY-HOSTNAME] HTTP/1.1
Host: update.ddns.org
Authorization: Basic [BASE64-ENCODED-USERNAME:PASSWORD-PAIR]
User-Agent: [DEVICE-MODEL-MAKE-VERSION]