HF PanelDocsv1.0.0

Dynamic DNS

Keep a host name pointed at a changing IP address from a router (dyndns2) or a script, with the update addresses and answers.

Dynamic DNS keeps a name such as home.example.com pointing at an internet connection whose IP address changes. A router or a small script tells HF Panel the new address, and HF Panel updates the name's A or AAAA record straight away. Customers create the names; this page describes the two update addresses.

Where: Control Panel › Domains › Dynamic DNS

Create a name and its token

  1. Under Add a Dynamic DNS name, type the Name (for example home) and choose the Domain.
  2. Optionally, type a First address (optional) and tick Email me when the address changes.
  3. Click Add.
  4. Copy the token now. It is shown only once. If you lose it, click New token to make another; the old one stops working.

The token box also shows the router settings, the update address and a ready-made curl command for your name.

Note: Dynamic DNS needs the domain's DNS to be hosted on this server.

The update addresses

Address For Signs in with
https://api.yourdomain.com/nic/update routers (the dyndns2 protocol) HTTP basic authentication; the token is the password
https://api.yourdomain.com/v1/ddns/update scripts the token in the query or body

Both answer on ports 443 and 2087. On a server without the API's own address, use https://panel.yourdomain.com:8443/nic/update and https://panel.yourdomain.com:8443/ddns/update. The Setting it up card on the Dynamic DNS screen always shows the right addresses for your server.

Neither address needs a session or an API token: only the Dynamic DNS name's own token.

Routers: /nic/update (dyndns2)

In your router's Dynamic DNS settings, choose the dyndns2 or custom service and enter:

Router setting Value
Server api.yourdomain.com
Username your Dynamic DNS name, for example home.example.com
Password the name's token
Host name your Dynamic DNS name

The request your router sends looks like this:

bash
curl -s -u "home.example.com:TOKEN" \
     "https://api.yourdomain.com/nic/update?hostname=home.example.com&myip=203.0.113.25"
text
good 203.0.113.25
Parameter What it does
hostname one name, or up to 20 names separated by commas. Without it, the basic authentication username is used
myip the new address. You can send an IPv4 and an IPv6 address separated by a comma. Without it, the address the request comes from is used
myipv6 an IPv6 address, as an alternative to putting it in myip

The answer is plain text, one line per name:

Answer Means
good <ip> the record was changed to this address
nochg <ip> the record already had this address; nothing changed
badauth wrong token for this name (HTTP 401 when it is the only name)
nohost no such Dynamic DNS name
notfqdn not a full host name
numhost more than 20 names
badip not a usable IP address
abuse too many requests (see the limits below)
dnserr the record could not be written
911 a server error; try again later

Scripts: /v1/ddns/update

GET or POST, with the token in the query or a form body:

Parameter Required What it does
token yes the name's token
ip no the new IPv4 or IPv6 address. Without ip and ipv6, the address the request comes from is used
ipv6 no a new IPv6 address
bash
curl -s "https://api.yourdomain.com/v1/ddns/update?token=TOKEN"
json
{
    "ok": true,
    "result": "good",
    "host": "home.example.com",
    "ipv4": "203.0.113.25",
    "ipv6": ""
}
Status result Means
200 good or nochg updated, or nothing to change
401 badauth unknown or wrong token
409 nohost, dnserr the update could not be made
422 badip not a usable IP address
429 abuse too many requests
500 911 a server error

Run the script every few minutes, for example from cron:

bash
*/5 * * * * curl -s "https://api.yourdomain.com/v1/ddns/update?token=TOKEN" > /dev/null

Limits

  • 120 update requests per name an hour. Updates that change nothing count, but do not change the record.
  • 12 address changes per name an hour.
  • 20 refused requests (wrong token, unknown name) from one client address in 15 minutes. After that, every request from that address answers abuse (HTTP 429) for 15 minutes.

Each change sets the record's TTL to 60 seconds, publishes the zone, and appears in the name's History.

Tip: keep the token out of shared scripts and screenshots. Anyone with it can point your name somewhere else.