DtDNS IP Update API Specification
e-mail: admin@dtdns.com

Version: 2.26.1
Updated: August 25, 2011
Copyright (C) 2000-2017, DtDNS


Release History
---------------
v2.27.0 - 01/15/12 - Updating a hostname within a domain now updates both
                     the base address of the domain and resource record
v2.26.1 - 08/25/11 - Clarify that the HTTP spec requires \r\n end-of-line
v2.26.0 - 02/12/05 - Removed the "blank ip" error message.  Updated
                     information about passing in hostnames as well as
                     internal IP address handling.
v2.25.3 - 01/06/03 - Updated copyrights, removed extraneous information,
                     updated various outdated sections.
v2.25.2 - 04/09/01 - Added SSL support to the server, so this document
                     has been updated to mention that.
v2.25.1 - 02/03/01 - Removed srv tag, changed the "getip" URL, corrected
                     some of the error messages, changed the update script
                     URL (old one will still work for now).
v2.25.0 - 01/16/01 - Modified update format slightly.
v2.20.1 - 08/06/00 - Added offline IP address to server.
v2.20.0 - 06/29/00 - Added domain update support for full domains hosted
                     by DtDNS.  Allows dynamic domain resolution without
                     having to CNAME to a DtDNS subdomain.
v2.10.4 - 03/25/00 - Fixed random spaces before and after the text error
                     messages from the server.  Fixed minor typos in spec.
v2.10.3 - 01/30/00 - Removed the "IP Already Updated" error.
v2.10.2 - 01/07/00 - Updated info a bit, as well as the history.
v2.10.1 - 08/14/99 - Added srv tag and an accompanying error message.
v2.03.1 - 07/23/99 - Added 2 new error messages on the autodns script.
v1.10.0 - 03/10/99 - Second Beta release.
v1.00.0 - 03/02/99 - Initial Beta release.


Basic Operations
----------------
 An auto-update client for the DtDNS service is one that will send the
 user's hostname (or domain name), password, and current IP address to
 the DtDNS service to be updated in our database, and then included in
 the DNS zone files.

 IP update requests are sent via HTTP on port 80 (or 81 if the user is
 behind a proxy server that doesn't allow connections out on port 80),
 as a standard URL request.  We also offer SSL support on port 443 if
 you wish to use a secure connection.


Things to Consider...
---------------------
 The example below shows how the HTTP request should look...

GET /api/autodns.cfm?parameters=values HTTP/1.1\r\n
Host: www.dtdns.com\r\n
User-Agent: Your_Client_Name\r\n
\r\n

 The \r\n sequenses specify a carriate-return + newline.  There should be
 one at the end of every line, and a blank line at the end of the request.

 The User-Agent is not required, but we ask that you include one with the
 name and version of your client for statistical tracking purposes.  If your
 client was called "Updater" and it was release version 2.5, your User-Agent
 might look like "Updater_2.5".

 We have made available a URL that will return the IP address that an update
 request was received from.  This IP would be used when a request is received
 that does not include an IP address.  The URL is...

        http://myip.dtdns.com

 We would also like to ask that your client (especially hardware clients)
 check to make sure that an IP address has actually changed before sending
 an update request.  This will help keep wasted bandwidth and server
 processing down to a minimum.  You can check the current IP address by
 comparing the local system IP address to one obtained via DNS query for
 their hostname or domain name.  Some users may want to schedule updates
 at regular intervals to make use of our auto-offline monitors, in which
 case we ask that these update requests be kept at least 20 minutes apart.
 An option for the user to force a single IP update at any time is also
 encouraged for flexibility.


Standard IP Update
------------------
 The command line (URL) to be sent is as follows...

        http://www.dtdns.com/api/autodns.cfm?<options>

 ...or if you want to use a secure connection...

        https://www.dtdns.com/api/autodns.cfm?<options>

 Available options are listed below.  Each should be setup in a name=value
 pair, and separated by an ampersand.  If you know anything about URLs, you'll
 quickly realize that this is setup just as if you were passing the values
 to a CGI script using the GET method, except here, we're passing them to
 a ColdFusion template, which does all the work.

        id=hostname - This is a required field that will specify what the
                      member's hostname (or domain) is.  This value should
                      ALWAYS be a fully qualified domain name.  It should be a
                      subdomain of one of the available DtDNS domains, or
                      a full domain that DtDNS is hosting.  Please check the
                      hostname for invalid characters and spit out an error if
                      you find any.  See O'Reilly's DNS and BIND 3rd ed. for
                      a complete discussion on what characters are and aren't
                      valid in hostnames and domain names.

                      * NOTE: Hostnames are now passed using the full hostname
                      and the domain name it's on, not just the hostname (ex:
                      test.dtdns.net, myhost.etowns.org, etc.).  Full domain
                      names are passed using just the domain name (ex: blah.com,
                      mydomain.net, etc.).
                      
                      * NOTE: If you pass a host name that is within a domain, 
                      such as host123.somedomain.com both the base address of 
                      the domain and the resource record host123 will be 
                      updated.

        pw=password - This is a required field that will specify the member's
                      password.  This will be compared to what is stored in
                      the userbase for the specified hostname.  If they do not
                      match, an error (specified below) will be returned.

        ip=address -  This field will specify what IP address to update to.
                      If no IP field is specified, the server will take the IP
                      address the request was recieved from.

                      We will attempt to determine if the user is behind a proxy
                      server by testing several common header variables.

                      We recommend giving the user the option of not sending the
                      IP address with IP updates if they are behind a NAT
                      router.  Hardware clients that do not act as a direct
                      bridge should send the user's WAN address, and hardware
                      clients that act as bridges should not send an IP address.

                      DtDNS now provides an "offline IP" for our members to
                      use.  By pointing their hostname or domain to this IP
                      address, anyone trying to visit their web site on port
                      80 will see a standard offline message or be redirected to
                      a URL configured via the web site.  The offline IP
                      address is 0.0.0.0.

        client=name - This is an OPTIONAL parameter to include the name of
                      your update clinet.  Please keep this under 10 characters,
                      and all in one word if possible.  This can be used for
                      tracking purposes, and general statistics.  'Unknown' will
                      be placed in the database if no client is specified.  If
                      you use the User-Agent HTTP header, please use the same
                      value in this field.


   That should be sent all ON ONE LINE.

   Example: autodns.cfm?id=testhost.dtdns.net&pw=test&ip=24.3.122.217
   Does: This example updates hostname testhost on the domain dtdns.net, with
         password test, to the ip address 24.3.122.217.

   Example: autodns.cfm?id=myfulldomain.com&pw=test&client=MyClient
   Does: Updates full domain "myfulldomain.com", with password test, to the
         ip address the request was received from, and sets the client to
         MyClient.

Several messages are returned by the server once the request has been
processed by the system.  They are listed below.  When your program goes
to update a host, it should watch for these return messages and display
some sort of dialog box with your own (or our) version of the message.

Msg :   No hostname to update was supplied.
Desc:   This message is returned when no ID is specified.

Msg :   No password was supplied.
Desc:   Returned when no PW is given.

Msg :   The hostname you supplied is not valid.
Desc:   Returned when ID is not a valid hostname or domain on the system.

Msg :   The password you supplied is not valid.
Desc:   Returned when the value of PW does not match the password defined
        for the value in the ID tag.

Msg :   This account has not yet been activated.
Desc:   Returned when the account has not been activated for usage.

Msg:    Administration has disabled this account.
Desc:   Returned when the disabled bit is active for the specified ID,
        meaning that the hostname or domain name has been disabled for
        some reason.

Msg:    Illegal character in IP.
Desc:   Returned when a non-numeric or period character is detected in the IP
        field when the user has their account setup for A name resolution.
        Having a non-standard IP when set to A resolution causes the service
        to not update the IP database.  Also returned when a number in the IP
        address is higher than 255.