dynDNS offers a dyndns endpoint compatible with protocol v2 and v3 of dyndns.org
The protocol has been expanded to support and overcome Browser modifications like the prohibition to embed authentication in URLs.
Here we show the full protocol accepted by dynDNS.it.
All requests must be sent to the endpoint
update.dyndns.it using HTTP protocol and Basic HTTP Authentication.
The basic request is the following:
- HOSTNAME is the full hostname to update (ie. myhostname.ns0.it).
After receiving this request, dynDNS.it gets the public IP from where the request originates and sets the Hostname. In 30 seconds, the hostname starts to respond with the IP of the connection.
The response for the request is one word followed by optional additional information.
|IP Received||ok 188.8.131.52||The IP has been accepted and the hostname has been updated.|
|IP Received||nochg 184.108.40.206||The IP is already assigned to the Hostname. The client must send updates only when the IP changes. Sending duplicate updates is considered abusive behavior.|
|–||badauth||The server can not authenticate the request for the hostname using the user and password sent.|
|–||!donor||The action requested is reserved to active account. The account can be expired.|
|–||abuse||The account has been suspended due to abusive behavior|
|–||911||The server is experiencing a major issue. The client must wait 10 minutes before sending more updates.|
The request can include more parameters, all in the query string. All parameters that can be included in the request are the following. All parameters are optional, only the hostname is required.
|the full hostname||hostname = myhost.ns0.it||The hostname to update. This parameter must be present in every request|
|any public IP||myip=220.127.116.11||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|
|ON or OFF||wildcard=ON||Activates/Deactivates all fourth-level domains pointing to the main hostname. For example www.myhost.ns0.it|
|valid username||username=fred||The username to authenticate the request. Used instead of the ‘Authorization’ HTTP header with the parameter password|
|valid password||password=1234||The password to authenticate the request. Used instead of the ‘Authorization’ HTTP header with the parameter username|
|valid hostkey||key=xfgt||The key authenticating the request. Used instead of the ‘Authorization’ HTTP header and the username and password parameters|
|–||deprecated||Used in the past to assign a mail server for the hostname|
|–||deprecated||Used in the past to distinguish between dynamic and static domains|
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.
Update hostname with explicit IP to use:
The hostname will point to the IP sent.
dynDNS.it 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
Embed authentication with key
You can pass HOSTKEY as query string parameters without using an ‘Authorization’ Header
- All interactions with the dynDNS.it update platform are made via HTTP/HTTPS protocol using exclusively the GET method.
- The dynDNS.it server is available at the address:
update.dyndns.it, on port 80 for HTTP and on port 443 for the HTTPS.
- Parameters are sent to the dynDNS.it 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.
- Authentication is required for all requests. dynDNS.it platform accepts different authentications method to update hostnames. (HTTP basic auth or username and password as parameters)
- 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
- An alternative authentication method requires the inclusion of USERNAME and PASSWORD parameters in the query string.
- After every request, the client receives a RESPONSE from the dynDNS.it 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.
- The updating script must send updates ONLY when the IP of the connection changes, otherwise it is considered abusive behavior. The IP of the connection can be checked by sending an unauthenticated GET to the https://checkip.dyndns.it endpoint.
RAW HTTP Request Example
The generic request to the dynDNS.it update platform, using Basic HTTP Authentication:
GET /nic/update?hostname=[MY-HOSTNAME] HTTP/1.1 Host: update.dyndns.it Authorization: Basic [BASE64-ENCODED-USERNAME:PASSWORD-PAIR] User-Agent: [DEVICE-MODEL-MAKE-VERSION]
Client structure example
A generic client should implement the following structure:
- Get the current connection IP from http://checkip.dyndns.it
- if the current IP is different from the locally saved IP
- Send the update to update.dyndns.it
- Save the current IP in local storage
- Sleep 5 minutes
- jump to 1