Map a custom domain name to a bucket - Object Storage Service

Maps a custom domain name to a bucket.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API	Action	Description
PutCname	oss:PutCname	Maps a custom domain name to a bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	When mapping a custom domain name to a bucket, if a certificate is attached, these three permissions are required.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Command syntax

ossutil api put-cname --bucket value --cname-configuration value [flags]

Parameter	Type	Description
--bucket	string	The name of the bucket.
--cname-configuration	string	The CNAME configuration container.

The --cname-configuration option accepts both XML and JSON. If the value contains the file:// prefix, the configuration is read from a file.

XML syntax:

<BucketCnameConfiguration>
  <Cname>
    <Domain>string</Domain>
    <IsWildCard>bool</IsWildCard>
  </Cname>
</BucketCnameConfiguration>

JSON syntax:

{
  "Cname": {
    "Domain": "string",
    "IsWildCard": boolean
  }
}

Note

put-cname does not use the --wildcard option. Instead, it declares the CNAME type through the IsWildCard element in --cname-configuration. IsWildCard is set to true or false: true indicates a wildcard domain CNAME (the Domain value is the base domain of the wildcard domain, without the *. prefix), and false indicates an exact CNAME.
Only Agentic Buckets support wildcard domain CNAMEs: when binding a CNAME (exact or wildcard) to an Agentic Bucket, you must explicitly configure the IsWildCard element. It cannot be left empty or omitted. Standard buckets do not require this element. Make sure that your ossutil version supports the IsWildCard element.
The put-cname command corresponds to the PutCname API operation. For more information about the parameters, see PutCname. For more information about supported global command-line options, see Global command-line options.

Examples

1. Map the custom domain name example.com to examplebucket.

Use an XML configuration file. The content of cname-configuration.xml is as follows:

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

Sample command:

ossutil api put-cname --bucket examplebucket --cname-configuration file://cname-configuration.xml

Use a JSON configuration file. The content of cname-configuration.json is as follows:

{
  "Cname": {
    "Domain": "example.com"
  }
}

Sample command:

ossutil api put-cname --bucket examplebucket --cname-configuration file://cname-configuration.json

Use JSON configuration parameters. Sample command:

ossutil api put-cname --bucket examplebucket --cname-configuration "{\"Cname\":{\"Domain\":\"example.com\"}}"

2. Bind a certificate to examplebucket.

Use an XML configuration file. The content of cname-configuration.xml is as follows:

<?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 RSA PRIVATE KEY-----
MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC****
-----END RSA PRIVATE KEY-----</PrivateKey>
      <PreviousCertId>493****-cn-hangzhou</PreviousCertId>
      <Force>true</Force>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

Sample command:

ossutil api put-cname --bucket examplebucket --cname-configuration file://cname-configuration.xml

Use a JSON configuration file. The content of cname-configuration.json is as follows:

{
    "Cname": {
        "Domain": "example.com",
        "CertificateConfiguration": {
            "CertId": "493****-cn-hangzhou",
            "Certificate": "-----BEGIN CERTIFICATE-----
MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC****
-----END CERTIFICATE-----",
            "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----
MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC****
-----END RSA PRIVATE KEY-----",
            "PreviousCertId": "493****-cn-hangzhou",
            "Force": true
        }
    }
}

Sample command:

ossutil api put-cname --bucket examplebucket --cname-configuration file://cname-configuration.json

3. Map a wildcard CNAME for example.com, with certificate, to the Agentic Bucket myab-$uid-$region-ab-apsr.

Use an XML configuration file. The content of cname-configuration.xml is as follows:

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

Sample command:

ossutil api put-cname --bucket my-uid-region-ab-apsr --cname-configuration file://cname-configuration.xml

Use JSON configuration parameters. Sample command:

ossutil api put-cname --bucket my-uid-region-ab-apsr --cname-configuration "{\"Cname\":{\"Domain\":\"example.com\",\"IsWildCard\":true}}"