Skip to content
Control Plane Labs

CNAME record

Aliases one name to another name, which is then resolved in its place.

Last updated July 27, 2026

Zone-file example

; type 5, defined in RFC 1035
www.example.com.     300   IN   CNAME   example-lb.provider.net.
docs.example.com.    300   IN   CNAME   example.github.io.

Typical uses

  • Pointing a subdomain at a provider-managed hostname such as a CDN or PaaS endpoint
  • Keeping one canonical name so an address change only needs one edit
  • Vendor domain-verification records that must resolve to a vendor-controlled name
  • ACME dns-01 delegation, where _acme-challenge is a CNAME into a validation zone

When it breaks, check

  • A CNAME cannot coexist with any other record at the same name — this breaks apex setups
  • A CNAME at the zone apex is invalid; use ALIAS/ANAME or an A record instead
  • Chained CNAMEs work but cost extra lookups; most resolvers cap the chain length
  • The target must be a name, never an IP address — a CNAME to 203.0.113.10 is malformed

What the CNAME record does

CNAME means “canonical name”: the record says the name you asked for is not the real one, and gives you the real one. The resolver then queries the target and returns both the CNAME and the target’s records in the same response. This is why a CNAME costs you an extra resolution step, and why deep chains hurt.

The rule that trips everyone up is exclusivity. Because a CNAME redirects all lookups for that name, no other record type may exist alongside it. You cannot have a CNAME and an MX on the same name, and you cannot have a CNAME at a zone apex, because the apex must carry SOA and NS records.

Zone-file and wire format

The syntax is alias TTL IN CNAME target. and the trailing dot on the target matters enormously: without it the zone origin is appended. On the wire the RDATA is a single domain name. There is no way to express “alias but only for A queries”, which is precisely the gap that ALIAS records exist to fill.

; valid: a subdomain aliased to a provider hostname
www.example.com.        300   IN   CNAME   d111abcdef8.cloudfront.net.

; INVALID: a CNAME at the apex, alongside the mandatory SOA and NS
; example.com.          300   IN   CNAME   d111abcdef8.cloudfront.net.

; INVALID: another record type sharing the alias name
; www.example.com.      300   IN   TXT     "hello"

Common uses

The best use of a CNAME is delegating control of an address you do not own. Pointing www at a CDN hostname means the CDN can move its edge addresses whenever it likes and your zone never changes. The same logic drives vendor verification records and, most usefully, ACME dns-01 delegation: CNAME _acme-challenge.example.com into a small zone that only your certificate automation can write, and you never have to give the ACME client credentials for your production zone.

Troubleshooting

Two failure signatures cover most CNAME problems. If a name resolves but mail or another record type mysteriously does not work, look for a CNAME shadowing that name — the CNAME wins and the other record is unreachable even if it is present in the zone file. If the apex of your domain will not accept the value your provider gave you, that is the apex restriction, not a provider bug.

Use dig +trace to watch the chain, and check how many hops it takes; each one is latency on a cold cache.

# see the alias and the resolved target in one answer
dig www.example.com A +noall +answer

# follow the whole delegation and alias chain from the root
dig +trace www.example.com

# confirm nothing else is defined at an aliased name
dig www.example.com ANY +noall +answer

The defining RFC

CNAME is type 5, defined in RFC 1035 §3.3.1. The exclusivity rule and the requirement that the apex hold SOA and NS records come from RFC 1034 §3.6.2, and RFC 2181 §10.1 restates the constraint in the clearest language of any of the three. ACME challenge delegation is described in RFC 8555 §8.4. Resolve an alias chain with the DNS lookup tool.

Reference and tooling

Every record type and its assigned numeric value is listed in theIANA DNS Parameters registry. To query a live zone from the browser, use theDNS lookup tool. If the record you are chasing is TLS-related, the TLS inspector andCertificate Transparency lookup are usually the next two stops.

Other record types