DtDNS IP Update API Specification e-mail: firstname.lastname@example.org 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=18.104.22.168 Does: This example updates hostname testhost on the domain dtdns.net, with password test, to the ip address 22.214.171.124. 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.