A customer hosts their main website on cPanel but also wants to expose their home NAS or office camera under a subdomain. Their ISP gives them a dynamic IP that changes every few days. cPanel doesn’t have a built-in dynamic DNS service, but the whmapi1 API plus a small cron on the customer’s end is a clean equivalent. The tricky parts are credentials and rate limiting.
What’s happening
Dynamic DNS, in the original sense (No-IP, DynDNS), is a service that exposes an HTTP endpoint where a small client posts its current IP, and the service updates a DNS record. cPanel doesn’t ship that endpoint as a feature. But cPanel’s whmapi1 API has editzonerecord, which does the same job — update an A record with a new IP. The customer needs:
- An API token with the right scope.
- A client (a few lines of bash, a router with curl, an IoT widget) that detects the public IP and calls the API on change.
The trade-offs vs a hosted dynamic DNS service:
- Pro: the record stays under the customer’s domain, not under a generic provider’s subdomain.
- Pro: no third-party service to depend on or pay for.
- Con: API tokens are sensitive. A compromised token can update any record in any zone the token has access to — including potentially the customer’s mail records.
- Con: client code lives at the customer’s end. If it breaks, the customer has to debug.
How to verify
Confirm the current IP and the record:
curl -s ifconfig.me
dig +short home.example.com
If they differ, the dynamic DNS update job is stale or failing.
Check the cron’s last run on the customer’s end:
# customer's side
crontab -l
cat /var/log/ddns-update.log | tail -20
For the API call itself:
curl -sk -H "Authorization: whm root:TOKEN" \
"https://cpanel-host.example.com:2087/json-api/editzonerecord?api.version=1&domain=example.com&Line=N&name=home.example.com.&type=A&address=$(curl -s ifconfig.me)&ttl=300"
Should return JSON with result.status: 1 on success.
What to do
- Generate a scoped API token on the cPanel host. WHM > Development > Manage API Tokens. Scope to the smallest possible permission — for dynamic DNS, only
editzonerecordfor the specific zone if cPanel’s token system supports per-zone (older versions don’t; newer let you scope by feature group). - Create the dynamic record in cPanel Zone Editor first, with TTL set to 300:
home.example.com IN A 192.0.2.10
- Write the client script on the customer’s side. A minimal bash:
#!/bin/bash
TOKEN="<whm-api-token>"
HOST="cpanel-host.example.com"
ZONE="example.com"
NAME="home.example.com."
CURRENT=$(dig +short $NAME)
NEW=$(curl -s ifconfig.me)
if [ -z "$NEW" ] || [ "$CURRENT" = "$NEW" ]; then exit 0; fi
# Find the line number of the existing A record
LINE=$(curl -sk -H "Authorization: whm root:$TOKEN" \
"https://$HOST:2087/json-api/dumpzone?api.version=1&domain=$ZONE" \
| jq -r ".data.zone[].record[] | select(.name==\"$NAME\" and .type==\"A\") | .Line")
# Update
curl -sk -H "Authorization: whm root:$TOKEN" \
"https://$HOST:2087/json-api/editzonerecord?api.version=1&domain=$ZONE&Line=$LINE&name=$NAME&type=A&address=$NEW&ttl=300"
echo "$(date) updated $NAME from $CURRENT to $NEW" >> /var/log/ddns-update.log
Run via cron every 5 minutes:
*/5 * * * * /usr/local/bin/ddns-update.sh > /dev/null 2>&1
- Rate-limit the updates. If the IP genuinely changes every five minutes, the customer’s ISP is unstable — but if a misconfigured router is calling the update endpoint every second, you’ll hit the cPanel host’s rate limiter. Build in a “only update if changed” check.
- Monitor for token compromise. API tokens don’t expire by default; revoke and rotate quarterly. If the customer’s home device is exposed (a router with default credentials, an old NAS without security updates), the token is exposed too.
- Use a separate token for the dynamic DNS client. Don’t share the operator’s master API token. If the dynamic client is compromised, you can revoke only its token without disrupting other API consumers.
For multiple dynamic records, use one token but loop over names in the same script. For many customers, build a small web endpoint on the cPanel host (a custom PHP or Node.js handler) that accepts <token, name, ip> and updates — that’s a hosted dynamic DNS service of your own, served from the cPanel infrastructure.
Stack Harbor sets up dynamic DNS for customer remote-access use cases as part of deployment management.