DtDNS IP Update API Specification
e-mail: admin@dtdns.com
Version: 2.26.1
Updated: August 25, 2011
Copyright (C) 2000-2012, 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.