All Products
Search

This Product

    Object Storage Service:bucket-cname

    Document Center

    Object Storage Service:bucket-cname

    Last Updated:Sep 24, 2026

    You can run the bucket-cname command to create a CNAME token that is used to verify the ownership of the domain names mapped to a bucket and manage CNAME configurations.

    Usage notes

    • To create a CNAME token, you must have the oss:CreateCnameToken permission. To query a CNAME token, you must have the oss:GetCnameToken permission. To add CNAME configurations, you must have the oss:PutCname permission. To query CNAME configurations, you must have the oss:ListCname permission. To delete CNAME configurations, you must have the oss:DeleteCname permission. For more information, see Grant a custom policy.

    • For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.

    Create a CNAME token

    Note

    Only ossutil 1.7.13 and later can be used to create a CNAME token.

    • Command syntax

      ossutil bucket-cname --method put --item token oss://bucketname domainname

      The following table describes the preceding parameters.

      Parameter

      Description

      bucketname

      The name of the bucket to which the domain name for which you want to add a CNAME record maps.

      domainname

      The custom domain name.

    • Examples

      The following sample code provides an example on how to create a CNAME token for the custom domain name example.com to be mapped to the bucket named examplebucket: 

      ossutil bucket-cname --method put --item token oss://examplebucket example.com

      The following output is displayed:

      <CnameToken>
 <Bucket>examplebucket</Bucket>
 <Cname>example.com</Cname>
 <Token>4db41c3ad0c4c4b690d4c17fb34e****</Token>
 <ExpireTime>Thu, 26 May 2022 19:14:12 GMT</ExpireTime>
</CnameToken>

0.270654(s) elapsed

      After the CNAME token is created, you must add a TXT record. For more information, see Access OSS through a custom domain name.

    Query the CNAME token

    • Command syntax

      ossutil bucket-cname --method get --item token oss://bucketname  domainname local_xml_file

    • Examples

      • The following sample code provides an example on how to query and display the CNAME token: 

        ossutil bucket-cname --method get --item token oss://examplebucket example.com

        The following output is displayed:

        <CnameToken>
 <Bucket>examplebucket</Bucket>
 <Cname>example.com</Cname>
 <Token>fbf997e8a2d48cb2177ed25180ee****</Token>
 <ExpireTime>Thu, 26 May 2022 19:53:19 GMT</ExpireTime>
</CnameToken>

0.144356(s) elapsed

      • The following sample code provides an example on how to query the CNAME token and store it in a local file: 

        ossutil bucket-cname --method get --item token oss://examplebucket example.com local.xml

        The local file contains the following content:

        <CnameToken>
 <Bucket>examplebucket</Bucket>
 <Cname>example.com</Cname>
 <Token>fbf997e8a2d48cb2177ed25180ee****</Token>
 <ExpireTime>Thu, 26 May 2022 19:53:19 GMT</ExpireTime>
</CnameToken>

    Add CNAME configurations

    Important

    Before you add CNAME configurations, you must create a CNAME token. For more information, see Create a CNAME token.

    • Command syntax

      ossutil bucket-cname --method put oss://bucketname domainname

    • Examples

      The following sample code provides an example on how to add CNAME configurations to a bucket named examplebucket: 

      ossutil bucket-cname --method put oss://examplebucket example.com

      If the following output is displayed, the CNAME configurations are added: 

      0.227834(s) elapsed

    Query CNAME configurations

    • Command syntax

      ossutil bucket-cname --method get oss://bucketname local_xml_file

    • Examples

      • The following sample code provides an example on how to query and display the CNAME configurations of a bucket named examplebucket: 

        ossutil bucket-cname --method get oss://examplebucket

        If the following output is displayed, the CNAME configurations of the bucket are queried. The following output shows that the domain names example.com and example.org are mapped to the bucket named examplebucket and these domain names are enabled: 

        <?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>examplebucket</Bucket>
  <Owner>148562088256****</Owner>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2021-08-26T07:25:12.000Z</LastModified>
    <Status>Enabled</Status>
    <IsPurgeCdnCache>true</IsPurgeCdnCache>
  </Cname>
  <Cname>
    <Domain>example.org</Domain>
    <LastModified>2021-08-26T07:25:26.000Z</LastModified>
    <Status>Enabled</Status>
    <IsPurgeCdnCache>true</IsPurgeCdnCache>
  </Cname>
</ListCnameResult>

0.164039(s) elapsed

      • The following sample code provides an example on how to query the CNAME configurations of a bucket named examplebucket and store the CNAME configurations in a local file: 

        ossutil bucket-cname --method get oss://examplebucket local.xml

        If an SSL certificate is associated, the following output is displayed:

        <?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>examplebucket</Bucket>
  <Owner>1506925210***</Owner>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2023-02-27T10:38:13.000Z</LastModified>
    <Status>Enabled</Status>
    <IsPurgeCdnCache>false</IsPurgeCdnCache>
    <Certificate>
      <Type>CAS</Type>
      <CertId>927****-cn-hangzhou</CertId>
      <Status>Enabled</Status>
      <CreationDate>Mon, 27 Feb 2023 06:51:34 GMT</CreationDate>
      <Fingerprint>60:AA:C3:2C:D4:70:54:3D:02:DB:B5:AA:E7:0E:E2:B9:0B:5A:C8:CC</Fingerprint>
      <ValidStartDate>Feb 10 00:00:00 2023 GMT</ValidStartDate>
      <ValidEndDate>Feb 10 23:59:59 2024 GMT</ValidEndDate>
    </Certificate>
  </Cname>
</ListCnameResult>

        If no SSL certificate is associated, the following output is displayed:

        <?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>examplebucket</Bucket>
  <Owner>148562088256****</Owner>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2021-08-26T07:25:12.000Z</LastModified>
    <Status>Enabled</Status>
    <IsPurgeCdnCache>true</IsPurgeCdnCache>
  </Cname>
  <Cname>
    <Domain>example.org</Domain>
    <LastModified>2021-08-26T07:25:26.000Z</LastModified>
    <Status>Enabled</Status>
    <IsPurgeCdnCache>true</IsPurgeCdnCache>
  </Cname>
</ListCnameResult>

    Add a CNAME record and associate an SSL certificate

    • Command syntax

      ossutil bucket-cname --method put --item certificate oss://bucketname local_xml_file

    • Examples

      1. Specify the local configuration file. 

        <?xml version="1.0" encoding="UTF-8"?>
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <CertificateConfiguration>
      <CertId>493****-cn-hangzhou</CertId>
      <Certificate>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</Certificate>
      <PrivateKey>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</PrivateKey>
      <PreviousCertId>493****-cn-hangzhou</PreviousCertId>
      <Force>true</Force>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

      2. Add a CNAME record to the DNS records of the domain name and associate an SSL certificate with the domain name. 

        ossutil bucket-cname --method put --item certificate oss://examplebucket local.xml

    Disassociate SSL certificates

    • Command syntax

      ossutil bucket-cname --method put --item certificate oss://bucketname local_xml_file

    • Examples

      1. Specify the local configuration file. 

        <?xml version="1.0" encoding="UTF-8"?>
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <CertificateConfiguration>
      <DeleteCertificate>True</DeleteCertificate>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

      2. Disassociate the SSL certificate. 

        ossutil bucket-cname --method put --item certificate oss://examplebucket local.xml

    Delete CNAME configurations

    • Command syntax

      ossutil bucket-cname --method delete oss://bucketname domainname

    • Examples

      The following sample code provides an example on how to delete CNAME configurations for a bucket named examplebucket: 

      ossutil bucket-cname --method delete oss://examplebucket example.com

      If the following output is displayed, the CNAME configurations are deleted: 

      0.227389(s) elapsed

    Common options

    To access a bucket in a different region, use -e to specify the endpoint. To access a bucket owned by a different Alibaba Cloud account, use -i for the AccessKey ID and -k for the AccessKey secret.

    For example, you can run the following command to add CNAME configurations for a bucket named testbucket that is located in the China (Hangzhou) region and that belongs to another Alibaba Cloud account:

    ossutil bucket-cname --method put oss://testbucket example.org -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret

    Common options.