DNS records: what each type does and how to set them in BWEZE DNS

A, AAAA, CNAME, MX, TXT, SRV and NS: what each record is for, why the apex cannot be a CNAME, how TTLs work, and who can edit records in BWEZE DNS.

A DNS zone is a list of records, each with a name, a type, a TTL and a value. Resolvers ask for them by name and type. This guide covers the types BWEZE DNS accepts, the rules that catch people out, and how to set them.

BWEZE runs authoritative DNS on ns1.bweze.com and ns2.bweze.com. Those nameservers do not answer on the public internet yet. You can create zones and records now, but don’t point a live domain’s nameservers at them until the DNS docs drop their notice. To serve a project on a domain you own today, connect it with records at your current DNS provider.

The record types

BWEZE DNS accepts seven types:

Type What it holds Typical use
A A host’s IPv4 address Point a name at a server
AAAA A single IPv6 address The same, over IPv6
CNAME The canonical name for an alias Make www an alias of another name
MX A preference and a mail exchange host Where mail for the domain is delivered
TXT Text strings whose meaning depends on the name SPF, DKIM, DMARC and ownership checks
SRV Priority, weight, port and target host of a service Services found by _service._proto names
NS An authoritative name server Delegate a subdomain to other nameservers

In zone-file form they look like this (the SRV line uses the fictional service from RFC 2782):

@               A      203.0.113.10
@               AAAA   2001:db8::10
www             CNAME  app.example.net.
@               MX     10 mx1.mailhost.com.
@               TXT    "v=spf1 mx -all"
_foobar._tcp    SRV    0 1 9 old-slow-box.example.com.
lab             NS     ns1.otherhost.net.
  • MX. With several mail hosts, the lower preference value is preferred (RFC 1035).
  • TXT. The text means what the name it sits on says: an SPF policy at the apex, a DMARC policy at _dmarc. SPF, DKIM and DMARC covers those three.
  • SRV. Clients try the lowest priority first, and weight shares the load among targets of equal priority (RFC 2782).
  • NS. An NS record says the named host is authoritative for a zone starting at that name (RFC 1035), which is how a subdomain is handed to other nameservers.

CNAME rules

A CNAME makes its name an alias for another name. Three rules follow from the standards:

  1. Nothing else at that name. RFC 1034 says that if a CNAME is present at a name, no other data should be, and RFC 1912 says a CNAME is not allowed to coexist with any other data. That includes MX and TXT records.
  2. No CNAME at the apex. The top of a zone carries its NS records and its SOA record (RFC 1034), so a CNAME there breaks rule 1. RFC 1912 describes the result: the NS records are ignored, and every host in the domain with them. At the apex, use A and AAAA records.
  3. MX, NS and SRV point at real hosts. The name in an NS or MX record must not be an alias (RFC 2181), and neither may an SRV target (RFC 2782). Point them at names with address records.

TTL

The TTL is how long, in seconds, a resolver may cache a record (RFC 1035). In BWEZE DNS it runs from 60 to 86,400 seconds, one day, and defaults to 300. A short TTL lets a change reach everyone sooner. Before you move a record, lower its TTL and wait for the old TTL to pass.

Set records in BWEZE DNS

Records live in a zone, so add the zone first:

curl -X POST https://api.bweze.com/v1/dns/zones \
  -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
  -d '{ "zone": "example.com" }'

BWEZE manages records as record sets: every record with one name and one type. Setting a record set replaces all of its records at once:

curl -X POST https://api.bweze.com/v1/dns/zones/example.com/records \
  -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
  -d '{ "name": "@", "type": "MX", "ttl": 3600, "records": ["10 mx1.mailhost.com.", "20 mx2.mailhost.com."] }'
Field Value
name The name in the zone; @ is the zone’s apex
type A, AAAA, CNAME, TXT, MX, SRV or NS
ttl Seconds, 60 to 86,400; default 300
records The values, one string per record

Editing is the same call. To add a third mail host to the set above, send all three values; to drop one, send the set without it. To delete a whole set, call DELETE /v1/dns/zones/{zone}/records with a body of { "name": "...", "type": "..." }.

A name, type, TTL or value BWEZE does not accept fails with 400 invalid_record or invalid_dns_input. 503 dns_unavailable means the nameservers could not be reached; try again later.

The dashboard’s DNS page does the same, and exports a zone as a BIND zone file.

Who can change records

Every workspace role can see DNS. Only owners and admins can change it.

An API token needs a permission for each action:

Action Permission
List and read zones dns:read
Add a zone dns:create (not for tokens limited to some zones)
Set records dns:update
Delete records or a zone dns:delete

The DNS editor token template grants all four. A token limited to some zones sees and changes only those, and a token never does more than its owner’s role allows.

Full reference

Zones, record sets and permissions are in the DNS docs. Every DNS endpoint is in the API reference, and token scopes in API tokens.

Sources

Copy linkMarkdown

/ More guides

Build the next thing, from Rwanda.

Get started