Configure External DNS

External DNS allows you to host your Site on CloudCannon but manage your DNS Records elsewhere. You can set up External DNS through a different provider (e.g., Cloudflare) or your own servers. You add the records CloudCannon needs at that provider, and CloudCannon checks that they point at CloudCannon.

Before we begin, this article assumes you have connected a Custom Domain to your Organization.

Enable External DNS#

You can choose External DNS when you connect a Custom Domain, or switch an existing domain to External DNS on the Details section of the Domain Settings tab.

Records in the CloudCannon DNS zone for your domain stop working once you switch, so add them at your new provider before you change your nameservers.

To switch to External DNS:

1. Log in to CloudCannon.
2. Select the Organization your Custom Domain is connected to.
3. Click the Custom Domains link in the App Sidebar. CloudCannon will open the Domains Browser.
4. Select the domain for which you want to configure DNS by clicking the Card for the domain. CloudCannon will open the Summary tab of the Domain page.
5. Click the Domain Settings tab. CloudCannon will open the Details section.
6. Under DNS Provider, select the External DNS option. CloudCannon will label the provider you are switching from (current), and warn that records in its DNS zone stop being used once you switch.
7. Click the Switch to External DNS button.

CloudCannon will switch your domain to External DNS. For the next 48 hours, each Subdomain that a check found not pointing at CloudCannon shows Checking, and a Subdomain CloudCannon hasn't checked yet shows Not checked yet. CloudCannon keeps checking the records daily.

The records each Subdomain needs#

Each Subdomain needs its own records at your DNS Provider. The records depend on how visitors reach the Subdomain, through CloudCannon Hosting, Cloudflare Proxy, or Single Origin:

• CloudCannon Hosting — A CNAME Record pointing at sites.cloudcannon.com. Your Base Domain (e.g., example.com) needs two A Records instead, pointing at 52.8.178.132 and 184.169.135.34.
• Cloudflare Proxy — A CNAME Record pointing at orange-cloud.cloudcannon.com, proxied in your Cloudflare zone.
• Single Origin — A CNAME Record pointing at orange-cloud.cloudcannon.com. Your Base Domain needs two A Records instead, pointing at 52.8.178.132 and 184.169.135.34.

When you add your Base Domain as a new Subdomain that serves a Site, CloudCannon also adds www.example.com as a redirect to it, unless www.example.com already exists, and www.example.com needs its own CNAME Record. Adding example.com on CloudCannon Hosting therefore shows three records: two A Records for example.com and a CNAME Record for www.example.com. In the same way, adding www.example.com as a Subdomain that serves a Site also adds example.com as a redirect to it, unless example.com already exists.

Your Base Domain also has a wildcard SSL Certificate, which gives subdomains you haven't set up yet a certificate, so their visitors reach your Fallback Redirect over HTTPS. On External DNS, this certificate is validated with TXT Records you add at your DNS Provider, and it needs new TXT Records each time it renews, unless you add a CNAME Record named _acme-challenge.[Base Domain] once. With that CNAME Record, the certificate renews by itself.

Follow the setup guide#

When you connect a domain on External DNS or add a Subdomain, a setup guide at the top of the Summary tab of your Domain page shows how far along setup is. It covers the Subdomains that don't point at CloudCannon yet, or are still waiting for their certificate, and that you added in the last seven days or marked as updated. The guide is headed A Subdomain requires DNS Record updates or Multiple Subdomains require DNS Record updates, names those Subdomains, shows three steps (Add the DNS Records, DNS Records match, and Your Subdomains go live, or the singular forms for one record or one Subdomain), and has an Open the DNS tab button that opens the DNS tab, where you add the records. If you don't have the base-domain:settings:dns:read permission, the button is Open the Subdomain page instead, or Open the Subdomains tab, which opens the Subdomains tab filtered to the Subdomains that need attention, when more than one is waiting.

The Custom Domain page under Site Settings shows the same guide for the Subdomain that hosts your Site, and notes that the Site stays on its Testing Domain until the Subdomain goes live. On that page, the Scroll to DNS Records button scrolls to the DNS section, which lists the record the Subdomain needs. The DNS section only appears if you have the base-domain:settings:details:write permission.

Add the records#

The Required records table on the DNS tab lists the record each Subdomain needs in its Record column, followed by any records CloudCannon found at that name. For a TXT Record, the Record column shows the record's Name below its value, with its own Copy button. If the Subdomain uses Cloudflare Proxy, add the record in your Cloudflare zone with the proxy status set to Proxied.

Clicking the I've updated it button requires the base-domain:settings:details:write permission.

To add the records:

1. Log in to CloudCannon.
2. Select the Organization your Custom Domain is connected to.
3. Click the Custom Domains link in the App Sidebar. CloudCannon will open the Domains Browser.
4. Select the domain for which you want to add records by clicking the Card for the domain. CloudCannon will open the Summary tab of the Domain page.
5. Click the DNS tab. CloudCannon will open the DNS tab, with the Required records table.
6. Log in to your third-party DNS Provider.
7. Click the Copy icon next to a needed record in the Record column. CloudCannon will copy the value.
8. Add the record at your DNS Provider with the value you copied. Repeat steps 7 and 8 for each needed record in the Record column.
9. Remove any other A, AAAA, or CNAME Records with the same name at your DNS Provider.
10. Click the I've updated it button below the name of each Subdomain whose records you added.

CloudCannon will check every hour for up to seven days after you click the I've updated it button, and hide the button for those seven days. For the first 48 hours, the Status column shows Checking. After that, it shows the status CloudCannon found, while CloudCannon keeps checking. The setup guide and the DNS section of the Subdomain page show when you marked the records as updated. There's no need to keep the page open. Once CloudCannon finds the records and issues the SSL Certificate, it emails you that the Subdomain is live. If the Summary tab is open at the time, the setup guide shows that the Subdomain is live, with a Visit [Subdomain] button and a Dismiss button.

Whenever the wildcard SSL Certificate for your Base Domain needs validating, including when it is first issued and each time it renews, the DNS tab also lists the TXT Records for that certificate under Wildcard certificate records. For the first certificate, the heading reads Wildcard certificate records (optional): the wildcard SSL Certificate only covers subdomains you haven't set up, so the setup guide doesn't ask for these records. Add them the same way if you want them.

Below the Wildcard certificate records table, the Automatic renewal record (optional) table offers a CNAME Record instead: Add this CNAME record once and the certificate renews by itself, without TXT records. Remove any TXT records with the same name first. The record points _acme-challenge.[Base Domain] (e.g., _acme-challenge.example.com⁠) at an address ending in .dcv.cloudflare.com, which starts with your Base Domain. The DNS tab shows the exact value, with a Copy icon for the name and the value. If you add it, you don't need to add TXT Records for later renewals.

If CloudCannon still can't find a record 48 hours after you clicked the I've updated it button, the setup guide shows The DNS Record for a Subdomain does not match, The DNS Records for a Subdomain do not match, or The DNS Records for multiple Subdomains do not match, with a How can I fix this? box, and the DNS tab shows a notice for the Subdomain. Both list what usually fixes it:

• Check that the record is saved at your DNS Provider, not only entered.
• Some DNS Providers add the domain for you, so the name might need to be the subdomain part on its own.
• Remove any other A, AAAA, or CNAME Records with the same name.

Review the records on the DNS tab#

On External DNS, the DNS tab starts with the External DNS nameservers section, if you have the base-domain:settings:dns:read permission. It has a Configure External DNS link, and, if you can view the settings of your Base Domain, a change the DNS Provider link. Its table lists your Base Domain with the nameservers CloudCannon found and the status Not CloudCannon DNS. Without the base-domain:settings:dns:read permission, the tab says The Custom Domain [Base Domain] uses an external DNS Provider. and links to this article instead.

The Required records table lists each Subdomain whose record doesn't point at CloudCannon yet, with Subdomain, Record, and Status columns. The Record column shows the record each Subdomain needs, then any records CloudCannon found at that name, marked Points elsewhere if they point somewhere else or Existing otherwise. Once every Subdomain points at CloudCannon, a notice takes the place of the table, headed [Subdomain] points at CloudCannon for one Subdomain, Both subdomains point at CloudCannon for two, or All [Number] subdomains point at CloudCannon for more. Each Subdomain's status, in this table and in the DNS section of its Subdomain page, is one of:

• Configured — The Subdomain reaches CloudCannon.
• Not pointing at CloudCannon — A record for the Subdomain points somewhere else.
• No DNS Record — CloudCannon found no record for the Subdomain.
• Not checked yet — CloudCannon hasn't checked the Subdomain yet.
• Checking — In the last 48 hours, you added the Subdomain, changed its hosting, changed your DNS Provider, or marked its record as updated, and CloudCannon is still looking for the record.

For a Subdomain that isn't connected, the Subdomain column also shows the I've updated it button, with Checks hourly for a week below it. The button is hidden for seven days after you click it.

Above the table, one warning notice names each Subdomain that still isn't pointing at CloudCannon 48 hours after you marked it as updated, with what usually fixes it, and each Subdomain whose record changed after it was live.

The External DNS nameservers table and each record table on the DNS tab have a footer that says when CloudCannon last checked, with a Check now button that checks every record in the table again. The nameservers footer also says CloudCannon checks daily., and the record table footers say Check now checks every record once. The Automatic renewal record (optional) table has no footer. The footer of the External DNS nameservers table also has a View nameserver check history icon, which opens the Nameserver checks for [Base Domain] modal.

When you click a Copy icon, the icon changes to a tick and Copied! appears next to it.

The Wildcard record (optional) table shows a wildcard CNAME Record for your domain (e.g., *.example.com pointing at sites.cloudcannon.com⁠). Without a wildcard record, a subdomain you haven't added doesn't resolve. With one, its visitors reach your Fallback Redirect, or get a not found page if you haven't set one. Records you add for specific Subdomains always take priority over the wildcard.

Once you have added the wildcard record at your DNS Provider, click the I've updated it button in its row. The status changes to Checking, and CloudCannon checks for the record every hour for up to seven days by looking up a subdomain name that doesn't exist on your domain. Once CloudCannon finds the record, the status changes to Configured. CloudCannon also checks the wildcard record each time it checks your nameservers.

When the DNS tab isn't listing TXT Records for the wildcard SSL Certificate, the Wildcard certificate notice below the wildcard record shows the state of that certificate, which covers subdomains you haven't set up: Setting up, HTTPS on, or No HTTPS. While HTTPS is on, the notice shows the date by which the certificate renews, or that it renews by itself through the CNAME record you added. If your Base Domain is one of your Subdomains on CloudCannon, the notice has a View HTTPS for [Base Domain] link to its Subdomain page.

Until you add the CNAME Record that renews the wildcard SSL Certificate by itself, the Automatic renewal record (optional) table lists that record, below the Wildcard certificate notice or below the Wildcard certificate records table, with the same columns as the other record tables, a Copy icon for its name and value, and the status Optional. Once CloudCannon finds the record, the table goes away.

The DNS section of each Subdomain page shows the same record for that one Subdomain, with the same Copy icon and I've updated it button. Its footer has a View DNS check history icon, which opens the DNS checks for [Subdomain] modal, and a Check now button. The TXT Records for getting HTTPS ready before you switch DNS, or for the certificate of a Subdomain on Cloudflare Proxy, are in the HTTPS section of the Subdomain page. For your Base Domain, the TXT Records for a wildcard SSL Certificate renewal are on the DNS tab, and the DNS section links to them.

How often CloudCannon checks your records#

CloudCannon checks the records of each Subdomain daily, and every hour for up to seven days after you click the I've updated it button. Adding a Subdomain, or changing its hosting, doesn't start hourly checks, so click the I've updated it button once you have added the record.

To check a Subdomain immediately, click the Check now button in the footer of the DNS section of its Subdomain page. To check every Subdomain listed in the Required records table, click the Check now button in the footer of that table. You can check each Subdomain at most once a minute: for a minute after a check, the Check now button is disabled, with the tooltip Checked less than a minute ago. You can check again in a minute. Checking the records of Subdomains needs the base-domain:settings:details:write permission. Without it, the Check now button in a record table is disabled, with the tooltip You do not have permission to edit the Domain Settings for [Base Domain]. The Check now button in the Wildcard record (optional) table needs the base-domain:settings:dns:read permission instead, with the tooltip You do not have permission to view the DNS for [Base Domain]. If CloudCannon couldn't complete the latest check, the footer says when the check failed, and the table keeps the last known status.

Subdomain emails#

CloudCannon emails everyone who can edit the settings of your Base Domain (the base-domain:settings:details:write permission) about the DNS Record of each Subdomain.

[Subdomain] is live on CloudCannon

CloudCannon sends this email when it finds the record for a Subdomain you marked as updated and issues its SSL Certificate. The email shows the Site or redirect now live on the Subdomain, with a Visit [Subdomain] button.

[Subdomain]'s DNS Record does not point at CloudCannon

CloudCannon sends this email when it still can't find the record more than 48 hours after you clicked the I've updated it button. If you didn't click it, CloudCannon counts the 48 hours from when you added the Subdomain, or from the last time you changed its hosting or your DNS Provider, whichever is later. Changing the hosting or the DNS Provider starts the 48 hours again. CloudCannon only sends the email within seven days of that starting point, and only once for each starting point.

The email starts It has been more than 48 hours since [...], then shows the record the Subdomain needs, what CloudCannon found, and what usually fixes it, with an Open the Subdomain page for [Subdomain] button that opens the Subdomain page.

Action required: [Subdomain]'s DNS Record no longer points at CloudCannon

CloudCannon sends this email when the record of a live Subdomain stops pointing at CloudCannon. The email shows what the record points at now, with an Open the Subdomain page for [Subdomain] button that opens the Subdomain page. Change the record back at your DNS Provider, or, if you moved the Subdomain on purpose, click the Delete Subdomain button on its Subdomain page to remove it from CloudCannon.

Renew the wildcard SSL Certificate#

The wildcard SSL Certificate for your Base Domain needs new TXT Records at your DNS Provider each time it renews, unless you add a CNAME Record once. The first wildcard SSL Certificate is optional, because your Base Domain and the Subdomains you have set up have their own certificates. Once you have one, renew it on time, or visitors to subdomains you haven't set up see a security warning. Before it expires, CloudCannon emails everyone who can edit the settings of your Base Domain the new TXT Records, and the DNS tab lists them under Wildcard certificate records, with the CNAME Record in the Automatic renewal record (optional) table below. You can add the CNAME Record at any time, not only during a renewal: while the record is missing, the DNS tab offers it, and the Other subdomains block in the HTTPS section of the Subdomain page for your Base Domain links to it. Once you add it, the certificate renews by itself, and you don't need to add TXT Records again. For more information, please read our documentation on renewing the wildcard SSL Certificate on External DNS.

Choose how visitors reach a Subdomain#

Each Subdomain on your Custom Domain has its own hosting option, which applies to every Site on that Subdomain. Changing a Subdomain's hosting requires the base-domain:settings:details:write permission. You can choose one of three options:

• CloudCannon Hosting — CloudCannon's global CDN serves the Subdomain. This is the default and recommended option. Your Base Domain can't point at the CDN on External DNS, so its A Records point straight at CloudCannon's origin instead.
• Cloudflare Proxy — Your own Cloudflare zone proxies the Subdomain to CloudCannon's origin.
• Single Origin — DNS points straight at CloudCannon's origin, or through your own proxy.

For more information on Subdomains, please read our documentation on what a Subdomain is.

Configure Cloudflare Proxy#

CloudCannon hosting uses Cloudflare. If you use Cloudflare as your DNS Provider and a record's proxy status is Proxied, you can't proxy directly to the normal CloudCannon CNAME (i.e., sites.cloudcannon.com⁠).

To resolve this issue, you can either set the record's proxy status to DNS only, or set the Subdomain's hosting to Cloudflare Proxy and add a CNAME Record to your DNS Provider.

The Hosting for [Subdomain] modal labels the saved option Current, shows the DNS Record the selected option needs, and warns you if the record has to change.

To set a Subdomain's hosting to Cloudflare Proxy:

1. Log in to CloudCannon.
2. Select the Organization your Custom Domain is connected to.
3. Click the Custom Domains link in the App Sidebar. CloudCannon will open the Domains Browser.
4. Select the domain for which you want to configure hosting by clicking the Card for the domain. CloudCannon will open the Summary tab of the Domain page.
5. Click the Subdomains tab. CloudCannon will list the Subdomains on your Custom Domain.
6. Click the Card for the Subdomain. CloudCannon will open the page for that Subdomain.
7. Click the Configure hosting button in the Hosting section. CloudCannon will open the Hosting for [Subdomain] modal.
8. Select the Cloudflare Proxy option under Hosting. CloudCannon will show the DNS Record the Subdomain needs.
9. Click the Save hosting button.

CloudCannon will expect your Cloudflare zone to proxy visitors to the CloudCannon origin.

To add a CNAME Record:

1. Log in to Cloudflare.
2. Navigate to the DNS Records for your domain.
3. Add a CNAME Record pointing your Subdomain (e.g., docs.example.com) at orange-cloud.cloudcannon.com, with the proxy status set to Proxied.
4. Set Cloudflare's SSL/TLS encryption mode to Full (strict).
5. Click the I've updated it button in the DNS section of the Subdomain page.

Cloudflare will confirm that you own the Subdomain from the proxied record, and issue its SSL Certificate. To issue the certificate before you change your proxied record, click the Switch to TXT validation button in the HTTPS section. For more information, please read our documentation on issuing the certificate before you switch a proxied record.

Configure Single Origin#

In some cases, you may need to configure your DNS Records to point directly at CloudCannon's host origin rather than sites.cloudcannon.com, for example when another provider proxies your Subdomain. Single Origin skips these features of CloudCannon Hosting:

• CloudCannon's global network, which serves your pages from locations around the world, so they load quickly everywhere.
• Certificate validation before your DNS points at CloudCannon. With Single Origin, CloudCannon can only validate your SSL Certificate once your DNS points at the CloudCannon origin.

To point your DNS straight at the CloudCannon origin, set the Subdomain's hosting to Single Origin and add DNS Records to your DNS Provider.

To set a Subdomain's hosting to Single Origin:

1. Log in to CloudCannon.
2. Select the Organization your Custom Domain is connected to.
3. Click the Custom Domains link in the App Sidebar. CloudCannon will open the Domains Browser.
4. Select the domain for which you want to configure hosting by clicking the Card for the domain. CloudCannon will open the Summary tab of the Domain page.
5. Click the Subdomains tab. CloudCannon will list the Subdomains on your Custom Domain.
6. Click the Card for the Subdomain. CloudCannon will open the page for that Subdomain.
7. Click the Configure hosting button in the Hosting section. CloudCannon will open the Hosting for [Subdomain] modal.
8. Select the Single Origin option under Hosting. CloudCannon will show the DNS Records the Subdomain needs.
9. Click the Save hosting button.

CloudCannon will expect your DNS to point straight at the CloudCannon origin.

The DNS section of the Subdomain page lists the records it needs in the Record column. For a Subdomain, this is a CNAME Record pointing at orange-cloud.cloudcannon.com. For your Base Domain, it is two A Records instead.

To add the DNS Records:

1. Log in to your third-party DNS Provider.
2. Add the records listed in the Record column of the DNS section of the Subdomain page.
3. Click the I've updated it button in the DNS section.

CloudCannon will show the Subdomain as Configured in the DNS section once your DNS points at the CloudCannon origin, and will answer the certificate challenge for the Subdomain itself.

If your own proxy sits in front of CloudCannon, have it connect to CloudCannon over HTTPS, keep the visitor's hostname in the Host header, and pass requests to /.well-known/acme-challenge/ through to CloudCannon, so the certificate authority can reach the challenge. If your proxy connects over HTTP and the Subdomain has Redirect http:// visitors to https:// ticked, CloudCannon answers every request with a redirect to HTTPS, which can send visitors in a redirect loop.