Hardware Client Authoring Hints

Elements listed as optional are not required for a client to be certified; however, implementing those is recommended.

Even if you do not plan to apply for any of the certification programs, we still strongly recommend following these recommendations in your client, as they will improve your client's behavior and reduce your support costs.

Internal Coding Practices

  • The client must not hardcode any IP addresses of DynDNS servers. Only the names (e.g. members.dyndns.org, checkip.dyndns.org) should be hardcoded.

IP Detection and Update Frequency

  • Hardware products should not use web-based IP detection; instead, they should simply use their WAN IP (for routers) or IP (for other devices) for updates.
  • Hardware routers should always specify their IP in the update request.
  • If the IP returned after a good or nochg return code is different from the router's current IP, then the client should turn itself off.
  • The client should store the IP of the last update in memory. It is not required to store the date and time of the last update.
  • The client should store the last update IP, along with the return code, in non-volatile memory, and not update on device start-up unless the IP is different.
  • The client must not update on a DHCP lease renewal unless the IP in the new lease is different from the IP of the previous lease.
  • The client should not update on a PPP/PPPoE connection unless the IP is different. Many PPP/PPPoE systems try to reassign the last IP when a user reconnects, so the client must not assume each PPP/PPPoE connection will result in a different IP.
  • The client must not update when the configuration of other features of the hardware products unrelated to DNS is modified.
  • The client should update after its configuration has been changed to confirm that the new configuration works and provide the user with appropriate error information if it does not. Such an update also ensures the client has an IP stored to use for determining whether to update later.
  • The client should not use DNS queries to determine whether an update is required. While this may appear to work, caching considerations make this practice very dangerous, especially with Custom DNS.
  • The client must not use DNS queries to determine whether an update was successful. A good or nochg return code indicates update success.
  • The client may update 28 days after the last update to prevent expiration in Dynamic DNS. Due to the difficulty of keeping track of the time of the last update and figuring out how long it has been since the last update, as well as testing challenges for such a feature, inclusion of such a feature in a hardware product is not recommended. (Optional)

Communication with DynDNS Servers

  • The client must send a unique useragent that identifies the manufacturer, model number, and firmware version.
  • Updates can be performed through normal HTTP or HTTPS. If an SSL library is available on the hardware platform, we strongly recommend HTTPS be used. As we recognize incorporating SSL on some hardware is logistically challenging, regular HTTP updates will continue to be supported.
  • The client should only look at the body of the HTTP response, and should not rely on HTTP error codes to determine success or failure.
  • If the client gets no reply from DynDNS servers, it should wait a minimum of 10 minutes before trying again.

Interface Design

  • The hardware product should ship with the client disabled.
  • When the user first enables the client, no default user information should in the client configuration interface.
  • The client should not ask for a server name. As each DNS provider uses a different update method, a client that supports multiple DNS providers should provide a list of supported providers and hardcode the appropriate server name for each provider. Making server name configurable does not enhance the flexibility of the client, but causes significant user confusion and the technical support costs associated with such confusion.
  • For Dynamic DNS, the client should not provide a list of domains, but should provide the user with enough room to enter a fully- qualified hostname (eg: theirname.dyndns.org, or theirname.dnsalias.com). New domains may be offered in Dynamic DNS, and clients should not require an update to work with hostnames in these new domains.
  • The client should allow at least 40 characters to be entered in the hostname field.
  • The client should allow for multiple hostnames to be entered, either in separate field or in a single hostname field with each hostname separated by commas. (Optional)

Error Handling

  • If the client receives a fatal error (badauth, nohost, notfqdn, !yours, etc), then the client should disable itself until the user has an opportunity to correct the configuration.
  • If the client receives an abuse error (which, if you've followed all of the instructions in this document, should never happen unless something other than your product was responsible for the block), it should either stop updating just like with any other fatal error, or, only if it notifies the user through e-mail or other means that do not involve the user actually logging into the hardware product, may update once every 24 hours until it no longer gets an abuse response.
  • Error status should be stored in non-volatile memory so that restarting the hardware device does not destroy error responses from the client. (Optional)
  • The client should make the exact return code available to the user available. "Update failed" messages are not helpful.
  • The client should provide friendly interpretations of return codes (eg: "Hostname is not yours" for !yours). If a client does this, and the error messages clearly imply what return code was returned, then it is not necessary to make the raw return code available to the user. (Optional)
  • A nochg return code, if followed by the hardware device's current IP, that results from an update following a configuration change should be treated as a good response. (Optional)
  • If the hardware product already has system-wide logging, that same logging infrastructure should be used for DNS client errors.
  • Hardware clients may want to want to provide an e-mail notification option to let the user know that an error occurred. (Optional)
  • If the client supports updating multiple hostnames, the error handling should be able to accommodate multiple return codes in the spirit of the recommendations above. (Optional).