Working with domains

Domains are used to route requests to your service. You associate your domain names with your origin when provisioning a Fastly service so you can properly route requests to your website and ensure that others cannot serve requests to that domain. For example, you could enter www.example.com, blog.example.com, or even use wildcards such as *.example.com. You can add, edit, or remove domains from your service at any time.

TIP

Due to limitations in the DNS specification, Fastly doesn't recommend using apex or second-level domains. An example of an apex domain is example.com rather than www.example.com.

Before you begin

Be sure you learn about the web interface controls and how to work with services before you start working with your domains.

Domain creation limits

Domains can only be associated with a single service at a time and each service has a limited number of domains that can be associated with it.

Domains can only be associated with one service at a time

If a domain is in use by another service within your account, you can delete the domain and add it to the other service. However, if a domain is used by a service in another Fastly account, it can't be used without being delegated.

If you try to create a domain that is already associated with another service, you may get error messages like:

Domain [domain name] is already taken by service [service name].

In this case, follow the steps to delete a domain from your service before creating the domain on your new service.

If you try to create a domain that is already owned by another customer, you may get error messages like:

Domain [domain name] is taken by another customer. Domain [domain name] is owned by another customer.

If you receive one of these errors when adding a domain that you rightfully should have access to, or if you need to delegate a domain to another account or customer (for example, delegating a domain from a test account to a production account), contact support to help you delegate the domain to the correct account.

Services are limited to a set number of domains

We set a limit on the number of domains you can create per service by default based on your account type and any packaged offering you've purchased.

Once you reach that limit, error messages may appear that look something like this:

1{
2 "msg": "An error occurred while connecting to the fastly API, please try your request again.",
3 "detail": "Exceeding max number of domains: 10"
4}

If you're receiving a limit message and need to create more services or domains, contact support for assistance. Fastly support engineers can not only increase the number of services that you can use, they can suggest other ways to design what you are trying to achieve.

Creating a domain for the first time

Follow the steps below to add a domain to your service for the first time:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click Edit configuration and then select the option to clone the active version.

    the Create a Domain page

  4. Fill out the domain creation fields as follows:

    • In the Domain Name field, enter your domain name.
    • (Optional) In the Comment field, enter a comment that describes the domain.
  5. Click the Add button. Your new domain appears in the list of domains.

  6. Click Activate to deploy your configuration changes.
  7. If you haven't already, add a CNAME DNS record for your domain name to begin routing client traffic through Fastly services instead of directly to your origin.

Creating additional domains

Follow the steps below to add additional domains to your service:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click Edit configuration and then select the option to clone the active version.

    the Domains page

  4. Click Create domain.

    the Create a Domain page

  5. Fill out the domain creation fields as follows:

    • In the Domain Name field, enter your domain name.
    • (Optional) In the Comment field, enter a comment that describes the domain.
  6. Click Add. Your new domain appears in the list of domains.

  7. Click Activate to deploy your configuration changes.
  8. If you haven't already, add CNAME DNS records for your domain name to begin routing client traffic through Fastly services instead of directly to your origin.

Creating a domain using the API

You can use Fastly's API to programmatically add domains to your service. To add a domain to your service, make the following API call in a terminal application:

$ curl -H "Fastly-Key: FASTLY_API_TOKEN" -X POST https://api.fastly.com/service/<service_id>/version/<version_id>/domain -d 'name=www.example.com'

The response will look like this:

1{
2 "comment": "",
3 "name": "www.example.com",
4 "service_id": "<service_id>",
5 "version": <version_id>
6}

Testing a domain

After you activate your service configuration, but before you change your DNS entries to send your domain to our servers, you can check to see how your service is pulled through our network. Testing your domain can help you identify DNS issues or problems with your Fastly configuration.

Using the web interface

To use the web interface to test your domain on Fastly before you make a final CNAME change, follow the steps below:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click Edit configuration and then select the option to clone the active version.

    the Domains page

  4. Click Test domain next to the domain you want to test.

  5. Verify that your website appears in a new tab in your web browser.

Using command line utilities

To use command line utilities to test your domain on Fastly before you make a final CNAME change, follow the steps below:

  1. Find the IP address of a Fastly POP.
  2. Add a domain Host entry to your hosts file.
  3. Test the domain in a web browser.

Determining the IP address of a Fastly POP

Use the host, nslookup, or dig command to determine the IP address of a Fastly POP. We return different IP addresses depending on the location and state of the network making the request. As a result, the IP address you receive for any specific query may differ from the below examples but should result in the best performance for you.

TIP

For non-TLS requests, use dualstack.nonssl.global.fastly.net for connection over IPv6. For TLS requests, use the custom TLS CNAME record provided in the web interface or by Fastly support. For more information about the Fastly TLS service, see our guide on TLS service options.

Running host for your domain returns both IPv4 addresses and IPv6 addresses:

$ host www.example.com.
www.example.com.is an alias for dualstack.nonssl.global.fastly.net.
dualstack.nonssl.global.fastly.net has address 199.232.144.204
dualstack.nonssl.global.fastly.net has IPv6 address 2a04:4e42:64::204

In this example, the IPv4 address is 199.232.144.204 and the IPv6 address is 2a04:4e42:64::204.

Running nslookup for dualstack.nonssl.global.fastly.net also returns both IPv4 addresses and IPv6 addresses:

$ nslookup dualstack.nonssl.global.fastly.net.
Server: 127.0.0.53
Address: 127.0.0.53#53
Non-authoritative answer:
Name: dualstack.nonssl.global.fastly.net
Address: 199.232.144.204
Name: dualstack.nonssl.global.fastly.net
Address: 2a04:4e42:64::204

In this example, the IPv4 address is 199.232.144.204 and the IPv6 address is 2a04:4e42:64::204.

Alternatively, you can run dig to determine the IP address, but you must specify an A query for IPv4 addresses or a AAAA query for IPv6 addresses.

Running dig for your domain with an A query returns:

$ dig +noall +answer -t A www.example.com.
www.example.com. 3600 IN CNAME dualstack.nonssl.global.fastly.net.
dualstack.nonssl.global.fastly.net. 30 IN A 199.232.144.204

The IPv4 address is 199.232.144.204

Running dig for your domain with an AAAA query returns:

$ dig +noall +answer -t AAAA www.example.com.
www.example.com. 3600 IN CNAME dualstack.nonssl.global.fastly.net.
dualstack.nonssl.global.fastly.net. 30 IN AAAA 2a04:4e42:64::204

The IPv6 address is 2a04:4e42:64::204.

Modifying your hosts file

You can temporarily add a static IP address and domain Host entry to the hosts file on your computer. Use the following anycast IPs for testing your sites served over dualstack.nonssl.global.fastly.net.

IPv4IPv6
151.101.0.2042a04:4e42::204
151.101.64.2042a04:4e42:200::204
151.101.128.2042a04:4e42:400::204
151.101.192.2042a04:4e42:600::204

For example, if the domain you are testing is www.example.com and you are using the anycast IPv4 example 151.101.0.204, you would add this entry to the file and save the changes:

151.101.0.204 www.example.com
TIP

On machines running macOS or Linux, your hosts file is /etc/hosts. On Windows-based machines, it's C:\Windows\System32\Drivers\etc\hosts.

Testing your domain

Test your domain to see how Fastly pulls it through our network by restarting your browser if it's already running, and then typing your domain in the address field. You should now see the updated domain in the address field indicating requests are being sent to the Fastly POP.

Alternatively, you can test the domain using a ping command to verify that your domain is being served by a Fastly POP address. In this case, ping www.example.com would display the Fastly POP address 151.101.56.204.

Be sure to remove the Host entry from your hosts file after you make CNAME changes to point your domain to Fastly.

Deleting a domain

Follow the steps below to delete a domain from your service:

  1. On the Domains page, click the trash next to the domain you want to delete.
  2. Click Confirm and delete to confirm you want to delete your domain.
  3. Click Activate to deploy your configuration changes.
IMPORTANT

To minimize the risk of unauthorized use of your domains, we strongly recommend modifying or deleting any DNS CNAME records pointing to the Fastly hostname associated with the deleted domain. Follow the instructions on your DNS provider's website.

What's next

Learn more about working with hosts and working with health checks as you continue to refine versions of your service configurations.

Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.