Vanity nameservers

By default, every DNS zone hosted at OpusDNS answers from the shared OpusDNS nameservers (ns1.opusdns.com / ns2.opusdns.net). Vanity nameservers let you present your zones under nameserver names on your own domain — for example ns1.example.com and ns2.example.com — so your brand appears in the delegation and NS records. OpusDNS still answers the DNS from its anycast network; only the names change.

A group of branded nameservers is a vanity nameserver set. A set has:

• a name for your own reference;
• a parent domain — the domain the nameserver hostnames live under (e.g. example.com for ns1.example.com);
• two or more nameserver hostnames (e.g. ns1.example.com, ns2.example.com);
• an SOA responsible name (soa_rname) — the contact stamped into the SOA record of every zone the set brands, in DNS format (e.g. hostmaster.example.com).

Once a set is active, you can point your DNS zones at it: new zones can use it automatically (if it is your organization default), or any zone — new or existing — can be branded with a specific set explicitly.

How it works: where is the parent domain registered?

How much you have to do yourself depends on where the parent domain is registered. The API behaves the same either way; the difference is the setup you are responsible for.

Create a vanity nameserver set

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Example brand nameservers",
    "parent_domain_name": "example.com",
    "soa_rname": "hostmaster.example.com",
    "hostnames": ["ns1.example.com", "ns2.example.com"]
  }'

Request fields

The call returns 202 Accepted with the created set. The set starts in status provisioning and activates asynchronously (see What to expect after creating).

{
  "set_id": "vns_01kvn2kr1qep2bd7e60tt65fxn",
  "organization_id": "organization_01kvn2kr34e9ts01z1330tkvfx",
  "name": "Example brand nameservers",
  "parent_domain_name": "example.com",
  "soa_rname": "hostmaster.example.com",
  "status": "provisioning",
  "is_default": false,
  "nameservers": [
    { "hostname": "ns1.example.com", "position": 0 },
    { "hostname": "ns2.example.com", "position": 1 }
  ]
}

The nameserver in position 0 becomes the primary (SOA MNAME) for zones branded with the set.

What to expect after creating

Activation happens asynchronously — the 202 response means the request was accepted, not that the set is live. OpusDNS sets up the zone, confirms the nameservers are correctly in place, and only then moves the set to active. A set will not activate until its prerequisites actually check out, and what is required depends on where the parent domain is registered:

• Parent domain managed by OpusDNS — provisioning and glue registration are automatic and usually complete within a minute or two. Registry steps can take longer to settle and are retried for a period to allow for registry propagation.
• Parent domain registered elsewhere — OpusDNS repeatedly checks that the nameserver hostnames resolve to the assigned anycast addresses, for a limited window. Publish your A / AAAA records before creating the set, or shortly after, so the check succeeds inside that window.

A set has one of the following statuses:

The anycast addresses to publish

If your parent domain is registered elsewhere, point every nameserver hostname in the set at OpusDNS's shared anycast pool. Publish all of the following records for each hostname (e.g. for both ns1.example.com and ns2.example.com), and use the same addresses when you register glue at your registrar:

So each nameserver hostname resolves to both IPv4 addresses (two A records) and both IPv6 addresses (two AAAA records).

Use a set for your DNS zones

There are three ways to make a zone use a vanity NS set.

Set it as your organization default

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/$SET_ID/default" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

After this, new zones created with no explicit set are automatically branded with it.

• When the first set in your organization becomes active, it automatically becomes the default.
• With multiple active sets, only one is the default at a time; selecting a new default changes which set brands newly created zones, but does not change existing zones.
• Changing the default only affects zones created after the change. Each zone remembers the set it was branded with.

To stop a set from being applied to new zones while leaving existing zones working, make sure it is not the default — either choose a different default, or clear the default entirely:

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/default" \
  --request DELETE \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

After clearing, new zones fall back to the standard OpusDNS nameservers. Existing zones keep the branding they already have.

Brand a new zone explicitly

When creating a zone, include vanity_nameserver_set_id with the set_id. This works for any active set, default or not:

curl "$OPUSDNS_API_BASE/v1/dns" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "example.net",
    "vanity_nameserver_set_id": "vns_01kvn2kr1qep2bd7e60tt65fxn"
  }'

Re-brand or unbrand an existing zone

A pre-existing zone can be re-stamped with a different set — or reset back to the OpusDNS defaults — at any time, without recreating it:

curl "$OPUSDNS_API_BASE/v1/dns/example.net/vanity-set" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "vanity_nameserver_set_id": "vns_01kvn2kr1qep2bd7e60tt65fxn"
  }'

Set vanity_nameserver_set_id to null to unbrand the zone and restamp its apex back to the standard OpusDNS nameservers. This rewrites the zone's apex NS records and SOA at the DNS provider (and re-signs the zone if DNSSEC is enabled). Afterwards the zone appears in the set's zones listing.

List the zones using a set

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/$SET_ID/zones" \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

Returns the zones currently branded with the set (paginated). Useful before deleting a set, since a set in use cannot be deleted.

Check the status of a set

The /check endpoint is a read-only health report for a set. It changes nothing — it tells you what is correctly set up, what is missing, and what is optional-but-recommended. It is the quickest way to see why a set has not gone active, or why a customer's vanity nameservers "aren't working."

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/check" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "set_id": "vns_01kvn2kr1qep2bd7e60tt65fxn"
  }'

The response carries an overall summary and a list of individual checks:

{
  "set_id": "vns_01kvn2kr1qep2bd7e60tt65fxn",
  "parent_domain_name": "example.com",
  "status": "provisioning",
  "summary": {
    "state": "action_required",
    "detail": "Nameserver A/AAAA records are not yet published for ns1.example.com, ns2.example.com."
  },
  "checks": [
    {
      "id": "ns_a_records",
      "label": "Nameserver A/AAAA records",
      "status": "fail",
      "severity": "required",
      "source": "public_dns",
      "confidence": "authoritative",
      "detail": "Vanity NS hostnames are not yet resolving to the assigned anycast addresses.",
      "observed": {
        "required_records": {
          "A": ["192.174.68.145", "176.97.158.145"],
          "AAAA": ["2001:67c:1bc::145", "2001:67c:10b8::145"]
        }
      },
      "remediation": "Publish A (and AAAA) records for each nameserver hostname pointing at the addresses in required_records."
    }
  ]
}

The overall summary state

The individual checks

Each check reports a status (pass / warn / fail / info), a severity (required / recommended / optional), the observed values, and — when relevant — a remediation hint.

Retry a failed set

A failed set means activation did not complete within its window — usually because the nameserver A / AAAA records or registry glue were not in place in time. Once you have fixed what was missing, re-run activation for the same set instead of recreating it:

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/$SET_ID/retry" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

The call returns 202 Accepted; the set returns to provisioning and activation runs again, asynchronously, exactly as it did on create. Retry applies only to failed sets — calling it on a set in any other status returns 409.

Glue records

Glue records are the IP addresses attached to a nameserver at the registry/TLD level. They are needed when a nameserver lives under the same domain it serves — "in-bailiwick", e.g. using ns1.example.com to serve example.com itself — because otherwise resolving the nameserver would be circular.

• When the parent domain is registered with OpusDNS, glue is registered automatically — you do not need to do anything.
• When the parent domain is registered elsewhere, register glue (sometimes called "host records", "child hosts", or "private nameservers") at your registrar, pointing the nameserver hostnames at the anycast addresses from /check. If your domain is registered with OpusDNS but managed as a host object, see Host objects (glue records).
• Glue is only required for in-bailiwick use. If you only point other domains at your branded nameservers, glue is not strictly required — which is why the glue checks are advisory, not blocking.

Lifecycle: renewal, grace, and deletion

A vanity nameserver set is a subscription that renews annually for a fee. As long as it renews, it keeps working with no action needed. See your pricing information for the renewal figure.

If the subscription lapses

If a renewal does not go through, the set enters a 30-day grace period:

• At the start of grace, the set is suspended and automatically removed as the organization default, so it stops being applied to new zones. Zones that already use it keep working normally throughout grace.

• Restore it during grace to return it to normal:

  curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/$SET_ID/restore" \
    --request POST \
    --header "X-Api-Key: $OPUSDNS_API_KEY"
  

  bash

  A restored set comes back active, but not automatically as the default — re-select it as the default if you want it to brand new zones again. Restoring incurs a fee; see your pricing information.

• At the end of grace, if it has not been restored, OpusDNS automatically restamps every zone still using the set back to the standard OpusDNS nameservers and tears the set down. Those zones are then served by the OpusDNS nameservers again.

Deleting a set

Delete a set with DELETE /v1/vanity-nameserver-sets/{set_id}. The set must first be out of use — deletion is refused with 409 while:

• any zone still references the set — re-stamp every such zone onto a different set, or back to the OpusDNS defaults (Re-brand or unbrand a zone), first; or
• the set is the organization default and other active sets exist — choose a different default first. (Deleting your only active set is fine.)

curl "$OPUSDNS_API_BASE/v1/vanity-nameserver-sets/$SET_ID" \
  --request DELETE \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

When accepted, the call returns 202 Accepted and the set is torn down asynchronously.

API reference

An organization can have multiple active sets at once (for example, different brands), coexisting independently. Only one can be the default at a time.

Troubleshooting