Detecting the IP Change

To determine whether a client should update, it must have a reliable method to determine what its current IP address is so it can compare the current address to the last updated address. There are two methods.

Internal Method

A client may determine, automatically or through the input of the user, that it is directly connected to the Internet. The device would have a publicly addressable IP address. In this case, the optimal method is to obtain the IP address from the operating system’s network stack.

Web IP Detection (CheckIP)

A client may determine, automatically or through the input of the user, that it is not directly connected to the Internet. The client is on a machine with a private IP, usually on RFC 1918 space (10/8, 172.16/12, 192.168/16). In this case, the optimal method is to use web IP detection.

Dyn.rs operates a CheckIP service which may be used with clients that work with DynDNS.

Update Requests

After a change in IP address has been detected or a user alters any of their settings, the client should perform an update. All updates are sent using a well-formed HTTP request. The system will pass back a return code in the response body that the client needs to parse.

The HTTP Request

Hostname: dyn.rs
URI: /v3/update
Methods: GET, POST
HTTP Ports: 80, 8245
HTTPS Port: 443

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

All requests should be sent to hostname dyn.rs. 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.

Examples

These examples are provided only as samples, for better understanding of the process.


Authentication in URL

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

https://{username}:{password}@dyn.rs/v3/update?hostname={hostname}&myip={IP Address}

Curl command-line example

curl -ks -u {username}:{password} "https://dyn.rs/v3/update/?hostname={hostname}&myip={IP Address}"

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 /v3/update?hostname=yourhostname&myip=ipaddress HTTP/1.0
Host: dyn.rs
Authorization: Basic base-64-authorization
User-Agent: Company - Device - Version Number

Please note that both GET and POST requests are permitted and will be processed.


Update Parameters

Field Description Additional Info
hostname Comma separated list of hostnames that you wish to update (up to 5 hostnames per request). This is a required field. Each hostname specified will be updated with the same information, and the final return code will be returned.

For example, if your username is johndoe, your primary hostname will be johndoe.dyn.rs. Let's say you have already created two additional hostnames in the control panel: home.johndoe.dyn.rs and work.johndoe.dyn.rs.
Beside specifying the full hostnames, you can also use only 4th level names. If you'd like to update your default hostname johndoe.dyn.rs, which is a most common case, you could also specify an empty string or just - as a hostname. Example:

   hostname=johndoe.dyn.rs
or hostname=-
or hostname=
To update all three hostnames with the same IP at once, you can specify the hostnames in one of the following ways:
   hostname=johndoe.dyn.rs,home.johndoe.dyn.rs,work.johndoe.dyn.rs
or hostname=-,home,work
or hostname=,home,work
Notice the comma at the beginning, which delimits an empty string for your primary hostname.
myip IPv4 or IPv6 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.

Return Codes

When updating a hostname, the response to the update request will be one of the short return codes described below, followed by one space or tab character, and the appropriate message (everything after the first blank character to the end of the line). If there is an error, clients should communicate to the user a brief description of the problem that the return code indicates. All the return codes are given in the response body, with appropriate HTTP codes that indicate success (2xx), client error (4xx), or server error (5xx).

If updating multiple hostnames, only one final code is returned. Return codes indicating a failure with the account or the system are also given only once.

Update Types

Successful Updates

There is only one return code which indicates a successful update. Code good indicates that the update was successful and that the IP address was changed in our system.

No Change Updates

A nochg indicates a successful update but the IP address or other settings have not changed. The only acceptable situation where this allowed is during client initialization when the host has already been set to the same IP address. Users may also be given the option to “force” an update. This can be used to verify the authentication credentials and the current IP address.

As this is fairly infrequent, repeated instances of nochg updates will result in the host being blocked. Users should not be allowed to repeatedly force updates.

While it is not expected that the clients will prevent users from doing this, the client itself should strenuously avoid performing updates which would result in this return result.

Fatal Updates

Any failed update attempt is fatal which means that all further updates will also fail until the user has taken some sort of corrective action. For this reason, any failed update attempt should cause the client to be disabled until the situation is corrected and the client is manually re-enabled by the user.

Additionally, because the update may fail for a number of different reasons, the client needs to provide some method of communicating with the user that the update has failed and why. Some suggestions include:

  • Logging a message in the general log window for the router (assuming it has one)
  • Logging a message to a log window specific to the Dyn Update Client
  • Generating an error message to an email address configured by the user
  • Communicating to an external process running on the users desktop

Many of these errors involve configuration mistakes within the client or inconsistencies between the client configuration and the user’s account status; in all of those cases, the client must stop updating until the user has corrected the problem. Retrying the update automatically in those cases is abuse and may result in client blocks.

Account-Related Errors

The codes below indicate that the client is not configured correctly for the user’s account. These return codes are given just once. The client must stop updating until the user confirms that the problem has been resolved.

badauth

The username and password pair do not match a real user.

noaccess

Account has been disabled (suspendedq).

Update Complete

The codes below indicate that the update of a hostname was completed successfully.

good

The update was successful, and the hostname is now updated.

nochg

The update changed no settings, and is considered abusive. Additional nochg updates will cause the hostname to become blocked.

Note that, for confirmation purposes, good and nochg messages will be followed by the IP address that the hostname was updated to. This value will be separated from the return code by a space.

Hostname-Related Errors

The codes below indicate a problem with a specific hostname. The client must stop updating that hostname until the user confirms that the problem has been resolved.

notfqdn

The hostname specified is not a fully-qualified domain name (not in the form hostname.dyn.rs).

nohost

The hostname specified does not exist in this user account (or is not in service).

numhost

Too many hosts (more than 5) specified in an update.

abuse

The hostname specified is blocked for update abuse.

Agent-Related Errors

badagent

The user agent was not sent or HTTP method is not permitted (we recommend use of GET request method).

good 127.0.0.1

This answer indicates good update only when 127.0.0.1 address is requested by update. In all other cases it warns user that request was ignored because of agent that does not follow our specifications.

Server Error Conditions

The codes below indicate server errors that will have to be investigated. The client must stop updating and ask the user to contact Dyn support. The client must not resume updating until 30 minutes have passed or user confirms that the problem has been resolved.

dnserr

DNS error encountered

911

There is a problem or scheduled maintenance on our side.