How to manage CNAME tokens and CNAME configurations by running the bucket-cname command - Object Storage Service

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

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>

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

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>

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.

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.