Perform Update

When a change in IP address is found or a user alters any of their settings, the client should perform an update. All updates are sent using a well-formed HTTP request. DynDNS will pass back a return code that the client needs to parse. The update API is a REST-based system.

If you have questions about the syntax, please contact DynDNS Support.

The HTTP Request

Hostname:   members.dyndns.org
HTTP ports:   80, 8245
HTTPS port:   443

Updates can be performed over HTTP or SSL-encrypted HTTPS (preferred).

All requests should be sent to members.dyndns.org. Hard coding the IP address is not acceptable as the IP address may change.

The update interface listens on ports 80 and 8245 for HTTP, and 443 for HTTPS. Port 8245 may be used to bypass transparent HTTP proxies. It is not necessary to open any incoming ports (or allow incoming ICMP) for updating.

All clients must send a well-formed user agent that includes company name, model number, and software build revision. An example would be: Mellenium Inc. - Router 25001 - 1.1

Examples

These examples are provided only as samples. See RFC 2616 for information about the HTTP Protocol.

Authentication in URL

For web-browsers or utility programs (fetch, curl, lwp-request) that can parse authentification section in URL.

http://username:password@members.dyndns.org/nic/update?hostname=yourhostname&myip=ipaddress&wildcard=NOCHG&mx=NOCHG&backmx=NOCHG

Raw HTTP GET Request

Actual HTTP request should look like following fragment. Note that there is the bare minimum set of headers. Request should be followed by sending an empty line.
Fragment base-64-authorization should be represented by Base 64 encoded username:password string.

GET /nic/update?hostname=yourhostname&myip=ipaddress&wildcard=NOCHG&mx=NOCHG&backmx=NOCHG HTTP/1.0
Host: members.dyndns.org
Authorization: Basic base-64-authorization
User-Agent: Company - Device - Version Number

Please note that although POST requests are permitted and will be processed, we don't encourage developers to use them. We might stop processing of POST requests at any time, without notice.

Update Paramter

Field Description Additional Info
hostname Comma separated list of hostnames that you wish to update (up to 20 hostnames per request). This is a required field. Each hostname specified will be updated with the same information, and the return codes will be given one per line, in the same order as given.

Example:
  hostname=test.dyndns.org,customtest.dyndns.org
myip IP address to set for the update. If this parameter is not specified, the best IP address the server can determine will be used (some proxy configurations pass the IP in a header, and that is detected by the server). If the IP address passed to the system is not properly formed, it will be ignored and the system's best guess will be used.
wildcard Parameter enables or disables wildcards for this host. (Deprecated: Flag is currently ignored) ON should be used to enable wildcard. NOCHG value will keep current wildcard settings. Any other value will disable wildcard for hosts in update.

Parameter is ignored for Custom DNS hosts.

mx Specifies a Mail eXchanger for use with the hostname being modified. (Deprecated: Flag is currently ignored) The specified MX must resolve to an IP address, or it will be ignored. Specifying an MX of NOCHG will cause the existing MX setting to be preserved in whatever state it was previously updated via a client or the DynDNS website.

Parameter is ignored for Custom DNS hosts.

backmx Requests the MX in the previous parameter to be set up as a backup MX by listing the host itself as an MX with a lower preference value. (Deprecated: Flag is currently ignored) YES activates preffered MX record pointed to hostname itself, NOCHG keeps the previous value, any other value is considered as NO and deactivates the corresponding DNS record.

Parameter is ignored for situations when no MX value is set for host and for Custom DNS hosts.

offline Sets the hostname to offline mode. YES activates feature and turns on offline redirect for hostname (if set). NOCHG could be used to keep current state.

Parameter is ignored for Static DNS hosts.

This feature is only available to credited users. The !donator return will be used if the account is not credited.

Other Parameters

We will accept these parameters without generating error messages:

  • system, previously used to identify update type
  • url, reserved for future use

All other parameter names could lead to ignoring your update request with the return code abuse.

Special note on WebHops

Currently, Dynamic DNS or Custom DNS hosts assigned to our WebHop servers cannot be updated via our API. This helps prevent customers from accidentally overwriting their redirects, since the hosts must remain assigned to the redirect server in order to function. No errors are returned for these attempts; they simply remain unchanged.

<<  Detect IP Change Process Return Code  >>