bucket-cname

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

• Command syntax

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

  The following table describes the preceding parameters.

  Parameter	Description

  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

• 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 specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option 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 yourAccessKeyID -k yourAccessKeySecret

For more information about common options, see Common options.