IP Update Protocol  IP Update Protocol

Overview


The IP update protocol is used to control the state of dynamic DNS and email services which are signed up for. This HTTP/HTTPS based protocol has been in use since 1997 for Dynu services. The latest version of API is 2.4.21.

Support
We provide a fully restful API with direct and powerful access to a vast array of features. Companies, developers and researchers can incorporate our innovative services directly into software and services.


Methodology


  • All interaction with the IP update server are made via HTTP/HTTPS protocol using exclusively the GET method. HTTP IP update server is available on ports 80 and 8245 while the HTTPS API server is available on port 443. Port 8245 is highly recommended for HTTP based requests in order to avoid alterations to requests done by any HTTP based proxy server.
  • Authentication is required for most queries/actions using 'Authorization' HTTP header. The Base 64 encoded string will contain a username:password combination. The username may be obtained from the control panel . The authentication credentials may also be sent across as URL querystring parameters.
  • Parameters are passed to the IP update server as name/value pairs as part of HTTP querystring. Please note that some parameters are optional while others are mandatory.
  • The RESPONSE from the IP update server is a one word return code followed by any additional information.
  • Example HTTP Request:

    GET /nic/update?hostname=example.dynu.com&myip=198.144.117.32 HTTP/1.1
    Host: api.dynu.com
    Authorization: Basic [BASE64-ENCODED-USERNAME:PASSWORD-PAIR]
    User-Agent: [DEVICE-MODEL-MAKE-VERSION]

NOTE: Basic auth embedded in URL is NO LONGER supported by most browsers. Please refer to the following issue regarding Chrome:
https://code.google.com/p/chromium/issues/detail?id=123150

If the browser does not support basic auth embedded in URL , you can simply pass the USERNAME and PASSWORD parameters as part of querystring parameters to test the API. Please note that you may pass the MD5 hash of the password instead of the actual password for security reasons.

If following does not work:
http://username:password@api.dynu.com/nic/update?hostname=example.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4

Use the following:
http://api.dynu.com/nic/update?hostname=example.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&username=someusername&password=MD5(xxxxx)

Usage

wget "http://api.dynu.com/nic/update?hostname=example.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&username=someusername
&password=098f6bcd4621d373cade4e832627b4f6"


Wget does not support basic authentication embedded in URL Wget does not support basic authentication embedded in URL so pass in password(or MD5 hash of the password) as a query string parameter. Be sure to enclose the URL in double quotes otherwise the parameters will not be sent by Wget.

Requests


There are many types of requests which can be directed towards the IP update server. Some are informational in nature while others are action based. All requests without exception will be responded with a 'response code' indicating the validity of the request processed.

Primary IP Address Update

This action is used to update the primary IP address for the domain name. Either the username or hostname can be supplied.

Parameters:

PASSWORD  The password may be supplied normally or as a MD5 hash for security reasons. Be sure to take advantage of setting up a separate IP update password different from the account password.

USERNAME  Providing the username and no hostnames will update the IP address for all hostnames in the account associated with the username.

LOCATION  Use 'location' parameter if you want to update IP address for a collection of hostnames including those created using aliases. Please note that the 'username' and 'password' parameters are mandatory when using location. The 'hostname' parameter is ignored when location parameter is used.

HOSTNAME  One or more comma separated host names whose IP address requires update. If you wish to update the IP address of all hostnames in the account, leave hostname empty.

IP ADDRESS  IPv4 address to be used for update. This field is OPTIONAL. If IP addrss is not sent as part of the request, the API server will use the IP address from which the request originates. The special IP address 10.0.0.0 is replaced with the IP address from which the request originates and you may use it with routers which disallow empty IP address field.

IPv6 ADDRESS  IPv6 address to be used for update. If IPv6 address is not sent as part of the request, the API server will NOT be able to update the IPv6 address and will only update IPv4 address for the hostname.

URL Format: http://api.dynu.com/nic/update?hostname=[HOSTNAME]&myip=[IP ADDRESS]&myipv6=[IPv6 ADDRESS]&password=[PASSWORD or MD5(PASSWORD)] http://api.dynu.com/nic/update?username=[USERNAME]&myip=[IP ADDRESS]&myipv6=[IPv6 ADDRESS]&password=[PASSWORD or MD5(PASSWORD)]
SSL URL Format: https://api.dynu.com/nic/update?hostname=[HOSTNAME]&myip=[IP ADDRESS]&myipv6=[IPv6 ADDRESS]&password=[PASSWORD or MD5(PASSWORD)] https://api.dynu.com/nic/update?username=[USERNAME]&myip=[IP ADDRESS]&myipv6=[IPv6 ADDRESS]&password=[PASSWORD or MD5(PASSWORD)]

Examples

1) Update IP address for all hostnames associated with location 'work'.

URL: http://api.dynu.com/nic/update?username=jamesd&location=work&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6
SSL URL: https://api.dynu.com/nic/update?username=jamesd&location=work&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6

2) Update IP address for hostname example.dynu.com with IP address 198.144.117.32 and IPv6 address 2604:4400:a:8a::f4.

URL: http://api.dynu.com/nic/update?hostname=example.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6
SSL URL: https://api.dynu.com/nic/update?hostname=example.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6

3) Update IP address for hostname example1.dynu.com and example2.dynu.com with IP address 198.144.117.32 and IPv6 address 2604:4400:a:8a::f4.

URL: http://api.dynu.com/nic/update?hostname=example1.dynu.com,example2.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6
SSL URL: https://api.dynu.com/nic/update?hostname=example1.dynu.com,example2.dynu.com&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6

4) Update IP address for all hostnames with IP address 198.144.117.32 and IPv6 address 2604:4400:a:8a::f4 for user jamesd.

URL: http://api.dynu.com/nic/update?username=jamesd&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6
SSL URL: https://api.dynu.com/nic/update?username=jamesd&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6

Alias/Subdomain IP Address Update

This action is used to update the IP address of a alias/subdomain for the domain name. Please make sure to add this alias/subdomain in the 'Aliases/Subdomains' section in the control panel for the domain name. If 'Wildcard' option is enabled in the control panel , virtually all aliases/subdomains point to the primary IP address by default.

Parameters:

PASSWORD  The password may be supplied normally or as a MD5 hash for security reasons. Be sure to take advantage of setting up a separate IP update password different from the account password.

HOSTNAME  A single hostname whose alias requires IP address update.

ALIAS  The alias of hostname whose IP address requires update.

IP ADDRESS  IP address to be used for update. This field is OPTIONAL. If IP address is not sent as part of the request, the API server will use the IP address from which the request originates. The special IP address 10.0.0.0 is replaced with the IP address from which the request originates and you may use it with routers which disallow empty IP address field.

IPv6 ADDRESS  IPv6 address to be used for update. If IPv6 address is not sent as part of the request, the API server will NOT be able to update the IPv6 address and will only update IPv4 address for the hostname.

URL Format: http://api.dynu.com/nic/update?hostname=[HOSTNAME]&alias=[ALIAS]&myip=[IP ADDRESS]&myipv6=[IPv6 ADDRESS]&password=[PASSWORD or MD5(PASSWORD)]
SSL URL Format: https://api.dynu.com/nic/update?hostname=[HOSTNAME]&alias=[ALIAS]&myip=[IP ADDRESS]&myipv6=[IPv6 ADDRESS]&password=[PASSWORD or MD5(PASSWORD)]

Examples:

Update IP address for subdomain camera2.mydomain.com with IP address 198.144.117.32 and IPv6 address 2604:4400:a:8a::f4. The domain name registered for dynamic DNS is 'mydomain.com'. The alias in this case is 'camera2'.

URL: http://api.dynu.com/nic/update?hostname=mydomain.com&alias=camera2&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6
SSL URL: https://api.dynu.com/nic/update?hostname=mydomain.com&alias=camera2&myip=198.144.117.32&myipv6=2604:4400:a:8a::f4&password=098f6bcd4621d373cade4e832627b4f6

Setting 'Signoff' status

This action is used when the server/router is going offline and would like to point the domain name to an offline message or offline URL. The offline action itself can be setup in the control panel .

Parameters:

PASSWORD  The password may be supplied normally or as a MD5 hash for security reasons. Be sure to take advantage of setting up a separate IP update password different from the account password.

HOSTNAME  A single hostname whose IP address requires update.

URL Format: http://api.dynu.com/nic/update?hostname=[HOSTNAME]&password=[PASSWORD or MD5(PASSWORD)]&offline=yes
SSL URL Format: https://api.dynu.com/nic/update?hostname=[HOSTNAME]&password=[PASSWORD or MD5(PASSWORD)]&offline=yes

Examples:

URL: http://api.dynu.com/nic/update?hostname=mydomain.com&password=098f6bcd4621d373cade4e832627b4f6&offline=yes
SSL URL: https://api.dynu.com/nic/update?hostname=mydomain.com&password=098f6bcd4621d373cade4e832627b4f6&offline=yes

EMAIL: ETRN Route Update

This action is used to inform Dynu email servers to route emails for a given domain name to its primary email server. The mode of email service in the control panel should be setup as 'Email Store/Forward'.

Parameters:

PASSWORD  The password may be supplied normally or as a MD5 hash for security reasons.

DOMAIN NAME  A single domain name whose emails are to be routed to its primary email server.

IP ADDRESS  IP address of the primary email server. This field is OPTIONAL. If IP address is not sent as part of the request, the API server will use the IP address from which the request originates. The special IP address 10.0.0.0 is replaced with the IP address from which the request originates and you may use it with routers which disallow empty IP address field.

PORT  The port number on which the primary email server is running. If your ISP is blocking inbound port 25, we recommend that you run your email server on a non-standard port such as 26 or 2525.

URL Format: http://api.dynu.com/etrn/update?hostname=[DOMAIN NAME]&password=[PASSWORD or MD5(PASSWORD)]&myip=[IP ADDRESS]&port=[PORT]
SSL URL Format: https://api.dynu.com/etrn/update?hostname=[DOMAIN NAME]&password=[PASSWORD or MD5(PASSWORD)]&myip=[IP ADDRESS]&port=[PORT]

Examples:

URL: http://api.dynu.com/etrn/update?hostname=mydomain.com&password=098f6bcd4621d373cade4e832627b4f6&myip=198.23.87.112&port=26
SSL URL: https://api.dynu.com/etrn/update?hostname=mydomain.com&password=098f6bcd4621d373cade4e832627b4f6&myip=198.23.87.112&port=26

Response Codes


When an API 'request' is made, the API server will respond with a 'response code'. The client software should use the response codes to communicate a friendly message back to the user. Please note that in cases where multiple 'requests' are sent using a single HTTP request(for example, updating IP address for multiple domain names), multiple 'response codes' will be returned separated by a break(CRLF). Please refer to each individual 'request' for appropriate 'response codes'. Below are some common 'response codes':

unknown  This response code is returned if an invalid 'request' is made to the API server. This 'response code' could be generated as a result of badly formatted parameters as well so parameters must be checked for validity by the client before they are passed along with the 'request'.

good  This response code means that the action has been processed successfully. Further details of the action may be included along with this 'response code'.

badauth  This response code is returned in case of a failed authentication for the 'request'. Please note that sending across an invalid parameter such as an unknown domain name can also result in this 'response code'. The client must advise the user to check all parameters including authentication parameters to resolve this problem.

servererror  This response code is returned in cases where an error was encountered on the server side. The client may send across the request again to have the 'request' processed successfully.

nochg  This response code is returned in cases where IP address was found to be unchanged on the server side.

notfqdn  This response code is returned in cases where the hostname is not a valid fully qualified hostname.

numhost  This response code is returned in cases where too many hostnames(more than 20) are specified for the update process.

abuse  This response code is returned in cases where update process has failed due to abusive behaviour.

nohost  This response code is returned in cases where hostname/username is not found in the system.

911  This response code is returned in cases where the update is temporarily halted due to scheduled maintenance. Client must respond by suspending update process for 10 minutes upon receiving this response code.

dnserr  This response code is returned in cases where there was an error on the server side. The client must respond by retrying the update process.

!donator  This response code is returned to indicate that this functionality is only available to members.

GnuDIP Support


Both TCP and HTTP based GnuDIP is fully supported. Routers supporting GnuDIP IP update as well as any GnuDIP based IP update clients may be used to make full use of this functionality.

GnuDIP TCP Server: gnudip.dynu.com
GnuDIP TCP Port: 3495

GnuDIP HTTP URL: http://gnudip.dynu.com/gnudip/cgi-bin/gdipupdt.cgi
GnuDIP HTTP Ports: 80, 8245(port 8245 is preferred to avoid issues related to proxies)