Docs menu

DNS & Domains

Goal: Add a domain you own, point it at your landing zone, manage its records, and know what you can do when your DNS lives somewhere else.

Cloud -> DNS & Domains (under Foundation) holds the domains your workspace uses for web addresses. Each domain is one record. For a domain OpenX hosts, that record becomes an Azure DNS zone in your own landing zone and your own Azure subscription. For a domain you keep somewhere else, OpenX keeps the list of what that host should answer, and you set it there.

OpenX never buys or registers a domain. You bring one you already own, and your registrar stays yours.

This window opens as a panel: it floats at the right at first, docks anywhere, and keeps your place when you move it. See Node editors and work windows as panels.

The item is in the menu only when the workspace has a connected cloud and its private landing zone. Until then it is left out, and a request for it is answered with PRIVATE_LANDING_ZONE_REQUIRED (see Cloud).

What it creates in your cloud

  • A DNS zone for each domain OpenX hosts. It is made in your landing zone's resource group, in your subscription. Azure assigns the zone four name servers. Zones are public: private DNS zones are not offered yet.
  • Nothing, for a domain you keep by hand. OpenX writes nothing at that host.
  • Nothing, for a zone you bring that already exists until you choose to manage one of its records or move it. Connecting only adds two tags to the zone.

The rights you need

To do thisYou need
Open the window and read domains and recordsWorkspace.DNS.Read or Workspace.DNS.Manage
Add, change, move or remove a domain or a recordWorkspace.DNS.Manage

Workspace owners hold both through their main cards; anyone else needs an access configuration that confers them (see Permissions).

What it costs

Azure bills each zone it hosts every month, and each million lookups. A domain you keep by hand, and a zone you bring that Azure already holds, add nothing from OpenX. The window's Cost section reads the estimate and links Azure DNS pricing; see Workspace costs. Azure's own price page is the source for the amounts, which this page does not repeat.

What the window shows

The window is titled DNS & Domains, with the heading Your domains, in your own cloud. A strip explains the path a domain takes: Add a domain, Point your registrar here, Manage records.

The status pill reads First step (no domains yet), Waiting or Ready, and the line beside it says what is waiting: a domain saved whose zone is not made yet, domains waiting for their registrar, domains kept by hand whose records are not all set, or Your domain points here. Each domain has its own tab. A domain's state reads Not created yet, Zone created, Removal staged or Managed by hand at its host.

Add a domain

  1. Open Cloud -> DNS & Domains and the Add a domain tab.
  2. Type the Domain, for example example.com. A domain is lower-case letters, digits and hyphens in at least two parts separated by dots, with no trailing dot. A name with accents is written in its xn-- form.
  3. Answer Where is this domain's DNS? Press Find who serves it and OpenX reads who answers for the domain today. If that cannot be read, it says so and you can still choose:
    • Host it in your landing zone (Azure): OpenX makes the zone.
    • Keep it where it is; I'll set records by hand: see Keep a domain by hand.
  4. Press Add domain, then run the window's own commit. That makes the zone in Azure.

One domain is held by one record. Adding a domain the workspace already has is refused (DNS_ZONE_DUPLICATE); change the existing record instead. Once a zone exists its domain is fixed (DNS_ZONE_NAME_FIXED): to use another domain, remove this one and add the new one.

The window's provider rail lists Azure DNS as available. Amazon Route 53 and Google Cloud DNS show as Coming soon with what they will do; you can keep a domain at either by hand today.

Point your registrar here

A domain answers from its zone only after the company you bought it from lists the zone's name servers. Until then nothing has changed for your visitors.

  1. Open the domain's tab. Under Name servers, copy the four Azure assigned (Copy all four). Azure assigns them when the zone is created.
  2. Open Change your nameservers at your registrar and follow How to change name servers, which links your registrar's own steps. If OpenX cannot tell who your registrar is, it shows steps that fit any.
  3. Replace the registrar's name servers with those four. Before you do:
    • Copy the records your domain has today (its website, email and other entries). Once your registrar points here, only the records in this zone answer.
    • If DNSSEC is on at your current DNS provider, turn it off there first, or the domain can stop answering while the name servers change.
  4. Press Check now. It usually takes less than an hour and can take up to 48 hours.

OpenX reads where your domain points each time it reads the zone. Nothing stores the answer, and a saved zone is never proof that the domain is live.

The tab saysIt means
Not checked yetPress Check now to read where the domain points.
Waiting for your registrarNothing has changed at your registrar yet.
Partly doneSome of the four name servers are set, not all; it says how many and what is still old.
ConnectedYour registrar points here and Azure answers. Some places may still see the old answer for a while.
SpreadingConnected, while some resolvers still remember the old answer; it clears within 48 hours.
Could not checkA lookup failed. Try Check now in a minute.

The number on the menu item counts domains newly connected since this browser last opened the window, added to the proposals waiting for you.

Manage records

Once a zone exists, its tab lists the record sets. Each is marked managed here or not managed here. A set that is in the zone in Azure but not yet in OpenX is not managed here; press Manage here (or Manage all) to bring it in. Until you do, a change to it is refused (DNS_RECORD_UNMANAGED). A set that another part of OpenX needs is marked owned by that part, and is locked: change it there.

A set is keyed by name and type, for example www/CNAME, and @ is the domain itself.

  • Types: A, AAAA, CNAME, MX, TXT, SRV, CAA and NS. DNSSEC and other types are not managed yet.
  • Names: @, or a lower-case relative name such as www or _dmarc. A * is allowed only as the first label.
  • TTL: whole seconds from 1 to 2147483647; 3600 is common.
  • Values: written as a zone file writes them: A 203.0.113.10, MX 10 mail.example.com, SRV 10 5 5060 sip.example.com, CAA 0 issue "letsencrypt.org". A set holds at most 20 values; a CNAME holds one.
  • Rules: a CNAME cannot sit at @ and must be the only record at its name. An NS record delegates a subdomain and cannot sit at @ or be a wildcard.
  • Aliases: an A, AAAA or CNAME can point at an Azure resource instead of holding values. Azure allows 50 aliases per resource.

While the domain answers from this zone, the window says so before you change @, an MX or a CAA, or remove a set, because that changes live traffic.

Bring a zone you have

If a zone for the domain already exists elsewhere in your Azure, open Bring a zone you have. It lists the Azure DNS zones your cloud connection can see, and for each whether it can be connected. Check what the cloud connection may do there first; a zone connected to another workspace cannot be connected here.

  • Connect uses the zone where it is. OpenX tags it for this workspace and changes nothing else until you manage a record. OpenX never creates, moves or deletes a connected zone on its own.
  • Move into my landing zone moves it into your landing zone after the window shows what the move changes and you confirm. Only a person confirms a move.
  • Copy records in from your current DNS provider reads a zone file you paste, or scans common names, and saves the records it can read. Lines it skips or cannot import are listed with why.

Keep a domain by hand

A domain you keep at its own DNS host (GoDaddy, Amazon Route 53, Google Cloud DNS or somewhere else) is marked Managed by hand at that host. OpenX writes nothing there. Its tab, Set these records at the host, lists each record to add: name, type, value and TTL, with a state for each (set, missing, set to something else, still spreading, or could not be read). Press Check now after adding them; the state comes from that read, never from what is saved. The tab links the host's own help for adding records.

Where your DNS host supports Domain Connect and has accepted the setup, a record that another part of OpenX needs shows a button, Set up the name at the host for me. It opens your host's own page; approve the change there, then press Check now. Not every host offers it, and OpenX cannot press it for you.

Move to another DNS host

Move this domain moves a domain between hosts, for example from your landing zone to a host you keep by hand, or the other way. Every record the domain answers moves with it, so first bring any record that is not managed here under management (DNS_MOVE_HOST_UNGATHERED otherwise).

  1. Pick where it goes and read what the move does, then Start the move.
  2. To an Azure zone, Deploy creates the zone and writes every record; nothing changes for your visitors yet. To a host by hand, add every record there and give that host's name servers (Save name servers).
  3. Press Check now: the new host must answer every record before you switch.
  4. Change the name servers at your registrar yourself. OpenX checks it live.
  5. When the domain answers from the new host, Finish the move. Deploy then makes the new host the domain's host. Stop the move ends it early and lets go of a zone made for it.

Only a person confirms, finishes or stops a move.

Names under a domain

A domain can hold claims: a part of OpenX holds a name under it, and OpenX works out the records the claim needs; you never type them. A claim is proposed in the same proposal as the part that holds it, so you accept both at once. The claim's rows in the domain's tab say which part owns them, and a Used by list names who holds each name. No part of OpenX makes claims yet; see Limits and not built yet.

  • A name that traffic points at is held by one claim. A second claim for it is refused (DNS_NAME_TAKEN).
  • A claim whose name is outside the domain, or whose records would break a rule beside your other records, is refused.
  • When the part that holds a name is removed, its records stay in the zone until you next run the DNS & Domains window. The main Deploy sends no DNS zones and leaves them as they are (see Deploy).
  • A part that offers "Use a domain from DNS & Domains" lists a domain OpenX hosts only once it answers from its zone in Azure (its registrar already points here). It lists a domain kept by hand only once a live read has shown where that domain stands. Any other is shown as Not offered yet, with why.

Remove a domain

Removing a domain stages the removal (Removal staged); see Removals. Before you confirm, the removal says what it does: anything that uses the domain stops resolving unless your registrar points elsewhere. A copy of the zone's settings and records is kept first in dns-archive/ in your landing zone's storage account, and the zone is then removed. A domain whose zone was never created changes nothing outside OpenX.

What an AI can do with it

An agent reads domains with get_workspace and retrieve_inventory, and changes them by proposal; a person accepts in this window with Accept proposal and Deploy, which records the domain and then starts the window's own commit. There is no API route that reads or changes DNS directly.

Accepting a proposal is not the domain being live. For a zone OpenX makes, retrieve_inventory answers the zone's name servers and Delegation.State (waiting, partial, connected, spreading, spread or unknown); the domain answers from the zone only once that reads connected or later. For a domain by hand it answers each record's state.

An agent may propose a move, never confirm it, and may not set what Azure writes: the zone's resource, name servers, creation time and record limit. Leave them out; Deploy fills them in. Refusals carry a code that says what to do next, for example DNS_ZONE_NAME_INVALID, DNS_PROVIDER_COMING_SOON, DNS_HOSTING_INVALID, DNS_MOVE_CONFIRM_PERSON_ONLY and the DNS_RECORD_... family.

Limits and not built yet

  • Public zones only. Private DNS zones are planned, not built.
  • Amazon Route 53 and Google Cloud DNS are Coming soon as places OpenX hosts a domain. Keep a domain at either by hand today.
  • OpenX holds no GoDaddy key. A GoDaddy domain is kept by hand: its records are set at GoDaddy.
  • Domain Connect needs Fathym's own signing key and return page to be set up. Until they are, the Set up ... for me button can be absent for every host. Open: who sets these up (DNS and Domains track, row 38.13.12).
  • DNSSEC is not managed.
  • No part of OpenX claims a name yet. Hosted apps (custom domains, not started), workbenches, email sender domains and sign-in pages are meant to hold names under your domains and to offer "Use a domain from DNS & Domains". None does today. The claim rules above are built, so a claim can be proposed on a domain record, but nothing in OpenX asks for one for you.
  • This is built and not yet walked end to end. Treat a first domain as a trial and press Check now before you tell anyone the domain is live.

Troubleshooting

  • DNS & Domains is missing from the menu: the workspace has no connected cloud or no landing zone yet (see Landing Zone), or you hold neither DNS right.
  • The domain does not answer: read the tab's delegation state. Waiting for your registrar or Partly done means the name servers are not all set yet. Records that were at your old DNS provider are not here unless you copied them.
  • A record is refused: each refusal names the rule and the fix. A CNAME alone at its name and not at @ is the common one.
  • The zone is at its record limit (DNS_ZONE_TOO_MANY_RECORD_SETS): remove sets you no longer need.

On fathym.com: OpenX →

On this page