How to manage CNAME token 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 the 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.
This topic provides sample command lines that are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. 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
```
./ossutil64 bucket-cname --method put --item token oss://bucketname domainname
```
The following table describes the parameters in the preceding command.
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.
```
./ossutil64 bucket-cname --method put --item token oss://examplebucket example.com
```
The following output is returned:
```
<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

./ossutil64 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:

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

The following output is returned:

<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:

./ossutil64 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

./ossutil64 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.
```
./ossutil64 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

./ossutil64 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:

./ossutil64 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:

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

If an SSL certificate is hosted, 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 hosted, 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 to the DNS records of the domain name and host an SSL certificate

Command syntax

./ossutil64 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 host an SSL certificate.

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

Disassociate SSL certificates

Command syntax

./ossutil64 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 SSL certificates.

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

Delete CNAME configurations

Command syntax

./ossutil64 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.
```
./ossutil64 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, you can 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:

./ossutil64 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.