Citrondns API

Below you will find a set of routines, protocols, and tools for building software applications around the Citrondns platform. This allows for the creation of client applications that access the features of Citrondns.

Citrondns update client design

It is very important that your update client observe a few rules to avoid unnecessary connections to your DDNS server. A poorly designed client application can and will cause your DDNS server to be flooded with unneeded update requests. For example, imagine that a company has fielded 30,000 devices each using an embedded DDNS client that sends an update every 1 minute, needed or not. This will result in 43,200,000 daily updates. Each would require a Database lookup. A little extra time spent on client development can save hundreds if not thousands of dollars down the road.

Your DDNS client should not send unnecessary IP updates. When a successful update is sent to the DDNS server, your DDNS client should store its detected WAN IP address. Your client should then poll the IP detection method defined below every few minutes and compare the detected IP address to the stored IP address. If an IP change is detected an update should be sent to the DDNS server. If successful your client should store the new IP address and the process should be repeated indefinitely.

Your device should send an IP update upon reset/reboot even if an update is not needed.

CitronDNS does not use user accounts and instead uses an encrypted MAC Address, Serial number or other unquie field from a device to secure access to the DDNS server. When used in conjunction with SSL this DDNS is the most secure available. CitronDNS will eliminate any possibility of a misconfiguration between a Device and DDNS server. CitronDNS is designed to allow an end user to completely manage their DDNS name(s) from within your devices configuration pages.

CitronDNS is fully customizable. Any fields you may want to collect from a device like TCP Port information, Firmware Version, Hardware Version etc.. can be added in just a few minutes by our team.

Helpful tools

There are HTTP tools such as libcURL, cURL or INADYN which can be used to simplify the development process. There are also tools which can help create perfectly formatted HTTP headers for use in your code, like Wfetch 1.4.

Citrondns update protocol

The HTTP Request(s)

Please see RFC 2616 for information about the HTTP Protocol. All human editable fields should be trimmed of white spaces. All fields must be URL encoded before being sent to the DDNS server.

GET Request (Adds a DNS record.)

GET /add.aspx?mac=encrypted-mac-address&dm=yourhostname&myip=ipaddress
Host: view.camera
User-Agent: Company - Device - Version Number

Reply codes:
01 = Invalid hostname
02 = Invalid MAC
04 = Invalid IP
07 = Hostname already in use
08 = Update with no change
09 = Update with records modified
10|user.domain.com = Domain Created (Reply code with | delimiter and full domain name.)
911 = Flood Detected
12 = Server Error

GET Request (Updates a DNS record)

GET /update.aspx?mac=encrypted-mac-address&myip=ipaddress
Host: view.camera
User-Agent: Company - Device - Version Number

Reply codes:
02 = Invalid MAC
04 = Invalid IP
13 = No record found
08 = Update with no change
09 = Update with records modified
911 = Flood Detected
12 = Server Error

GET Request (Removes a DNS record)

GET /remove.aspx?mac=encrypted-mac-address
Host: view.camera
User-Agent: Company - Device - Version Number

Reply codes:
02 = Invalid MAC
12 = Server Error
13 = No record found
15 = Successful Delete
16 = Delete Failed

GET Request (Returns a devices registered IP.)

GET /ipcheck.aspx?mac=encrypted-mac-address
Host: view.camera
User-Agent: Company - Device - Version Number

Reply codes:
02 = Invalid MAC
12 = Server Error
13 = No record found
14|0.0.0.0 = Successful lookup with | delimiter and IP

GET Request (Detects current WAN IP. Use this file for IP detection.)

GET /ipdetect.aspx
Host: view.camera
User-Agent: Company - Device - Version Number

Reply codes: WAN IP ADDRESS

The Citrondns ISAPI

The CitronDNS ISAPI can be used to capture input from existing DDNS clients and redirect those requests to an aspx page of your choosing. The ISAPI can be modified to support any existing third party client, even those using custom update protocols.
If you are going to use an existing non standard firmware client, you can use the ISAPI to redirect requests for .php or .pl pages(Or any page type from other servers.) to an appropriate aspx page on your DDNS server.
The ISAPI is written in Visual C++ v8.0 and compiles with Visual Studio 2005 or later.
The source code of this tool is provided upon request. Modifications are provided by our team free of charge.

Definitions

MAC

Encrypted MAC address. This field must be encrypted, base64 encoded and URL encoded. This field is used to secure all DNS routines. This is a required field.

MYIP

IP address to set for the update. If this field is not specified, the DDNS server will determine the current WAN IP. If the IP address passed to the system is not properly formed, the update will be rejected.

DM

A users desired hostname. This should only include the subdomain requested by the end user. The field should not include the full domain name. This field should be trimmed of all whitespaces and URL encoded.

Contact Information

Adamsland Microsystems
P.O. BOX 296
Huntsville AR. USA, 72740
Phone: +01-479-789-0292
Email: sam@dyndnsservices.com