How to set up a CNAME record for a custom domain name

We ask customers to set up their domain names using CNAMEs rather than the possibly more familiar A record method because:

If we need to upgrade or downgrade your service we can do this without your tech team having to be involved.
It allows us to meet our target service level availability eg up-time as defined in Delib's Service Level Agreement (SLA).

This guide covers the essentials of what needs to happen:

I am the main site-admin, what do I need to do?
I am the technical person, what do I need to do?

It also contains further explanations if you would like more detail:

Why do you use CNAMEs instead of A records?
How does a CNAME lookup work?
Why can't any other record share the same name?
How do I set-up a CNAME on my DNS server?
How do I check that the CNAME has been set up correctly?

I am the main site-admin, what do I need to do?

You only need to organise a CNAME record to be set up if you would like your site to appear at a subdomain of a domain you already own. For example, if you own example.gov.uk and would like your site to appear at haveyoursay.example.gov.uk.

You do not need this guide if you are:

Purchasing Citizen Space and choosing a URL like example.citizenspace.com.
Purchasing Dialogue and choosing a URL like example.dialogue-app.com.
Purchasing Simulator and choosing a URL like example.budgetsimulator.com.

See the set-up requirements articles for Citizen Space, Dialogue or Simulator for more on what kinds of URLs you can have for your sites.

What do I need to do?

If you need to set up a CNAME record in order to have your site on a custom domain you will need to do the following. Your customer success manager will be happy to answer any questions you have.

You need to find the person or team who controls your organisation's domain name. Because you own the domain and not us, we can't do this for you.
You need to ask your technical people to create the CNAME record. You will need to pass on the value we give to you for them to do this. This will usually look like "cs-example.delib.net.", "da-example.delib.net. or "sim-example.delib.net." for example. The dot on the end is important and must not be omitted.
You need to instruct your technical team to create the CNAME record as soon as possible. The record can be created as soon as you have decided on your URL and must be created in order for the site to be visible.

I am the technical person, what do I need to do?

Receive the value from your internal contact, which we provide to them. This will usually look like 'cs-example.delib.net.', 'da-example.delib.net.' or 'sim-example.delib.net.' for example. The dot on the end is important and must not be omitted.
Create a CNAME record pairing your chosen URL with the CNAME value we give you. We have more information on why you should use a CNAME instead of an A record.
There must not be any other records of any type which have the same name as the CNAME record. We have more information on why this is the case.
Test that the CNAME has been set up correctly.

Why do you use CNAMEs instead of an A record?

This approach to DNS management helps us to provide you with the best possible service and the most service up-time, as defined with our SLA. This approach removes the need for us to liaise with you if your IP address needs to change, which could be at unsociable hours.

Most commonly your IP address will change because we're undertaking standard maintenance or upgrading your site. Occasionally we may also move your site to provide better resilience if we detect a hardware failure, DC outages or network outages for example.

If you create an A record instead of a CNAME record, we will not be able to support your site's SLA because we will not be able to change the site's IP address without your involvement. From past experience we have found that the fewer the number of teams involved in this type of activity, the faster it can be done with fewer errors. For this reason, we do not support custom domains with A records.

How does a CNAME lookup work?

A CNAME is like a forwarding address for DNS. You use a CNAME record so that your site's name can point to the server for your site without you needing to alter a DNS record if the server's IP address has to be changed. There is no additional difficulty to creating or serving a CNAME record instead of an A record.

You must not have any other DNS record(s) with the same name as your CNAME record. If you do you may see extremely complicated failure modes where end-users in different physical locations see different DNS results depending on:

Timing
Their physical location
The specific chain of caching DNS servers between them and the authoritative name servers
The order in which different DNS queries are made by different parties.

RFC 1034 specifically recommends against having any other record with the same name as a CNAME record. For this reason, we do not support custom domains with any record other than the CNAME record at the same name.

How do I set-up a CNAME on my DNS server?

If you have an online control panel for your domain then it will normally be a web application that lets you administer DNS records for your domain. The appearance and behaviour of this application will depend on your DNS provider.

If you run your own DNS servers, you will be using software like BIND or Windows Server.

If you use BIND, add a record to your domain's zone file and then reload the zone. On Ubuntu for instance, the zone file will usually be in /etc/bind/db.example.com . The new line in the zone file should look like:

consultations.example.com. 3600 IN CNAME cs-example.delib.net.

If you use Windows Server, see Microsoft's documentation and instructions for adding a CNAME record to Windows Server 2008.

If your organisation's local network or intranet has a DNS server that serves records for client.gov.uk, you will need to add an identical record to your local DNS server so that your site will be viewable from within your network.

If this is not set up correctly, you may find that your site will be accessible via the public internet but not from your office network. The easiest way to test whether your site is accessible via the public internet is to browse to your site on a 3G connection on a smartphone like an iPhone or Android phone. If your site is viewable via the public internet but not from computers on your office network then you most likely have a local DNS server that needs to have this record set up.

How do I check that the CNAME has been set up correctly?

On Windows

Open a Command Prompt by clicking the Start menu, typing "cmd.exe" and pressing Enter. A black window should appear with a prompt.

You should now run the following command, replacing 'haveyoursay.example.com' with your actual domain name:

nslookup -type=CNAME haveyoursay.example.com

and you should see a reply like:

Server: UnKnown

Address: 192.168.1.1

Non-authoritative answer:

haveyoursay.example.com canonical name = cs-example.delib.net

The first two lines, 'Server:' and 'Address:"'may vary, they just depend on your local router or DNS caching server. The line under 'Non-authoritative answer:' giving the canonical name is the one that matters and has to match the value (like 'cs-example.delib.net') that we gave you.

If you accidentally forgot to put a dot on the end of your CNAME record's value when you needed to, you should expect to instead get a reply like:

Server: UnKnown

Address: 192.168.1.1

Non-authoritative answer:

haveyoursay.example.com canonical name = cs-example.delib.net.example.com

This indicates that the trailing dot was missed and the name is not set up correctly.

On Mac OS X or Linux

Open a Terminal. On Mac OS X, click on the magnifying glass icon at the top-right of your screen (or press Apple + Space together) to bring up the search tool, then type 'Terminal' and press Enter. On Linux with Gnome, click the 'Activities"'in the corner of your screen, type 'Terminal' and press Enter.