API Documentation
DNS-O-Matic gives dynamic IP address users a simple way to distribute their IP changes to multiple services with a single update. The DNS-O-Matic API enables that service for client developers.
The API should be used by all client developers (software or hardware) who need to distribute IP address updates to dynamic DNS services.
- Version: 0.9 (When the API reaches version 1.0, all future changes will be backwards compatible.)
Those familiar with the DynDNS Remote Access Update API will find the DNS-O-Matic API similar.
Quick Overview
- Client software initializes or detects a change in the client IP adddress.
- Client software sends an update request to DNS-O-Matic.
- DNS-O-Matic acknowledges update.
- DNS-O-Matic propagates update across all user subscribed services.
Detecting Changes
A client must know its current public IP address and trigger updates when necessary. Clients can determine the current public IP via the operating system's network stack or via web detection, useful for private IPs (RFC 1918 space).
DNS-O-Matic operates a web service for detecting the user's public IP, available to clients that work with DNS-O-Matic.
An HTTP request to http://myip.dnsomatic.com/ will return the public IP of the client. Example:
HTTP/1.1 200 OK Content-Type: text/plain Server: DNS-O-Matic - MyIP0.3 Connection: close Cache-Control: no-cache Pragma: no-cache Content-Length: 105 1.2.3.4
For clients using OpenDNS, a DNS request for ''myip.opendns.com'' will always return the public IP of the client. Example:
$dig myip.opendns.com +short 1.2.3.4
Sending the Update
When a change in IP address is found or a user alters any of their settings, the client should perform an update. All updates are sent using a well-formed HTTP request. DNS-O-Matic will pass back a return pre for the client to parse. The API is a REST-based system.
HTTP Request
When sending an update to updates.dnsomatic.com be sure to always do a DNS query to resolve the IP for this host. Implementors MUST NOT hard code the IP for updates.dnsomatic.com as they may change from time to time.
Update requests must be sent using HTTPS on port 443,
Hostname: updates.dnsomatic.com HTTPS port: 443
Note: All clients must send a well-formed User-Agent including company name, model number, and software build revision. An example would be:
SoftwareDev - Fast Update Client - 2.0
Failure to use a well-formed and consistent User-Agent string MAY result in failed update requests.
Sample Updates
URL Authentication: For web browsers or utilities (fetch, curl, lwp-request) which parse authentification section in URL.
https://username:password@updates.dnsomatic.com/nic/update?hostname=yourhostname\ &myip=ipaddress&wildcard=NOCHG&mx=NOCHG&backmx=NOCHG
Users need to enter a DNS-O-Matic username and password. DNS-O-Matic usernames are 3-25 characters. DNS-O-Matic passwords are 6-20 characters. All ASCII letters and numbers accepted. Dots, dashes, and underscores allowed, but not at the beginning or end of the string.
Users will also enter a list of hostnames (FQDNs) to be updated.
Note on service passwords: Many dynamic DNS services have an update password, separate from the account password. When a user sets up a service to be updated by DNS-O-Matic, they will be asked to provide their update password (if available), and encouraged strongly not to provide their service password unless no other alternative exists.
Regardless, all DNS-O-Matic registration and configuration happens under SSL, and the service information provided will be encrypted.
HTTP Request: Sample request only. Follow your request by sending empty line.
Base64-encoded authorization should be represented by Base 64 encoded username:password string.
We recommend using the GET HTTP method, however either GET or POST may be used.
GET /nic/update?hostname=yourhostname&myip=ipaddress&wildcard=NOCHG&mx=NOCHG&backmx=NOCHG HTTP/1.0 Host: updates.dnsomatic.com Authorization: Basic base-64-authorization User-Agent: Company - Device - Version Number
Update Parameters
hostname
Hostname you wish to update. To update **all** services registered with DNS-O-Matic to the new IP address, hostname may be omitted or set to all.dnsomatic.com (useful if required by client). This field is also used for services that use different names for the unique identifier of the target being updated (ex. freedns.afraid.org, TZO). DNS-O-Matic will format the update string appropriately for each supported service at distribution.
myip
IP address to set for the update. If not specified, the best IP address the server can determine will be used (some proxy configurations pass the IP in a header, and that is detected by the server).
wildcard
Parameter enables or disables wildcards for this host. ON enables wildcard. NOCHG value will keep current wildcard settings. Any other value will disable wildcard for hosts in update.
mx
Specifies a Mail eXchanger for use with the hostname being modified. The specified MX must resolve to an IP address, or it will be ignored. Specifying an MX of NOCHG will cause the existing MX setting to be preserved in whatever state it was previously updated.
backmx
Requests the MX in the previous parameter to be set up as a backup MX by listing the host itself as an MX with a lower preference value. YES activates preferred MX record pointed to hostname itself, NOCHG keeps the previous value, any other value is considered as NO and deactivates the corresponding DNS record.
Other Parameters
DNS-O-Matic will accept and distribute these parameters for compatibility with services which support the DynDNS Update API. However, DNS-O-Matic does not use/need them.
offline
Sets the hostname to offline mode. YES activates feature and turns on offline redirect for hostname (if set). NOCHG could be used to keep current state.
system
Previously used to identify update type
url
Reserved for future use
Unknown parameters may be ignored or may lead to a return code of abuse.
Return Codes
The DNS-O-Matic response does not necessarily reflect the service's response, just the DNS-O-Matic response. DNS-O-Matic distributes the update to the selected services asynchronously.
All responses from the services are logged to the user's account. If the service response is an error which cannot be addressed by DNS-O-Matic, then the user will be notified via email and on the DNS-O-Matic website of the error, with suggestions about how to resolve the error.
DNS-O-Matic returns one error code per update, in this form
good <ip>
The update was accepted and will be distributed to all linked services.
nochg <ip>
The update succeeded, with no change. DNS-O-Matic will not re-distribute successive ''nochg'' updates. This is to avoid abuse as well as save bandwidth and server infrastructure for both DNS-O-Matic and the supported services.
badauth
The DNS-O-Matic username or password specified are incorrect. No updates will be distributed to services until this is resolved.
notfqdn
The hostname specified is not a fully-qualified domain name.
nohost
The hostname passed could not be matched to any services configured.
numhost
You may update up to 20 hosts. numhost is returned if you try to update more than 20 or update a round-robin.
abuse
You are sending updates too frequently and have been temporarily blocked.
badagent
The user-agent is blocked.
dnserr
DNS error encountered. Stop updating for 30 minutes, and optionally ask the user to contact DNS-O-Matic.
911
There is a problem or scheduled maintenance on DNS-O-Matic. Stop updating for 30 minutes, and optionally ask the user to contact DNS-O-Matic.
