After you upload objects to buckets, Object Storage Service (OSS) automatically generates URLs for the objects. You can use the URLs to access the objects. If you want to access the objects by using custom domain names, you must map the custom domain names to the buckets in which the objects are stored and add CNAME records for the custom domain names.

Prerequisites

  • A custom domain name is registered. For more information about how to register a custom domain name, see Register a generic domain name.
  • The Internet Content Provider (ICP) filing is complete for the domain name of the bucket that is located in the Chinese mainland and to which you want to map the custom domain name.

    For more information about how to apply for an ICP filing, see What is an ICP filing?

Limits

  • You can map up to 100 domain names to a bucket. Each domain name can be mapped only to one bucket. OSS does not limit the number of domain names that an Alibaba Cloud account can map.
  • If you map a custom domain name to a bucket in the OSS console, the domain name cannot contain wildcard characters. If Alibaba Cloud CDN is enabled to accelerate the retrieval of resources from an OSS bucket, you can map a custom domain name that contains wildcard characters to the bucket. However, the domain name does not appear in the OSS console.

Usage notes

You can map a custom domain name to a bucket to meet the requirements in the following scenarios:

  • To make sure that the image objects in a bucket that is created in a region in the Chinese mainland after September 23, 2019 are previewed but not downloaded when you access the objects by using a browser.
  • To make sure that the web pages of a static website that is hosted in an OSS bucket are accessed but not downloaded.

Rules for using custom domain names

For example, a public-read object named exampleobject.jpg is stored in the root directory of the bucket named examplebucket in the China (Hangzhou) region. The custom domain name www.example.com is mapped to the bucket. The URLs that are used to access the object are different before and after the custom domain name is mapped to the bucket.
  • Before the custom domain name is mapped to the bucket

    You can use the following URL that contains the default domain name of the bucket to access the exampleobject.jpg object: https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.jpg.

  • After the custom domain name is mapped to the bucket

    You can use the following URL that contains the custom domain name mapped to the bucket to access the exampleobject.jpg object: https://www.example.com/exampleobject.jpg.

    Note After you map a custom domain name to a bucket, you can preview an image object in the bucket when you access the image object. If the object cannot be previewed but can be downloaded as an attachment, the browser may not support the preview of images in specific formats. To resolve this issue, you must install a plug-in that allows you to preview images in specific formats in a browser.

Use the OSS console

  1. Map a custom domain name to a bucket.
    1. Log on to the OSS console.
    2. In the left-side navigation pane, click Buckets. On the Buckets page, click the name of the bucket to which you want to map a custom domain name.
    3. In the left-side navigation pane, choose Transmission > Domain Names.
    4. Click Map Custom Domain Name.
    5. In the Map Custom Domain Name panel, enter the domain name that you want to map in the Custom Domain Name field.
      Domain names that contain wildcard characters are not supported. Example: *.example.com.

      If a message appears to indicate that a domain name conflict occurs, the domain name has been mapped to another bucket. To resolve this issue, you can map another domain name to the bucket or verify the ownership of the domain name and forcibly map the domain name to the bucket. If you verify the ownership of the domain name and forcibly map the domain name to the bucket, the mapping between the domain name and the original bucket is removed.

  2. Add a CNAME record.
    • If the domain name is managed by your Alibaba Cloud account, perform the following steps to automatically add a CNAME record.
      1. In the Map Custom Domain Name panel, turn on Add CNAME Record Automatically.
        Notice If the domain name has a CNAME record, the CNAME record is updated to the new CNAME record.
      2. Click Submit.
    • If the domain name is not managed by your Alibaba Cloud account, manually add a CNAME record.

      If the domain name is not hosted by Alibaba Cloud, you must add a CNAME record to the Domain Name System (DNS) of your DNS provider.

      The following example shows how to use Alibaba Cloud DNS to manually add a CNAME record to a domain name that is not hosted by Alibaba Cloud:

      1. Log on to the Alibaba Cloud DNS console.
      2. On the Manage DNS page, click Configure in the Actions column corresponding to the domain name to which you want to add a CNAME record.
      3. On the DNS Settings page, click Add Record. In the Add Record panel, configure the parameters described in the following table.
        Parameter Description
        Type Select the type of the record that you want to add. Select CNAME in this step.
        Host Enter the host record based on the prefix of the domain name.
        • To add a top-level domain such as aliyun.com, enter @.
        • To add a second-level domain, enter the prefix of the second-level domain. For example, if the domain name is help.aliyun.com, enter help.
        • To map all second-level domains to the domain name of the bucket, enter *.
        ISP Line Select the ISP line that is used to resolve the domain name. To allow the system to select the optimal line, we recommend that you select Default for this parameter.
        Value Enter the public endpoint of the bucket. The public endpoint of a bucket is in the BucketName.Endpoint format. The public endpoint of the China (Hangzhou) region is oss-cn-hangzhou.aliyuncs.com. If you create a bucket named examplebucket in the China (Hangzhou) region, the public endpoint of the bucket is examplebucket.oss-cn-hangzhou.aliyuncs.com.
        TTL Select the interval at which the record is updated. Keep the default value.
      4. Click OK.

        A new CNAME record immediately takes effect. The time required for a modified CNAME record to take effect is 72 hours.

Check whether the CNAME record takes effect

You can run the ping or lookup command to check whether a specified CNAME is in effect. If the request is redirected to *.oss-cn-*.aliyuncs.com, the CNAME is in effect.

Verify the ownership of a domain name

If the custom domain name that you want to map to a bucket is not managed by your Alibaba Cloud account or is registered by another vendor, you must verify the ownership of the domain name before you can map the domain name to the bucket.

  1. Click Obtain TXT.
    Domain name
    Note OSS randomly generates a token for the domain name, which includes the following fields: Domain, Host, and Value. Store the token information in a secure location.
    cname
  2. Add a TXT record to your DNS records. Enter the recorded values of the Host and Value fields in Step 1 and retain the default settings of other parameters.
    For more information about how to add a CNAME record, see Manually add a CNAME record.
  3. In the Map Custom Domain Name panel, read and select I have added the TXT record. Continue submission.
    If your configurations are correct, OSS maps the custom domain name to the bucket.

Remove a domain name mapping

If you no longer need to use a custom domain name, you can remove the mapping of the custom domain name from a bucket.

  1. On the management page of the bucket from which you want to remove the custom domain name mapping, choose Transmission > Domain Names.
  2. On the Domain Names tab, click Manage Mapping Configurations in the Actions column corresponding to the domain name for which you want to remove the mapping.
  3. In the Manage Mapping Configurations panel, click Unbind. Then, click OK.

References