HarborDNS

Documentation

Everything you need to set up a zone, migrate a live domain safely, manage records, and automate changes.

Create account

Getting started

A zone is the set of DNS records for one domain, such as example.com. HarborDNS is the authoritative source for the zones you host here: it answers DNS questions about your domain for the whole internet. You keep your domain at its current registrar and point it at HarborDNS.

1. Create or import a zone

From Zones → Create zone, enter the domain you want HarborDNS to serve. New zones start with the records every domain needs to function. If you already run DNS elsewhere, open the zone and paste or upload a standard BIND-style zone file to bring your existing records with you. An import replaces the editable record set, so review the file before you submit it.

2. Add and review records

Use the zone page to add, edit, and remove records. Every change is validated — names, targets, and values are checked before they are saved — so a typo is caught before it can affect resolution. Choose a TTL that matches how quickly you need future edits to become visible (see TTL and propagation below).

3. Delegate at your registrar

Each zone is assigned a set of nameservers, shown in the Delegation panel. To hand DNS to HarborDNS, sign in to your registrar (where you bought or renew the domain) and replace the domain's nameservers with the ones listed for your zone. This step — not any record edit — is what tells the world to ask HarborDNS.

4. Confirm the change

After you update nameservers, confirm the delegation and a few records with a direct query (see Verifying and troubleshooting). Resolvers around the world cache the old nameservers until their TTL expires, so give the change time and keep your previous provider in place until HarborDNS is answering correctly.

Migrating a live domain without downtime

Moving production DNS is safe if you verify before you switch. The goal is that HarborDNS already returns the correct answers before any resolver is told to use it.

  1. Lower TTLs first.A day or two ahead, drop the TTLs on your current provider (for example to 300 seconds). Resolvers then forget old answers quickly, so the cut-over is fast and reversible.
  2. Recreate every record here.Import your existing zone file or add records by hand. Match names, types, values, and priorities exactly — including MX, SPF/DKIM/DMARC (TXT), and any verification records.
  3. Verify against HarborDNS directly.Query the assigned nameservers by name (see below) and compare each answer to your current provider before touching delegation.
  4. Update nameservers at the registrar.Replace the domain's nameservers with the HarborDNS set. Leave the old provider's zone intact for now.
  5. Watch, then raise TTLs.Once queries are consistently served by HarborDNS, raise TTLs back to normal values and retire the old zone.

Record types

HarborDNS manages the common authoritative record types. Here is when to reach for each one.

A and AAAA — addresses

Point a name at an IPv4 address (A) or IPv6 address (AAAA). Use the name @ for the domain itself (the apex) and a label such as www or api for a subdomain. Add both an A and an AAAA record when your host has both address families.

@     A      192.0.2.10
www   A      192.0.2.10
@     AAAA   2001:db8::10

CNAME — aliases

A CNAME makes one name an alias of another, so it always resolves to wherever the target points. Two rules matter: a name with a CNAME cannot have any other records, and you cannot put a CNAME on the apex (@) because the apex must also carry NS and SOA data. Use A/AAAA at the apex and reserve CNAME for subdomains such as www or a vendor-provided hostname.

www    CNAME   app.example.com.
shop   CNAME   shops.myvendor.net.

MX — mail routing

An MX record names the mail server that accepts email for your domain, with a priority (lower is preferred). The target must be a hostname with an A/AAAA record, never an IP address and never a CNAME.

@   MX   10   mail.example.com.
@   MX   20   backup-mail.example.com.

TXT — verification and email policy

A TXT record holds free-form text. It is how you prove domain ownership to third parties and how you declare email-authentication policy (SPF, DKIM, and DMARC — see email deliverability). A name can hold several TXT records at once.

@              TXT   "v=spf1 include:_spf.google.com -all"
_dmarc         TXT   "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"

CAA — certificate authority policy

A CAA record lists which certificate authorities are allowed to issue TLS certificates for your domain — a low-effort guardrail against mis-issuance.

@   CAA   0 issue "letsencrypt.org"

SRV — service discovery

An SRV record advertises the host and port for a specific service (SIP, XMPP, and others), with priority and weight for selection and load sharing.

_sip._tcp   SRV   10 5 5060 sip.example.com.

NS — delegating a subdomain

Add NS records to hand a subdomain (for example internal.example.com) to a different set of nameservers. The nameservers HarborDNS assigns for the whole zone are managed for you and shown in the Delegation panel.

TTL and propagation

The TTL (time to live) tells resolvers how many seconds they may cache an answer before asking again. It is the single biggest factor in how fast a change is seen:

  • Records that change often (a failover target, a deploy that swaps IPs): 60–300 seconds.
  • Stable records (a fixed apex address, MX, SPF): 3600 seconds or more.

When you save an edit, HarborDNS starts serving the new answer right away. What takes time is the cache: a resolver that already has the old answer keeps returning it until the old TTL runs out. Lowering a record's TTL before a planned change is the standard way to make that change fast.

Email deliverability (SPF, DKIM, DMARC)

Three TXT-based standards decide whether your mail reaches inboxes. Set all three:

In most cases your email provider (for example Google Workspace, Microsoft 365, or a transactional sender) supplies the exact record values to use — check their setup guide or admin console. Your job here is to add those values as TXT records on the zone; the notes below explain what each one is for.

  • SPF — one TXT record at the apex listing the servers allowed to send as your domain. Use exactly one SPF record and end it with -all (hard fail) or ~all (soft fail).
  • DKIM — a TXT record at a selector name (for example selector1._domainkey) holding the public key your mail provider gives you, so receivers can verify a message's signature.
  • DMARC — a TXT record at _dmarc that tells receivers what to do when SPF or DKIM fails and where to send reports. Start at p=none to observe, then move to quarantine or reject.

DNSSEC

DNSSEC adds cryptographic signatures to your zone so resolvers can detect tampered or spoofed answers. HarborDNS runs managed DNSSEC: enable it from a zone's DNSSEC panel and HarborDNS generates the keys, signs the zone, and keeps the signatures current. To complete the chain of trust, copy the DS record shown after activation into your domain's settings at the registrar. Leave DNSSEC off until you are ready to add that DS record — a signed zone without a matching DS at the registrar can make the domain fail to resolve.

Zone import and export

Import a standard BIND-style zone file to recreate a zone quickly; it replaces the editable records in one step, which is faster and less error-prone than adding many records by hand. The apex nameserver records and the SOA are managed by HarborDNS and are not overwritten. Export at any time to download the current records as a portable zone file — useful for backups, reviews, and moving between environments.

Verifying and troubleshooting

Query the HarborDNS nameservers directly so you see the authoritative answer, not a cached one. With dig (macOS/Linux) point at a nameserver from your Delegation panel:

# Ask HarborDNS directly for a record
dig @ns1.harbordns.net example.com A +norecurse

# Check delegation as the internet sees it
dig example.com NS +short

# Inspect mail and policy records
dig example.com MX +short
dig example.com TXT +short

Common things to check:

  • Still seeing the old answer? A resolver is serving a cached record; wait for the previous TTL to expire or query the HarborDNS nameservers directly.
  • Delegation not taking effect? Confirm the nameservers at your registrar exactly match the Delegation panel, including trailing dots.
  • A subdomain won't resolve? Check for a stray CNAME sharing a name with other records — a CNAME must stand alone.

Automating with the API

Plans with API access can create scoped tokens from Settings. Use a token to read your account, create or remove zones, import and export records, and apply an atomic batch of record changes from CI/CD or an internal tool. Batches accept an idempotency key so a retried request is applied exactly once. See the API documentation for authentication, scopes, and request examples.

Billing

The Billing page shows your plan, how many zones and records you use against it, and opens the Stripe portal for invoices and payment details. Plans are priced by zones and records; there are no per-query charges.