DynDNS2 protocol

Most routers and DDNS clients speak the DynDNS2 update protocol (the one Dyn and No-IP made standard). legitdns speaks it too, at the standard address:

GET https://legitdns.com/nic/update

If a device offers a "custom" or "user-defined" DDNS service, this is the page to set it up from. Per-brand steps: router guides.

The request

Method: GET.
Authentication: HTTP Basic - username is the full hostname, password is its update token. There is no account-wide password (see Tokens).
User-Agent: required. Routers send one automatically; a hand-written call must too, or the answer is badagent.

Parameters:

Name	Meaning
`hostname`	The hostname to update (see the multi-hostname rule below)
`myip`	Optional, advanced: the address to publish - an IPv4 address, an IPv6 address, or both, comma-separated. Omit it and we publish the address the request came from
`myipv6`	Optional separate IPv6 address; when present it wins over the IPv6 part of `myip` (some clients send IPv6 this way)

Most setups omit myip - that is how routers behind NAT behave, and it does the right thing.

Example (normally your router builds this for you):

curl -u "mypi.pihome.example:YOUR-TOKEN" -A "myrouter/1.0" \
  "https://legitdns.com/nic/update?hostname=mypi.pihome.example"

The answer

Always plain text with HTTP 200. First word is the result code; a success is followed by the addresses now in effect.

Answer	Meaning
`good <ips>`	Updated and published
`nochg <ips>`	Nothing changed - either the addresses already matched, or the hostname is offline or in redirect mode and the update was saved as its last-known values instead of being published
`nohost`	The hostname does not exist, or is not the one the credentials belong to
`badauth`	The token is wrong, revoked, expired, or the update came from a source the token does not allow
`notfqdn`	The hostname is not a fully qualified domain name
`badagent`	The request had no User-Agent, or was not a GET
`abuse`	Rate limited - too many attempts from your address, or too many updates on the account. Back off and retry later
`911`	A problem on our side. Wait and retry; do not loop
`badrequest`	An address in `myip` was malformed, or is not a public address, and could not be used

Private and loopback addresses are refused - they can never work from the internet.

One deviation: the protocol has no standard code for "the address you sent is malformed", so we answer the plain word badrequest rather than misuse another code. Clients treat anything but good/nochg as failure, which is the behaviour we want.

Naming several hostnames at once

hostname may carry a comma-separated list - some clients send one request for several names. Our credentials are per-hostname, so:

The hostname matching the Basic-auth username is updated, if it appears in the list. It is the only name updated and the only name answered for.
Every other name is ignored: not updated, not checked, not recorded.
If the username's hostname is not in the list (or no credentials were sent), the answer is nohost.

Give each hostname its own client entry with its own token and this never comes up.

Held updates

Two panel settings hold updates instead of publishing them; both answer nochg, never a fake good:

Offline - updates are authenticated and recorded, addresses kept as last-known, nothing published until the hostname is back online.
Redirect mode - the same, so a chatty device cannot overwrite the redirect.

The update API reports these as offline_held / redirect_held; your history page shows the same reasons.

Service-wide modes hold updates the same way: while the service is in maintenance or read-only mode, updates are authenticated and recorded but not published, and the answer here is nochg too. The API names those maintenance_held and read_only_held.

Being a good citizen

Update only on change, and stop on errors:

badauth / nohost: fix the config - retrying will not help and counts against the rate limits.
abuse / 911: wait - an hour for abuse, a few minutes for 911.
Even on a timer, every few minutes is plenty.