Tzolkin Corporation


TZO Dynamic DNS Updates via HTTP (WebClient v2)

API version 2.02

Jun 30, 2006

Table of Contents

Revisions and Updates 4

Policy Overview 5

Purpose 5

TZO Specification Changes and TZO Notification policy 5

Obsolete Documentation Notice 5

Technical/System Overview 5

Process Flow for Dynamic DNS (TEXT) 6

Process Flow for Dynamic DNS (Flowchart) 9

API Usage 10

Update Syntax 10

NEW - Additional variables for TZO Webclient-2 (TZO API version 2) 10

HTTP GET Request (all on one line) 11

HTTPS GET Requests 11

HTTPS POST Request 11

Variables Used BY Update Request URL 11

HTTP USER AGENT - Requirement 12

HTTP USER_AGENT - Required fields 12

Example HTTP User-Agent 13

Avoid Using HTTP Library's 'Default' HTTP User-Agent 13

Please Register your HTTP User-Agent String With TZO 13

HTTP USER_AGENT - Unacceptable User-Agent strings 13

Response Codes - Interpretation and Strategy 15

Response Code MIME Type Note 15

I Response Code - Successful Update 15

II Response Codes - Delay Update Response (retry pending update) 15

III Response Codes - Permanently Disable Client (user intervention) 15

TZO Response Codes (with Extended Response text) - Complete List 16

Special Notes on Abuse Updates 18

304 No Update 18

403 account blocked Too Many Updates with the Same IP Address 18

414 account blocked Too Many Updates with the Same IP Address 19

Special note about basing client development on existing/free dynamic DNS clients 19

IP Address Checking for Reliable DNS Updates 20

Connection/IP Address Monitoring Strategy 20

Feature/Design Issue - IP Checking Explained 20

Appendix A - Making DNS Easier for your Users 21

Documentation for End-Users 21

Suggested Example Text for TZO: 21

Tighter TZO API Integration 21

TZO Revenue Sharing (Affiliate Program) 21

Appendix B - Dynamic DNS Client Development Helpful Hints: 22

DO NOT ask the user to input a server address 22

DO NOT hardcode the TZO Server IP address(es) 22

DO NOT 'ping' TZO Servers 22

DO NOT use DNS Queries To Determine if an domain 'needs' to be Updated 22

DO select and a meaningful User-Agent for your update Client 22

DO register your Client's User-Agent with TZO 22

DO Customize User-Agent strings if using existing DNS Client code 23

DO NOT use User-Agent strings which are too generic or known to be abusive 23

DO Process TZO Response Codes Completely 23

DO Provide User Feedback with TZO Response Codes 23

DO Record a Log of Dynamic DNS Update Responses 23

DO Raise an Error when a Response Code indicates an account is suspended 24

DO Consider (optional) adding a feature for 'Managed Restarts' of Expired Accounts 24

DO NOT use ''forced' updates' 24

DO Error check domain/hostname, username, and password fields. 24

DO Perform basic Fully Qualified Domain Name checking 25

DO NOT attempt to 'automate' TZO.COM DDNS account creation 25

DO consider how the Client will monitor IP addresses 25

DO consider optional/extra support for port 21333 Updates 25

DO NOT use port 443 (HTTPS) for GET-style requests 25

Additional Support and Information 25

Appendix C - Example HTML configuration implementation 26

Screenshot - Example DDNS Configuration in HTML 27

Example DNS Configuration - HTML Source Code 28

Revisions and Updates

June 30, 2006

Jun 23, 2006

May 24, 2006 - First Draft

NOTES: Relative to 'WebClient v1' protocol, please note the following major changes.

Policy Overview

These policies ensure fair distribution of TZO resources, and ensure reliable accounts for your client's users.

Purpose

This update specification describes an HTTP gateway to the TZO DNS servers. TZO exports a subset of the server system interface which can be accessed with easy-to-use HTTP requests.

Every update request sent to TZO results in a server 'response code' reply to your client.

Your software client must react appropriately to these TZO response codes to ensure proper operation of the user's account. DNS clients which ignore TZO Response Codes may cause harm to the TZO Update servers. To protect the TZO service availability for all customers, harmful clients may be blocked (banned) until fixed.

OEMs and Developers may contact TZO regarding DDNS testing and certification services, or you may use these specifications to plan your testing.

These specifications are bare requirements for DDNS clients. It is considered helpful to your users (and for TZO Support) to provide additional features such as logging of dynamic DNS Update Requests and TZO Response Codes. This feature allows TZO to support your third party DNS client with parity.

OEMs interested in business development should contact busdev@tzo.com. Developer support and questions about this document should be directed to devsupport@tzo.com.

TZO Specification Changes and TZO Notification policy

TZO at its discretion, provide extensions or replacement APIs, to be announced at http://www.tzo.com/developer/. Client authors who register with TZO Developer Support (devsupport@tzo.com) will receive email notification. Whenever possible, TZO will as a goal maintain backwards compatibility, and any Client that followed TZO specifications would be unaffected by such upgrades.

Obsolete Documentation Notice

This document identifies major changes to the TZO Update Request method, and the TZO Response Codes. The former (deprecated) HTTP Update specification shall now be known as 'Webclient-v1'.

This document shall be known as 'WebClient-v2'. New Client development efforts should use Webclient-v2, which is now the preferred API for managing TZO accounts.

Existing Client software may use the 'WebClient-v1' 1.0 API, or consider upgrading. The Webclient-v1 API and server is (still) maintenance supported by TZO.

Technical/System Overview

The TZO-HTTP system accepts DNS updates over GET or POST, HTTP or HTTPS. Update Syntax describes the URL string method, and after an Update connection the TZO system provides Return Codes.

Process Flow for Dynamic DNS (TEXT)

With the WebClient-2 API, the model for updates is more simple than in the previous WebClient-1 API; there are fewer things to check, and Response Codes became easier to parse. Client authors should strictly adhere to TZO specifications to minimize chances of Client update defects or Support issues.

    The following is a complete walk through (or text flowchart) of the steps taken by a proper dynamic DNS client. Example (reference client) code in C is available upon request.

  1. Begin
    If DNS account information is not provided by the user (if the fields are blank) the DDNS client must be DISABLED. The end user must provide Dynamic DNS account information, and enable TZO service. A Client should never attempt to Update TZO if it lacks the required fields.

  2. User Input Evaluation
    Before requesting an Update, a DNS client must 'sanity check' user input for validity. If the user inputs a domain name that is NOT in FQDN format, invalid email address, or other input error, the Client should display an error to the user -- and disable all Updates until the user corrects this problem.

  3. Client polls for 'current' IP address
    Exactly how the dynamic DNS client monitors/checks its IP is a vendor/OEM design question. Possibilities include:
    OPTION A) Client hosts a web based IP checker' on their website. The web IP checker server will be maintained by the Client author. Code for a web-based IP checker is considered trivial - you may ask TZO for a reference implementation which you may host yourself.

    OPTION B) Client uses WAN port (hardware) address to detect the IP. This approach is limited, and suitable only for Clients designed to control the actual Internet connection. This approach is unsuited for devices operating behind a NAT connection (if a LAN address is detected, the Client MUST disable itself and not update DDNS).

    OPTION C) Clients which prominently feature TZO may request to use TZO web-based IP checking services. The TZO IP checking server may not be used without expressed written consent from TZO.

    IMPORTANT: Clients must not update DNS accounts to IP addresses that are covered in RCF1918 (must not point domain at a 'private LAN address'). This problem occurs if the client is not designed with an ability to use web-based IP address detection (does not employ either Option A or C).

    IMPORTANT:     If your Client encounters any problem detecting the IP address, the client must log or display an error to the User.

  4. Import cached (if any) IP addresses.
    Read in (import) any cached IP address from prior successful DNS Updates, and store that historical IP record into a variable for future testing.

    NOTE: There will be no 'cached IP' on the first iteration (as no Update has yet occurred) - just continue to Step 5.

  5. TEST: Compare 'Previously-updated IP' to 'Current-IP'
    For a dynamic DNS client to be effective and accurate, the client needs to 'monitor' the Internet address for changes, to avoid unnecessary (abuse) Updates. This feature is the cornerstone of a reliable DNS client.

    In Step #3, your Client recovered the 'current IP' address.
    In Step #4, your Client recovered the value of the 'previous IP' address.
    Now in this step we compare the two IP values.

    If both IP values compare TRUE (match), then NO Update is necessary: Have the client 'sleep 600', then jump back to Step 3 to begin anew.

    If both IP values compare FALSE (or no cached IP exists due to first iteration), then an Update is necessary, so continue to Step 6 now.

  6. Create Update URL, and submit the GET Request
    As the 'Previous Update' and 'Current' IP differ, an Update Request is necessary. Formulate the update request URL containing the domain account info, and direct the HTTP request to the TZO update server.

  7. Capture Update Server Response
    Capture and record the TZO Update Server's Response Code.

  8. Process for Delay Code 414 (if found, 60 second wait)
    If the Update Server Response Code is '414', the DNS client must:
    a) Wait exactly 1 minute [sleep(60)]
    b) after sleep, return to Step 6

    NOTE: This is a temporary 'delay code'. The server issues this when it has seen a previous connection (good or bad) from your IP address, sometime within the last 60 seconds. This output serves to ensure fair allocation of server resources.

  9. Process for Delay Code 500 (if found, 600 second wait)
    If the Update Server Response Code is '500' (server maintenance), the DNS client must:
    a) Wait exactly 10 minutes [sleep(600)]
    b) after sleep, return to Step 6
    NOTE: This is a temporary failure code which may be retried after 600 seconds.
    NOTE: This is never a final Response Code - when you wait the 600 seconds, you should get the 'true' Response Code. This stage serves to inform the Client of server maintenance, so the Client specifically knows to retry the Update Request on an extended basis.

  10. Process for Response Code 480 - Account Expiration (Client Shutdown OR Delay)
    If the Response Code is 480, the user's account is expired. The 'standard' Client behavior is indicate Account Is Expired and DISABLE the Client.

    A 'better' (but optional) Client behavior is NOTE to the User that Account Is Expired, but continue to retry the Update every 24 hours. The reason for retrying is to allow TZO to 'wake' the client when the customer renews their account, and the reason to use a 24 hour delay is to avoid unnecessary load on the server. This process for 'remote restart' of expired accounts is explained in Appendix B.

  11. Process for Response Codes which require a Client Shutdown
    Response Codes requiring Client shutdown (and user notification) are: 401, 403, 405, 407, 415, and optionally (required if Client code does not support 'remote restart of expired accounts) special code 480.

    Please see Response Codes - Complete List for information on each Response Code.

  12. Process for Response Code 200 (Successful Response)
    A successful update Response Code is '200', meaning DNS has been updated for that account. When code 200 is received, the Client must:
    a) 'cache' or save to memory the value of the updated IP (note this was looked for in Step 4)
    b) wait 10 minutes (sleep 600 seconds) then goto Step 3.

Process Flow for Dynamic DNS (Flowchart)


Please contact devsupport@tzo.com with any questions.

API Usage

Update Syntax

All examples in this documentation use HTTP/1.0 unless specified otherwise. While the server also accepts HTTP 1.1, at this time there is no benefit to a HTTP 1.1 and so is discouraged. Please see the relevant Internet RFCs for any questions about basic HTTP details.

The most commonly used DNS update is an HTTP 1.0 GET containing all the account information. HTTP POST is also supported, and POST requests may also use HTTPS. Using GET is suggested as it is easier to debug/support.

TZO webservers are available using Ports 80, 443, and 21333. In special circumstances to bypass web proxies, TZO servers may be contacted on the 'alternate port' 21333. This special port should only be selected in special cases (not default) because many firewalls may restrict all non-port-80 traffic. In your user interface/config, you might call this option 'use alternate-port 21333 for Updates'.

Port 443 is for HTTPS. This implies a POST request.

NOTE: The following examples should not be copied verbatim without fully reviewing the WebClient-2 documentation. Examples are deliberately brief and for illustration only.

NEW - Additional variables for TZO Webclient-2 (TZO API version 2)

Under Webclient-2, there are 2 sets of server Response Codes. Both sets have the same meaning, and each have a different level of usefulness depending if the code is read by software or displayed to the end user.




HTTP GET Request (all on one line)

Note: The URL is too long to display on one line, so the example below has been formatted to put variable key/value on multiple lines.

This formatting has been done for documentation and display purposes only - actual requests must be sent 'all on one line', and you would substitute actual CRLF for each virtual {CRLF} below, and require standard HTTP headers. All requests are standard HTTP GET, as defined in RFC1945.


This example is abbreviated for testing purposes only (other headers might be used in your Client).

GET /webclient/tzoperl.html?
tzoname=DOMAIN_NAME&
email=EMAIL_ADDRESS&
tzokey=TZO_KEY&
ipaddress=WAN_IP&
system=tzodns&
info=1 HTTP/1.0{CRLF}
Host: rh.tzo.com{CRLF}
User-Agent: YOUR_DNS_SOFTWARE/YOUR_SOFTWARE_VERSION{CRLF}
{CRLF} 
{CRLF}

Please note the space character between the end of the GET URL, and 'HTTP 1.0' (this is all one line until CRLF).

HTTPS GET Requests

GET requests over HTTPS are NOT supported. At the time of this writing, TZO does not block these requests (but may do so in the future).

HTTPS POST Request

At this time, HTTPS POST requests are not supported for Support reasons.

HTTPS POST may be approved for special DDNS clients, however such clients would need to have exceptional error checking and logging facilities. TZO can not support or debug a closed application which does POST, and lacks logging features.

Variables Used BY Update Request URL

HTTP USER AGENT - Requirement

USER_AGENT is an optional HTTP header variable used to identify HTTP clients. See RFCs for more information. TZO Update servers require use of the USER_AGENT header.

Reasons for requiring HTTP USER AGENT are:

HTTP USER_AGENT - Required fields

We ask that Client's User-Agent string should convey these details:

Example HTTP User-Agent

Assuming for this example that your Client were based on TZO's Reference Client, and were a a hardware Client, you might use the following User Agent string: 'ACME Routers (WT-54v1, firmware 1.01, based on TZO reference code)'.

There is no fixed standard dictating the format of User Agents, and the fields required by TZO may be presented in any order.

Avoid Using HTTP Library's 'Default' HTTP User-Agent

HTTP libraries typically default to some HTTP USER_AGENT set by the library's designer. Your code must override this USER_AGENT, so it accurately represents your code. DDNS clients that ignore this request and submit 'default' or 'generic' HTTP user agents may be blocked by TZO.

Please Register your HTTP User-Agent String With TZO

Submitting (registering) your dynamic DNS Client's User-Agent string with TZO will make it possible for TZO Support to provide an increased level of Support for your Client. Please send Client information, including the HTTP USER_AGENT, to the devsupport@tzo.com address.

HTTP USER_AGENT - Unacceptable User-Agent strings

The following HTTP USER_AGENT strings are disallowed for client development, and may be blocked. These User-Agent strings do not fulfill the requirement of identifying the software Client. In many cases, clients using these Agent strings have larger problems than just the Agent string (some of these Clients will continue to send DDNS updates long after the account has expired).

Authors of Clients using the above Agent strings, should contact devsupport@tzo.com for assistance.

Response Codes - Interpretation and Strategy

Response Code MIME Type Note

For legacy reasons (support of historical DNS update clients), the server responds to all update requests using MIME type text/html. TZO WebClient-2 Responses do not contain HTML tags.

If parsing TZO Response codes using shell scripting or different rules and capabilities for parsing strings with CRLF (control characters).in them. This is not a TZO-specific issue.

I Response Code - Successful Update

Response Codes represent success or failure of the account Update. Client software must not ignore these response codes. There are two types of Response Codes from TZO:

NOTE: If unsure which method to use, please default your Client to use EXTENDED Request/Response.

{IP} is equal to the IP address for that Update. All Responses use {CRLF} termination.

II Response Codes - Delay Update Response (retry pending update)

There are two designated 'temporary wait' Response Codes: 414, and 500, and one special code (480) which MAY be interpreted as a temporary (delay) code OR as a permanent (stop) code. A 'Delay Code' is defined as a response which the Client must 'sleep' (wait) for NNN seconds, where NNN is defined below for each Code.

414 = TZO has received updates from this hostname or IP address within the last 60 seconds. This is possible client abuse, or may have occurred naturally if the user recently reset their account information in the Client. Wait 60 seconds before retrying the pending Update Request.

500 = Server maintenance at TZO. Wait 600 seconds before retrying the pending Update Request.

480 = Account Expired is normally a PERMANENT (client must self-disable) failure code discussed in section 3 . As an alternative to that permanent response, you may at your discretion (as a 'feature' in your client) interpret this code as a special-case Delay Code. This would allow easy repair of Support cases where the User allowed their TZO account to expire, but has since renewed. Wait 86400 seconds (exactly 24 hours) before re-trying the pending Update Request.

III Response Codes - Permanently Disable Client (user intervention)

There are 'permanent failure' Response Codes: 401, 405, 480, and XXX. This indicates the Client shall shut down completely - there is a problem with the account or the details provided by the user.

TZO Response Codes (with Extended Response text) - Complete List

{CRLF} = standard Carriage Return/Line-Feed
{IP} = The IP address. In this table, IP is the address of the client (or address client supplied)
All Response Codes and Extended Response Text outputs to a single line terminated by CR/LF.

Response Code

Extended Response Text

Description

Client Reaction

 
200
 
update successful {IP}{CRLF}

Successful update of DNS record.

Sleep 600 seconds, then re-test WAN IP.

 
304
 
No update {$IP}{CRLF}

DNS update request is no different than hostname's current DNS record.

No reaction. Sleep 600 seconds before re-testing the WAN IP.

NOTE: Repeated instances of '304 No update'is indication of a serious Client bug (DNS clients must not use 'Update timers'. See Appendix B.

 
401
 
bad authentication{CRLF}

TZO authentication failure (bad Key or email or domain name). This is a Permanent Fail requiring User action.

Disable DDNS on account. User must correct this issue before they can manually restart the client

 
403
 
account blocked Too Many Updates with the Same IP Address

For Technical Support reasons this DDNS account has been disabled. The user must contact TZO Support regarding their account.

Disable DDNS on account. User must correct this issue before they can manually restart the client

 
414
 
ip blocked Same IP Address Updating < 1 min {IP}

This IP address is Temporarily blocked from updates.

This Response indicates TZO received more than 1 Update Request within 60 seconds, which is too rapid. Updates for this account are temporarily blocked.

Temporary disruption in updates for this account or IP.
WAIT (sleep) for 60 seconds before retrying the Update request again.

 
405
 
Bad user agent

The Client is using a prohibited User-Agent. This is a Permanent Fail requiring User action. Software exhibiting this error message should not be distributed.

Disable DDNS on account. The client's User contact the DDNS software vendor for an updated client.

 
407
 
host blocked contact  support

Host blocked (account suspended by TZO)

Disable DDNS on account. Instruct the User to contact TZO Support for details.

 
415
 
Blocked from update

Update not accepted by TZO because the hostname/A-Record is 'locked' by the customer for Support reasons.

Disable DDNS on account. Instruct the User to contact TZO for details.

 
480
 
account expired

This hostname exists in TZO DNS database, but is expired.

NOTE: Client authors may choose between handling this in a permanent OR temporary manner. See Client Notes/Tips.

Two possible Client Reactions exist (you must decide upon which approach):

a) Shutdown Reaction: Disable DDNS on account. Instruct the user to contact TZO for details. Or:

b) OPTIONAL (friendly) Reaction: Enter 'long-delay forced update method', a sort of 'Remotely Restart' process for expired accounts. Details and Logic for this feature is described in Appendix B.



NOTE: Whenever a Client reacts to to TZO Response Codes, it should log some output either to the screen, file or disk. The Response Codes (and your Client's reaction to it) should be 'transparent' to the user, or else the client (or the user) will make false assumptions about performance, and possibly trigger Abuse classification on the server.

Special Notes on Abuse Updates

Abuse updates are defined as updates which are redundant or wasteful. The TZO Update Server will warn clients when it sees a potential abuse situation. Such Response Codes are important for a Client to understand. Clients that ignore Response Codes will inevitably become blocked for server abuse.

304 No Update

A 304 Response Code ('No update') Abuse is not abuse if it happens only one time.

For example, when the user installs a new client, firmware update, factory reset etc. they could trigger this response through no fault of the Client. This is similar to what other DDNS providers call 'nochg'.

If this response is provoked repeatedly, the server may escalate this to (more serious) Response 414, or (most serious) Response 403.

403 account blocked Too Many Updates with the Same IP Address

This Response indicates abuse: the WAN IP address used by the DNS Client has already sent an Update to TZO within the last 60 seconds.

This Response should not happen, as clients should never update more than once within 60 seconds (for any reason). This Response may occur naturally however if the user has for example re-entered their account information (a condition which causes many clients to re-update, and TZO is aware of).

414 account blocked Too Many Updates with the Same IP Address

A 414 Response Code ('account blocked') is issued to Clients using accounts that are blocked by the TZO Service. This type of block is automatic, when the TZO server receives a large number of Abuse updates. This will never happen with Clients which follow TZO specifications. (This may still happen however if the user does something wrong, such as running multiple dynamic DNS update Clients).

Clients which repeatedly transmit 'Updates' to TZO with an unchanged IP address are considered abusive, and blocked. The Client software must monitor the IP address to avoid this pitfall (suggestions for proper monitoring of the WAN IP are provided in the section 'IP Address Checking', and in Appendix B).

Special note about basing client development on existing/free dynamic DNS clients

There are existing DNS Client libraries on the Internet, which claim TZO compatibility. It may be tempting to borrow code or features from such clients (which may be permissible under that Client's license), however if you do so you are still responsible for ensuring the code follows the TZO requirements (including parsing of Response Codes).

Regrettably, in some cases there are Open Source/GPL client codebases which are abandoned by the author, and which are unsuitable for client use due to critical bugs. An example would be a Client which can update TZO accounts, but which also ignores TZO Response Codes (and so can not disable itself when the TZO service expires, which is considered Abuse).

TZO will provide Example DNS 'Reference Client' code (in C) is provided by TZO upon request to devsupport@tzo.com. While portions are copyright TZO, the Reference Client is provided under dual GPL/BSD licensing. Other licensing may be arranged.

TZO may provide sponsorship (in the form of services) or extra support/testing for Open Source and Free Software (BSD or GPL licensed) dynamic DNS clients which feature TZO.



IP Address Checking for Reliable DNS Updates

Connection/IP Address Monitoring Strategy

IP address checking/monitoring is critical to providing a reliable DNS client. A DNS client must monitor the Internet or device IP address in some manner, so that it always 'knows' what its IP address is.

There are several approaches to designing 'IP checker' feature - which method you choose is a feature design issue typically left for the software's Program Manager.

  1. Hardware Address Updates - On embedded or special purpose applications such as routers, firewalls or gateway/proxy devices, you may poll the devices network port for the hardware's IP address.

  2. Use your own web-based IP checker - As a commercial application provider, you can self-host your own web-based 'check IP' application. Your 'check IP' application is considered part of your application's feature set and is the vendor's responsibility.

  3. Use TZO-hosted web-based IP checking - TZO can provide web-based IP checking services for third-party software, freeing you to focus on your core client feature set. This service is available through prior agreement with TZO -- please contact busdev@tzo.com for more information.

Which method for detecting the IP address your client uses is a choice/responsibility of you the DNS Client author (or the entity contracting for your Client development). For example, Option A is typically NOT appropriate for hardware clients intended to operate behind a router (such as an IP camera or DVR firmware).

Clients that are unable to monitor their IP addresses will (at best) not be reliable, and (at worst) may be considered abusive Clients.

Feature/Design Issue - IP Checking Explained



Each technology (explained above) used for monitoring IP addresses, has unique benefits and costs. These must be considered carefully in the updater software's design. Please consult TZO (devsupport@tzo.com) if you are unsure of this issue.

The primary function of a dynamic DNS client is not simply to update a DNS record somewhere. Rather, the primary function of a dynamic DNS client is to monitor the connection IP address. For a Client to monitor the IP address, the client must support these features:

Appendix A - Making DNS Easier for your Users

Documentation for End-Users

If you provide an interface to TZO service, you should provide a link to the TZO website so users know where to visit for an account. Anyone user with a valid email address, can obtain a free 30 day trial account from TZO.

Suggested Example Text for TZO:

Tighter TZO API Integration

By prior arrangement with TZO, custom DNS and Domain Registration features may become available to your DNS client. Please consult the TZO Partners website at http://www.tzo.com/MainPagePartners/

TZO Revenue Sharing (Affiliate Program)

Revenue Sharing (referrals) programs are available, which may use TZO.COM supplied domain names, custom (user supplied) domains, custom client modification and branding. Please consult the TZO Partners website at http://www.tzo.com/MainPagePartners/.


Appendix B - Dynamic DNS Client Development Helpful Hints:

TZO has developed dynamic DNS Clients for PCs and embedded platforms. TZO testing services have also been used to validate third party DNS Clients. This section is dedicated to providing a a list of 'Do's and Don'ts', which we suggest giving development and test consideration.

This list encompasses TZO Webclient-2 API Specifications, general TZO server policies, and suggested User Interface elements that help your users (or helps TZO Support). This list can not be considered a complete testplan, however it highlights some of the more serious Client bugs (or customer feature requests).

DO NOT ask the user to input a server address

TZO asks that you automatically configure server addresses and Update URL variables in your software. Please do not ask the user to fill in a 'generic' field for Server Address, as this will confuse the user.

DO NOT hardcode the TZO Server IP address(es)

Client software must not hardcode any TZO IP addresses. Clients should always use the update server's hostname: rh.tzo.com. To manage load, TZO will change server IP addresses without advance notice.

DO NOT 'ping' TZO Servers

It is not acceptable to ping TZO servers. The TZO servers will reject ICMP requests ('ping') at the firewall, even for www.tzo.com. To determine if th Internet connection is up, use methods that do not involve TZO servers.

DO NOT use DNS Queries To Determine if an domain 'needs' to be Updated

Clients must never use DNS [example: gethostbyname()] as part of the logic used to trigger DNS Updates.

For the technically curious, the reason for this rule requires an understanding of DNS's distributed nature. You can never trust that your local DNS (or ISP's DNS) server is configured perfectly. Consulting DNS records to test if an update is needed will cause an 'update loop' condition which is severely abusive.

Note that querying the ISP/local DNS server for informational/display purposes is acceptable, provided:
a) DNS record queries must never be used as a test condition for controlling DNS updates.
b) The Client must never hardcode queries to TZO's nameservers.

DO select and a meaningful User-Agent for your update Client

TZO requires all Client software provide (via HTTP headers) a valid and meaningful User Agent. This User Agent information is used by TZO to allocate resources to your Client, and notify you (the Client author) of any Client-related issues. User Agents must be unique to your Client and must identify your client version.

DO register your Client's User-Agent with TZO

Please submit to TZO Developer Support (devsupport@tzo.com) your dynamic DNS client information, including the User Agent string.


DO Customize User-Agent strings if using existing DNS Client code

If your DNS client based on an existing dynamic DNS client code, please customize the User-Agent string to reflect your company, product model number, and firmware release.

For example: A hardware vendor embedding fictional open source Client 'ez-something' would customize the User-Agent string to be something like 'ez-something (WRDI-123rev4, Firmware 2.12)' or similar.

DO NOT use User-Agent strings which are too generic or known to be abusive

The following User-Agent strings are not supported: NULL, 'myclient/1.0', 'ddns', 'ddnsc', or '$username/1.0') are not considered unique and are not identifiable.

DO Process TZO Response Codes Completely

All Webclient-2 Response Codes (be it Basic or Extended Response) will begin with a 3-digit number. It is up to you to decide which method is more convenient for your development.

Clients must react to all possible Response Code scenarios, as outlined in the TZO DDNS flowchart. Never assume the update was successful, as this leads to server abuse.

DO Provide User Feedback with TZO Response Codes

Clients must show the results of the last attempted Update Request. Ideally this information is saved into a logfile. If the Response Codes are hidden from the user, the Client must display a custom error message that communicates the same message TZO intended. Such custom Client Response messages must begin with the same 3-digit Response Code that TZO has designated within the WebClient-2 API.

For example, a 'bad authentication' Response Code is '401'.
If your Client were localized for Espańol, your client would process the TZO Response Code '401' (or '401 bad authentication, if using &Info=1). Your own translation of the message might be: '(401) La conexión falló - el mal username, la contraseña, o el Domain Name'.

Retaining Response Code numbers will greatly improve communication, even though the the Client is third party and possibly in an unsupported language.

DO Record a Log of Dynamic DNS Update Responses

Many TZO customers prefer to use a dynamic DNS client already built into their router, camera, or Digital Video Recorder (DVR). Especially in such cases, it is important to the customer that the dynamic DNS client be transparent with respect to DNS account updates.

For example, if a DDNS client does not log any output from DDNS updates, then TZO Support will be challenged when asked to support your client. A Client that does not support logging or a debug mode is a 'black box', unable to be supported by anyone except the author of the Client.

DO Raise an Error when a Response Code indicates an account is suspended

If DNS updates have been suspended due to a permanent failure, provide some hint in the Client user interface to make clear that this action was required due to Configuration or Account issues. If the problem is not obvious o the client (such as 'bad authentication'), please suggest the user contact TZO Support.

DO Consider (optional) adding a feature for 'Managed Restarts' of Expired Accounts

Many account holders are non-technical users, who may have paid a local 'camera (or network) installer' to manage setup of their network. Such users may not process a bill in a timely manner, and allow their TZO service to lapse. From a Client feature-list perspective, it is advantageous to support 'Managed Restarts' of expired DNS accounts.

The 'standard' method for handling Expired Response Codes is to DISABLE the DDNS client until the user re-enters their account information (this prevents service abuse of the TZO servers). The more user-friendly approach is to support TZO 'Managed Restarts' of the accounts (which is OPTIONAL and described below).

Upon an Expired Response Code from TZO, the client MAY:

  1. For a limited time* (see below), you may 'test' the expired account daily to see if the user has renewed service with TZO.

    DETAILS:When TZO says an account is Expired, you may (at 24 hour intervals) issue a 'forced' Update request. This is a SPECIAL exception to the prohibition on forced-timer updates. If the update is forced once every 24 hours (86400 seconds) this will not cause any problem.

    IMPORTANT: The forced update regimen must end when TZO changes the Response Code. The Code could change to '200' (user's service contract restored), or the Response Code may change to '401' (account deleted).

  2. Clients must indicate what steps they are taking due to the expiration notice: either shutting down completely, or retrying every 24 hours.


NOTE: Expired Accounts exist in limbo for a set number of days according to TZO policy. TZO considers the account to be customer property, and TZO will 'reserve' that account in the customer's name to allow opportunity to renew. The Client need only to shutdown OR 'retry every 24 hours'. Eventually the account will change status once more, returning to '200' (success - the customer has renewed) OR account becomes '401' ('bad authentication' - the domain no longer exists). Client must respond to final codes appropriately.

DO NOT use ''forced' updates'

Clients should never blindly invoke the Update URL based on a timer (this is abuse).

Any Client design must support a means for 'checking the IP address' and caching Updates.

DO Error check domain/hostname, username, and password fields.

Do not not attempt to issue a DNS Update Request if the authentication fields are hopelessly wrong. For example, if these user fields are blank and they enable TZO Updates, you must report an error to the user and set the client to disabled.

DO Perform basic Fully Qualified Domain Name checking

If the user does not input an RFC-compliant domain name, shut down the DNS client and notify the user of an input error.
For example, you should not accept as hostname input any of the following examples: 'myserver' (no .TLD), 'my server dot com' (spaces, invalid), or 'http://example.com' (hostnames do not include the '<schema:>//' -- the actual 'domain' does not include 'http:// prefixes. This is a common user error).

For hostname correctness, please see the various RFC documents: RFC1035, RFC1123, RFC2181.

DO NOT attempt to 'automate' TZO.COM DDNS account creation

It is TZO Policy that DNS accounts must be created using approved methods: the user themselves must create the account on http://www.tzo.com/ using a web browser. TZO provides new users with the option of limited-duration free trial accounts.

Client authors wishing to provide closer integration with TZO (including embedded accounts or 'plug and play' domain setup, etc.) should consult the TZO Partners page at http://www.tzo.com/MainPagePartners/.

Please do not employ 'web scrape' techniques, or parse any TZO.COM webpage output except from the Update URL provided in this document.

DO consider how the Client will monitor IP addresses

A DDNS Client operating behind a router or NAT connection must have a method or accessing a 'web check IP' IP-address reporting application. Clients that feature TZO may request permission to use TZO's check IP script.

Client vendors supporting multiple DDNS providers should webhost their own 'check IP' script (TZO can provide example server code implementations upon request).

DO consider optional/extra support for port 21333 Updates

Some ISPs will force all port 80 traffic through a web proxy, which may sometimes interfere with dynamic DNS Updates. It is a good idea to offer a checkbox (not selected by default) which offers the ability to update using an 'alternate port'.

DO NOT use port 443 (HTTPS) for GET-style requests

HTTPS is reserved for POST requests, not GET. GET requests over HTTPS are not blocked (but someday may be).

Additional Support and Information

If you have any questions or require any assistance, please email devsupport@tzo.com

Appendix C - Example HTML configuration implementation

The following outlines an example DDNS configuration screen, provided as a convenience/template for your development. This type of configuration screen is commonly found in embedded platforms configurable using a browser, such as routers, firewalls, or IP cameras.

The example illustrates user interface elements TZO feels will make the DDNS (and server) experience more user friendly. The HTML is W3.org compliant HTML that will work in any modern browser - feel free to adapt the HTML as you wish.

Features provided by this Example DDNS form:



Illustration 1: Screenshot -- Example selection of TZO options (HTML rendered)


Screenshot - Example DDNS Configuration in HTML

Example DNS Configuration - HTML Source Code

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"

"http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">

<title>EXAMPLE TZO Configuration</title>

<style type="text/css">

body,html {

color:black;

background-color:white;

}

.setddns { padding-bottom:1px;}

.setddns p span,.setddns label,.sethost label,.setuser label,.setpass label {

font-weight:bold;

clear:both; /* a reset after float:left */

}

.sethost label,.setuser label,.setpass label {

float:left;

text-align:right;

min-width:12em;

margin-right:.5em;

}

.setpass {

margin-bottom:5px;

}

legend {

font-weight:bold;

color:blue;

background-color:white;

}

.ddnsresults {

margin-top:10px;

}

.submitbtn input {

background-color:#bbb;

color:black;

}

</style>

</head>



<body>

<div id="content">



<form action="#"><!-- set submit action here -->

<fieldset>

<legend>TZO Dynamic DNS Configuration (DEMO)</legend>

<div class="setddns">

<p><span>DDNS state:</span>

<input name="tzoddns" id="tzoddnson" value="1" type="radio"><label for="tzoddnson">Enabled</label>&nbsp;

<input name="tzoddns" id="tzoddnsoff" value="0" checked="checked" type="radio"><label for="tzoddnsoff">Disabled</label><br />

</p>

</div>



<div class="sethost">

<label for="hostname">Domain Name</label>

<input name="hostname" id="hostname" size="40" maxlength="65" value="" type="text"><br />

</div>



<div class="setuser">

<label for="user">Email (or Username)</label>

<input name="user" id="user" size="40" maxlength="65" value="" type="text"><br />

</div>



<div class="setpass">

<label for="pass">TZO Key (or Password)</label>

<input name="pass" id="pass" size="40" maxlength="40" value="" type="password"> <br />

</div>



<div style="float:right">

<!-- These links are generic examples suitable for DDNS clients.

If you have agreements with TZO, please consult those

agreements for a canonical list of URLs to display. -->

<ul>

<li><a href="http://www.tzo.com">Try TZO Free for 30 days!</a></li><!-- REQUIRED link -->

<li><a href="http://www.tzo.com/MainPageSupport/TutorialsPage.html">TZO Tutorials</a></li><!-- OPTIONAL link -->

<li><a href="https://www.tzo.com/">TZO Control Panel</a></li> <!-- OPTIONAL link -->

<li><a href="https://www.tzo.com/cgi-bin/Orders.cgi">Order TZO Dynamic DNS</a></li><!-- OPTIONAL link -->

</ul>

</div>



<fieldset>

<legend>Advanced Use Only</legend>

<!-- altport tells the DDNS client to send web updates over port 21333. If double-NAT (this router is not the border),

beware a 21333 request may be filtered by the border firewall. -->

<input name="altport" id="altport" value="0" type="checkbox">

<label for="altport">Update DNS using alternate ports (bypass local web proxy)</label><br />



<!-- altwan tells DDNS client to NOT check WAN IP over the web, and instead use the IP

address found on the WAN port. Not safe to use unless the router holds the Internet connection IP -->

<input name="altwan" id="altwan" value="0" type="checkbox">

<label for="altwan">Disable web IP check (use hardware WAN IP)</label><br />

</fieldset>



<div class="submitbtn">

<input type="submit" value="Save Settings">

</div>



<!-- end master fieldset -->

</fieldset>



<fieldset class="ddnsresults">

<legend>Recent DDNS Update Results</legend>

<code>

<b>Current WAN IP: {$CURRENT_IP}</b><br />

Connection IP last checked: 00:00:00<br />

Next check for Connection IP: 00:00:00:00<br />

Last IP Update time: MM/DD/YY 00:00:00<br />

Update Server Response:{$TZO_RESPONSE_CODE_EXTENDED}<br />

</code>

</fieldset>

</form>





</div><!-- content -->

</body>

</html>

Dynamic DNS Update Specification v2.00 -- Copyright 2006 Tzolkin Corporation (Page 31/31)