Revision: 1.13 (Date: 2002/06/15 20:05:23)
By Tyler "Crackerjack" MacDonald.
Questions/Comments: www@weedns.com
The weeDNS Update Protocol meets the following goals:
These are the features of weeDNS's Update Protocol:
The following goals/features are set for the future of the protocol:
Requests are in HTTP POST format, with parameters as the posted contents, in application/x-www-form-urlencoded format.
Requests may either have an action field, credential_* fields, but not both. Requests with an action field must also have a valid session cookie. In the event that both an action field, and credential_* fields, are specified, only the action field will be processed; the credential_* fields will be ignored.
The WeedNS Update Server pays attention to the following headers when dealing with a client request:
Unless weedns is the primary accepted language, the WeedNS server will send redundant information in english about the request that is otherwise machine-parsable from the HTTP Response, but may not be human-parsable or neccessarily obvious to a user. This includes messages like "Press the 'Back' button in your browser to leave this screen" and other niceties we want people to see when they are using a web browser to contact the update server.
If the primary accepted language is set to weedns, then these messages are suppressed and only information that actual WeedNS update clients need to know is printed in the most efficient method possible within the constraints of the protocol.
Clients requesting protected resources must send a valid Cookie header including their session key, otherwise they will receive a HTTP Result Code of 403 and no further processing will happen on the server side. See RFC 2109 for more information about HTTP Cookies.
To log in, send the following fields in application/x-www-form-urlencoded format to a weedns update engine:
The names of these fields were based off of the syntax for the Apache::AuthCookie module.
When a login is successful, you will be sent a HTTP Cookie, which should be used to authenticate subsequent requests, until either the expiry time specified in credential_2 is reached, or an attempt to update with the session key results in an authentication failure, at which point basic userid/password authentication should be specified again. A successful login will invalidate any old session keys associated with that account. This means that users logging in through a web based interface will invalidate the session key present in their client software. See the section on Client Efficiency below for more on this.
After a successful login, a WeedNS client can preform two possible actions. These are specified by setting the action field of the application/x-www-form-urlencoded data to the appropriate value; set action to logout to log out, or set it to update to preform a database update. These actions are described in more detail below:
A valid update string is comprised of one or more update requests, seperated by the comma character (","). The update requests are in the format of what(where)=value. The correct syntax for where and value are dependant on the specification of what. While the syntax varies from update to update for these values, the following rules always apply:
The following values are valid for what:
To create new database objects, use the specify new for the what portion of the update request. Currently, only database objects of type HOST (hostnames) are supported. The value portion of the update request should be the identifier for the record being created.
Example: To attempt to create a new hostname called joe.weedns.com, the following would be a suitable value
for the update parameter:
new(HOST)=joe.weedns.com
Example: To attempt to create a new hostname called joe.weedns.com as well as immediately set it's IP address to 10.10.1.2 (assuming the
creation was successful), the following would be a suitable value for the update parameter:
new(HOST)=joe.weedns.com,a(joe.weedns.com)=10.10.1.2
Example: To attempt to delete an existing hostname called joe.weedns.com, the following would be a suitable value
for the update parameter:
del(HOST)=joe.weedns.com
This is the most common update made in the weeDNS system. The value specified for where should either be a valid hostname, or a wildcard pattern that matches one or more valid hostnames owned by the user making the request. The value field is optional for this and only this type of update; if value is specified, it is used as the IP address for the update; if it is not specified, the current IP address of the client is used. This IP address will either be the IP address of the host that connected to the weeDNS server, or, if an X-Forwarded-For HTTP header is detected, the last IP address found in that header is used instead. The X-Forwarded-For header is set by most, probably all, commonly used HTTP proxies. If you wish to explicitly bypass proxy detection and explicitly set your IP address to the address that the connection is made from, specify "PROXY" as the value (this is case-sensitive) and it will be replaced with the IP address that the request comes to weeDNS from, as opposed to the content of the X-Forwarded-For header. In order for any other records to be written to the DNS tables for a given hostname, a valid A record must be specified.
Example: To set the IP address of all hosts the client user owns to the client user's current IP address, use the following syntax:
a(*)
Example: To set the IP address of all hosts the client user owns to the client user's current external/proxy IP address, use the following syntax:
a(*)=PROXY
Example: To set the IP address of the host called joe.weedns.com to 1.2.3.4, use the following syntax:
a(joe.weedns.com)=1.2.3.4
Example: To set the IP address of all hosts underneath the whyI.org domain that the client user owns to the current IP address for the
client user, use the following syntax:
a(*.whyi.org)
Example: To set the IP address of all hosts that the client user owns to the current IP address of the client, then set the IP address for
the host joe.weedns.com to 1.2.3.4 in one update request, so that after the request, all of the client user's host IP addresses are set
to to the user's current IP address are set to the client's current IP, except for joe.weedns.com, which would be set to 1.2.3.4,
use the following syntax:
a(*),a(joe.weedns.com)=1.2.3.4
Example: To remove the the IP address associated with joe.weedns.com, use the following syntax:
a(joe.weedns.com)=
Each of these updates takes the same format for the where field as the a update. For the value field, a fully-qualified hostname must be specified. A dot character (".") will automatically be added to the hostname specified, forcing it to be fully-qualified, so do not specify the trailing dot yourself.
Example: To set the primary mail exchanger for joe.weedns.com to joe.weedns.com, then set the secondary mail exchanger
for joe.weedns.com to joe2.weedns.com, causing email addressed to email addresses @joe.weedns.com to be sent to
joe.weedns.com for processing, or joe2.weedns.com if joe.weedns.com is unavailable, the following syntax would
be used:
mx1(joe.weedns.com)=joe.weedns.com,mx2(joe.weedns.com)=joe2.weedns.com
Example: To delete the secondary nameserver record for joe.weedns.com, the following syntax would be used:
ns2(joe.weedns.com)=
Unlike the other database information that you can update on your hosts, the url field does not affect the DNS tables at all. Instead, it is used as a URL to redirect to when somebody requests a path beginning with the name of your host on the root domain that your host belongs to. (This is assuming that the root host record for the domain points to the weeDNS server's redirection table, which is normally the case, and is the case with all the public domains available on whyI.org.)
Example:
TXT records should be a short (preferably one or two words) categorization of your host, but can really be anything you want that will validate, up to 128 characters in length. Alphanumberics, as well as spaces (" "), colons (":"), dashes ("-"), dots ("."), underscores ("_"), slashes ("/"), and the at symbol ("@") may be used in a TXT record.
Example: To set the TXT record for joe.weedns.com to "Personal Webpage", the following syntax would be used:
txt(joe.weedns.com)=Personal Webpage
Keep in mind that while they should always be used, it is especially important to use URL escaping rules (replace spaces with %20, etc) when submitting update requests as the query portion of the update engine URL.
The is_enable, is_search, and has_wildcard fields in a host record are flags, and may be set to 1 for true, or 0 for false.
Note that in the context of whyI.org dynamic dns, this flag has no effect. This is because whyI.org is doing free, mass-hosting of DNS under it's subdomains, and if information such as contact email addresses for hosts were not available via the webpage (as was the case with the original yI.org engine), people would often assume that whyI.org is the ISP or contact for the webpage and email abuse, software piracy complaints, requests for files or information, or other stuff unrelated to whyI.org itself to the whyI.org administrators. In the past, this significantly increased hassle and administration overhead; I even got several letters from lawyers, sent by registered mail, ordering me to cease and desist serving files that I was not serving, due to their lack of being able to find a better contact point for their requests. However, this option is built into the database structure and protocol so that organizations running the weeDNS server that wish to be able to give clients the option of making their contact email addresses, etc, private, may do so.
The wildcard record is a copy of the A record with the character sequence *. prepended to the name of the host. This results in DNS servers giving your host's IP information for any sub-hosts requested underneath your hostname. So, if you enabled has_wildcard on joe.weedns.com, then people requesting the host www.joe.weedns.com, i.am.not.joe.weedns.com, or anything else followed by .joe.weedns.com, would be directed to the IP address for joe.weedns.com.
has_wildcard has no effect if a ns1 or ns2 has been specified for the host.
Example: To stop information about the host joe.weedns.com from appearing in DNS tables without actually
deleting the record, the following syntax would be used:
is_enable(joe.weedns.com)=0
Example: To enable wildcards on joe.weedns.com, then remove the nameserver records for that host so that
the wildcard option has the desired effect, the following syntax would be used:
has_wildcard(joe.weedns.com)=1,ns1(joe.weedns.com)=,ns2(joe.weedns.com)=
Example: To hide all of your hosts from the web-based search engine (assuming that the weeDNS server you are
using supports this; whyI.org does not), the following syntax would be used:
is_search(*)=0
The response sent back from the server describes how the request was handled. The HTTP Result Code indicates whether or not an action was taken, and if not, why not; the headers may contain some other useful auxillary information, and the body is, when a request has been processed, information about that request, and when a request has not been processed, usually informtion about why not, or how to make the reuest go through.
The HTTP Result Code sent back from the server will indicate exactly what was done with your request; in all instances where the result code is 400 or higher, nothing was done with your request due to client or server error. The actual numeric response codes sent back from the server are as follows (listed along with their HTTP Standard english translations):
The HTTP Headers contain some extra information not included in the response. The only fields you actually need to check are Content-Type and Location, and the latter only in the case of a 302 HTTP Result Code. However, Server and Content-Language also provide some other useful information.
When the Content-Type HTTP Header is set to "text/plain", the weeDNS document body that follows is a Result Document. When it is set to "application/x-www-form-urlencoded", the document body is a Prompt. Both have different semantics for parsing, so the Content-Type header should always be paid attention to.
The Content-Language HTTP Header will always have it's primary value set to "weedns". Future versions may indicate the minimum weedns update-protocol version required to properly parse the output, so additional arguments should be recognized in this header.
Some values you may see for a Content-Language header:
WeedNS clients should accept all cookies sent by weeDNS servers. At the present time, the only cookie sent by the weeDNS update server is the session key granted after a successful authentication with userid and password, but clients should be prepared to process any cookies sent by the server. See RFC 2109 for more information about HTTP Cookies.
Once the HTTP Result Code and Headers have been parsed, in most instances the weeDNS client will need to parse the content. The way that this is done is dependant on the Content-Type header.
WeedNS document bodies that come with a Content-Type header set to text/plain contain one result per line. Each line will begin with either with the character "1" (one) to indicate success, or "0" (zero) to indicate failure. Within square brackets ("[]") there will be a reference to what succeeded or failed, and after the sqaure brackets there may be additional information about the request.
The result within the square brackets will be one of the following:
When there are three numbers (characers in the range of "0" (zero) to "9" (nine) within the square brackets, what follows is an explination as to why the given response code was issued.
This response is not normally sent by the weeDNS server, but is provided so that webservers acting as a frontend to WeedNS servers can return an appropriate weedns compatible result when the update server is dysfunctional or unavailable, when an authentication layer before the weeDNS server decides to deny access, or under any other number of imaginable circumstances. When they receive such a status line, WeedNS clients should treat the request as if the HTTP Result Code specified within the square brackets was the result code sent by the server and ignore the result code specified in the HTTP Headers.
These results inform the client of limitations on how often requests may be sent ot the weeDNS update server.
The value for wait is the amount of time that the client should wait until submitting the next request, specified in seconds, with the character "s" appended to the value to indicate the unit of measurement. When a weeDNS client receives a wait response line, it must wait at least the time specified before submitting another request. WeedNS servers will ignore all requests until the specified time has elapsed, and may penalize the client in question by firewalling or other methods if the client requests too frequently.
The value for limit gives to values and specifies how many requests may be sent within a duration. The values are sperated by the division character ("/"). The first value is how many requests may be sent in the duration, and has the character "r" appended to indicate the unit of measurement. The second value is now many seconds the duration is.
When failure is indicated, the client has already broken server rules. Properly written WeedNS clients should never break server rules. When failure is indicated, the request update was not processed and will have to be re-submitted.
If the client receives a successful [wait] response (prefixed with the character "1"), the server is indicating that the request sent was accepted and that while the client has not broken the server's frequency restrictions yet, however, if another request is sent before the duration specified, the client will be in violation of the server's rules.
If the WeedNS server sends a [go away] response, client software should terminate and indicate that it is behaving in a dysfunctional manner to the user. Servers only send this response when clients are grossly in violation of limitations and should be shut down to prevent infinite waste of bandwidth.
When a valid weeDNS update string is specified by the server as the reference in a result, the result normally matches up with a update requested by the client in the request. Success/failure is indicated by the first character on the line. On success, the first "word" of the comment section will normally be the number of records in the database that this update request affected, and the rest of the comment section will normally be the actual value that was assigned to the record(s) requested. On failure, the comment section will be a human-readable description of the error encountered.
Example: If I owned two hosts within the b0b.org domain,
"joe.b0b.org" and "joey.b0b.org", and I issued the
command:
a(*.b0b.org)=1.2.3.4,mx(joey.b0b.org)=joe.b0b.org
.. then a successful update request would probably return these lines:
1[a(*.b0b.org)=1.2.3.4] 2 1.2.3.4
1[mx(joey.b0b.org)=joe.b0b.org] 1 joe.b0b.org
[info] result lines are sent by the server to provide extended human-readable information messages to people who are using web browsers or other non-weedns-compatible HTTP software to send updates to WeedNS servers.
If your client is receiving [info] result lines, it has not been properly programmed. All correctly programmed weeDNS clients should send a correct Accept-Language header, which will supress the redundant [info] messages.
When a document with a Content-Language of weedns and a Content-Type of application/x-www-form-urlencoded is sent by the update server, the weedns server is prompting the client, indicating that not enough information has been supplied to fufill a request. The client should take the prompt and answer with the information that was requested in it.
The content of the response is a template of parameters that can be specified at this point. The parameters are specified as a urlencoded query string; the names of the parameters being the same as the names that should be sent back to the server when the conditions of the prompt are satisfied, and the values being a description of the data requested.
If a value for a parameter is not enclosed in brackets ("()"), that exact value should be sent back to the server for that parameter in the client's answer to the prompt. If the value for a paremeter is enclosed in brackets, then the following rules apply:
When writing a client that talks to weeDNS servers, especially if you're intending on releasing it to the public, it makes everybody's lives easier if you make sure you pay attention to certain details.
Make sure that in any context, if your client receives a response containing a [wait] line from the server, it does not attempt another request until the specified duration has elapsed. Requests made before this time will not be processed by the server and will continue to increase the amount of time the client must wait before making a request that is heard, as well as risking disciplinary action, such as the client's IP being blocked entirely from the server.
When designing your user interface, make it easy for the end user to bundle multiple sub-requests up into one large one. You can send dozens of commands in one update request and it only counts as one request to the server.
Store the user's session key across invocations; use it until the user specifically requests a logout or the server stops accepting it, and then, and only then, log in again with the user/password credentials. This not only saves bandwidth and cuts down on requests to the server, but it also makes the user's password more secure, since it isn't being transferred across the internet as often.
... Only one session cookie is valid for a user at any given time. If you, when possible, share the web browser's cookie database with your own application, the user won't invalidate your application's session whenever they log in via the web browser, and vice versa.
When a service provider makes a secure HTTP (https://) URL available for it's DNS update server, it is always best to use it by default, so that passwords and other sensitive information is never transmitted in plaintext over the internet.
If the client does break the [limit] and [wait] constraints set forth by the server, it will only increase the amount of time the client must wait, so it is pointless for the user to do this anyways and will only aggrivate server admins. You should either abort the request immediately, or wait the amount of time requested.
The user should be able to, in some way, see the raw requests sent to, and responses receieved from, the update server. This is trivial to implement, as a logfile, a seperate dialog window, or whatever suits your application best, and it helps people understand what is going on, which cuts down on technical support overhead.
The user should be able to specify a manual update request string to send to the server; on the command line, in a console window, or through whatever means suits your application best. While the purpose of most client software will be to provide a user-friendly "shell" around the weeDNS protocol, sometimes users may still want to enter raw update requests, and putting this functionality in your software saves them from having to log in via the webpage and invalidate their session key.
The reference implementation for a client to the weeDNS protocol is available from http://www.weedns.com/clients/, and is dubbed the "Skeleton Client" (weedns_sc). It is written in perl and provides some rudimentary example code to demonstrate the protocol. As of 2002/01/24, the latest client code (weedns_sc-1.15) is still missing some functionality and is mostly undocumented, but it does operate flawlessly as a WeedNS client.
The reference implementation for a server for the WeedNS protocol is whyI.org. It's services are currently available to the public, and you can use it to obtain a free dynamic hostname under one of several domains.
The code for the reference implementation, weedns server 0.1, is not yet near completion, is completely undocumented, there are some known bugs, and some of it's underlying code libraries are also under development. The code will become publically available when it reaches it's first point of stability.
This is the revision history for update_protocol.html:
Id: update_protocol.html,v 1.13 2002/06/15 20:05:23 faraway Exp
Id: update_protocol.html,v 1.13 2002/06/15 20:05:23 faraway Exp -
<www@weeDNS.com>