All Products
Search
Document Center

Object Storage Service:bucket-cname

Last Updated:Aug 15, 2024

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 Attach a custom policy to a RAM user.

  • 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 Map a custom domain name to the default domain name of a bucket.

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

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

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 LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.