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.
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. (TO BE LINKED)
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: <cli> $dig myip.opendns.com +short 1.2.3.4 </cli>
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 code for the client to parse. The API is a REST-based system.
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 may be sent using HTTPS (preferred) on port 443 or HTTP on port 80 to updates.dnsomatic.com
.
Hostname: updates.dnsomatic.com HTTPS port: 443 HTTP port: 80
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.
URL Authentication: For web browsers or utilities (fetch, curl, lwp-request) which parse authentification section in URL.
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 with their DNS-O-Matic password.
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
This copy is subject to minor change based on feedback!
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. What does wildcard do & mean in this context?
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.
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
. We have not yet determined if they will be distributed to other services.
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 in a separate process.
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 line for each service updated, in this form
SUCCESS
"good <ip> <hostname> <service>"
ERROR
"‹code› <ip> <hostname> [<service>]"
good
means the update was scheduled successfully.
nochg
indicates success, 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. If no hostnames included, notfqdn
will be returned once.
nohost
The hostname passed could not be matched to any services configured. The service field will be blank in the return code.
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
The hostname is blocked for update abuse.
badagent
The user-agent is blocked.
good 127.0.0.1
This answer indicates good update only when 127.0.0.1 address is requested by update. In all other cases it warns user that request was ignored because of agent that does not follow specifications.
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.