Donate to Dyns!
 home |  services |  sign up |  news |  downloads | documentation|  support |  contact 
(not logged in)
> documentation > technical > protocol > v1.1

Protocol V1.1
Introduction

This newer version supports a couple of new features in the DyNS service offering. However , this protocol version is downward compatible. There is no need to update your client if you do not use the new services offered by DyNS.
Posting your IP address to the DyNS server is done by opening a HTTP connection to the web server and invoking a script similar to a CGI script.

The HTTP request

The HTTP request arguments are:

  • URL: http://www.dyns.net/postscript011.php
  • username=(your DyNS username) (required)
  • password=(your DyNS password) (required)
  • hostname=(your DyNS hostname) (required)
  • domain=(your DyNS hostname) (optional)
  • ip=(your IP address) (optional)

Remarks

    hostname
    The hostname argument can also contain the domain name.

    domain
    There are 3 values with a special meaning:
    - 'own' : read the domain from the parameter 'hostname'
    - 'own-domain' : read the domain from the parameter 'hostname'
    - '' (or omitted) : read the domain from the parameter 'hostname'. If no domain found in parameter 'hostname', default to 'dyns.cx'

    ip
    if omitted, defaults to REMOTE_ADDR (Apache server variable)

examples

Example 1:

username = joe
password = foo
hostname = robinson
domain = dyns.cx

HTTP request:


http://www.dyns.net/postscript011.php?username=joe&password=foo&host=robinson

Example 2:

username = joe
password = foo
hostname = robinson
domain = crusoe.com

HTTP request (preferred method):


http://www.dyns.net/postscript011.php?username=joe&password=foo&host=robinson.crusoe.com

other option:

http://www.dyns.net/postscript011.php?username=joe&password=foo&host=robinson&domain=crusoe.com
or:

http://www.dyns.net/postscript011.php?username=joe&password=foo&host=robinson.crusoe.com&domain=own
or:

http://www.dyns.net/postscript011.php?username=joe&password=foo&host=robinson.crusoe.com&domain=own-domain
Reading the result

The server returns a string which you can interpret in the following way:
To determine the result of the script, it's always enough to read the first 3 characters of the result string which represent a decimal value. Following this value, a short description will be provided.
These are the different possible responses:

  • 400 Bad request
    Meaning: The URL was malformed, one of the required parameters was not supplied or the IP address you supplied in your request is invalid.
    Client action: Change your HTTP request.


  • 402 updating too fast (wait n s)
    Meaning: Your update was too fast. The query is discarded.
    Client action: Wait at least n seconds and retry.

  • 403 Database error
    Meaning: There was a server-side database error.
    Client action: Try again in a few moments.

  • 405 Hostname 'worldofjoe' is not one of your hosts
    Meaning: The hostname you want to update is either nonexisting, or you are not owner of this hostname
    Client action: change your HTTP request


  • 200 host worldofjoe updated (111.111.111.111)
    Meaning: update was successful. For verification , the assigned IP address is shown in the result string.
    Client action: nothing.


  • 200 dynforwarder worldofjoe updated (111.111.111.111)
    Meaning: update was successful. For verification , the assigned IP address is shown in the result string.
    Client action: nothing.


Development issues

When developing clients, you can set the script in development mode by supplying an extra argument: 'devel=1'
In that case, the script behaves just like it would when updating for real, except for 2 thing:

  1. Error 402 is disabled
  2. The update is discarded (the DNS is not updated for real)

Final remarks

The SOA record of your dynamic domains shows a timeout value of 5 minutes.
In the worst case, due to DNS caching, your old IP address will remain cached for 5 minutes by DNS caches troughout the world
The average case will be that most updates will be visible immediately troughout the world.
You can query one of our nameservers directly to check your IP address (maximal delay of the DyNS nameservers is 30 seconds)


Copyright (c) 1998-2017 DyNS.
webmaster@dyns.cx - privacy statement