PutCname

PutCname maps a custom domain name to a bucket. A standard bucket supports only an exact CNAME. An Agentic Bucket also supports a wildcard CNAME, used to access its Bucket Spaces.

Usage notes

When you map an exact or a wildcard CNAME to an Agentic Bucket, you must explicitly include the IsWildCard element in the request XML and set it to true or false.
For an Agentic Bucket, the following elements are not supported: AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache, and ClientCaConfiguration (including casCertId, inline certificates, and delete operations). If you configure any of them, OSS returns the 400 MalformedXML error. A standard bucket retains full support for these elements.
A Bucket Space cannot be mapped to a CNAME directly. Public network access to a Bucket Space goes through the wildcard CNAME mapped to its parent Agentic Bucket.

Permissions

By default, an Alibaba Cloud account has all permissions. RAM users and RAM roles under an Alibaba Cloud account have no permissions by default. The Alibaba Cloud account or an account administrator must grant the required permissions by using RAM Policy or Bucket Policy.

API	Action	Description
PutCname	oss:PutCname	Maps a custom domain name to a bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	If you bind a certificate when you map a custom domain name to a bucket, these three permissions are required.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Request syntax

POST /?cname&comp=add HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: GMT Date
Authorization: SignatureValue
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Note

PutCname uses the IsWildCard element in the request XML to declare whether the CNAME is exact or wildcard. For an Agentic Bucket, the IsWildCard element is required.

Request headers

This operation uses only common request headers. For more information, see Common HTTP headers.

Request elements

Element	Type	Required	Example	Description
BucketCnameConfiguration	Container	Yes	N/A	The container that stores the CNAME configuration. Parent nodes: none Child nodes: Cname
Cname	Container	Yes	N/A	The container that stores the CNAME information. Parent nodes: BucketCnameConfiguration Child nodes: Domain, IsWildCard, and CertificateConfiguration
Domain	String	Yes	example.com	The custom domain name. To map an exact CNAME, set this element to the complete domain name, such as console.example.com. To map a wildcard CNAME, set this element to the base domain name without the `*.` prefix, such as example.com. Parent nodes: Cname Child nodes: none
IsWildCard	Boolean	Standard bucket: No Agentic Bucket: Yes	true	Specifies whether to map a wildcard CNAME. Valid values: true: maps a wildcard CNAME. Set Domain to the base domain name. false: maps an exact CNAME. Set Domain to the complete domain name. For an Agentic Bucket, this element is required. Set it explicitly to true or false. For a standard bucket, if you omit this element, the value defaults to false. Parent nodes: Cname Child nodes: none
CertificateConfiguration	Container	No	N/A	The container that stores the certificate configuration. When you map a wildcard CNAME, the CN or SAN of the certificate must match `*.<Domain>`, so a wildcard certificate is required. Parent nodes: Cname Child nodes: CertId, Certificate, PrivateKey, PreviousCertId, Force, and DeleteCertificate
CertId	String	No	493****-cn-hangzhou	The certificate ID. Parent nodes: CertificateConfiguration Child nodes: none
Certificate	String	No	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	The public key of the certificate. Parent nodes: CertificateConfiguration Child nodes: none
PrivateKey	String	No	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	The private key of the certificate. Parent nodes: CertificateConfiguration Child nodes: none
PreviousCertId	String	No	493****-cn-hangzhou	The ID of the certificate that is currently bound. If Force is not set to true, OSS checks that this value matches the certificate that is actually bound and returns an error if it does not. Important If you do not specify PreviousCertId when you bind a certificate, set Force to true. Parent nodes: CertificateConfiguration Child nodes: none
Force	String	No	true	Specifies whether to overwrite the certificate. Valid values: true: overwrites the certificate. false: does not overwrite the certificate. Parent nodes: CertificateConfiguration Child nodes: none
DeleteCertificate	String	No	true	Specifies whether to delete the certificate. Valid values: true: deletes the certificate. false: does not delete the certificate. Parent nodes: CertificateConfiguration Child nodes: none

Response headers

This operation returns only common response headers. For more information, see Common HTTP headers.

Examples

Sample requests

Map a custom domain name to a standard bucket

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Bind a certificate to a custom domain name of a standard bucket

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <CertificateConfiguration>
      <CertId>493****-cn-hangzhou</CertId>
      <Certificate>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</Certificate>
      <PrivateKey>-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----</PrivateKey>
      <PreviousCertId>493****-cn-hangzhou</PreviousCertId>
      <Force>true</Force>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

Unbind a certificate from a custom domain name of a standard bucket

If you no longer want the domain name to use this certificate, unbind it.

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
      <CertificateConfiguration>
      <DeleteCertificate>True</DeleteCertificate>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

Map a wildcard CNAME to an Agentic Bucket (with a wildcard certificate)

POST /?cname&comp=add HTTP/1.1
Host: myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <IsWildCard>true</IsWildCard>
    <CertificateConfiguration>
      <Certificate>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</Certificate>
      <PrivateKey>-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----</PrivateKey>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

Map an exact CNAME to an Agentic Bucket

POST /?cname&comp=add HTTP/1.1
Host: myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>console.example.com</Domain>
    <IsWildCard>false</IsWildCard>
  </Cname>
</BucketCnameConfiguration>

Sample response

content-length: 0
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 980
connection: keep-alive
x-oss-request-id: 5C1B138A109F4E405B2D
date: Wed, 15 Sep 2021 03:33:37 GMT

OSS SDKs

The following OSS SDKs support the PutCname operation:

ossutil

For information about the ossutil command that corresponds to the PutCname operation, see put-cname.

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	The following are possible causes of the error: The CNAME format is invalid. You can check the returned XML for the specific error field and reason. For an Agentic Bucket, the `IsWildCard` element is missing or its value is empty. The wildcard base domain name failed verification. For example, the number of labels exceeds the upper limit, the number of levels is insufficient, or the domain name uses a high-risk TLD combination.
MalformedXML	400	The request includes an element that Agentic Buckets do not support (AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache, or ClientCaConfiguration), or the format of the request body is invalid.
CnameCertificateMismatch	400	The certificate does not match the CNAME domain name. When you map a wildcard CNAME, use a wildcard certificate whose CN or SAN matches `*.<Domain>`.
NeedVerifyDomainOwnership	403	Domain name ownership is not verified. To verify domain name ownership, perform the following steps: Call CreateCnameToken to create the CNAME token required for domain name ownership verification. When you create a token for a wildcard base domain name on an Agentic Bucket, specify `wildcard=true`. Add a TXT record at your domain name service provider. For example, to add a TXT record for the custom domain name `example.com`, set the record type to TXT, the host record to `_dnsauth.example`, and the record value to the CNAME token returned by Step 1. Keep the default settings for the other parameters. For more information, see Manually add a CNAME record. Note The TXT record that you add takes several minutes to take effect. Call PutCname to map the custom domain name.
CnameDenied	403	The domain name is already in use.
CnameIsForbidden	403	The domain name is reserved by OSS and cannot be mapped.
CnameIsRisk	403	The domain name poses a high risk and cannot be mapped.
NoSuchCnameInRecord	404	The domain name does not have an ICP filing. For more information about how to apply for an ICP filing, see Alibaba Cloud Domain Names.
ConflictCname	409	The wildcard base domain name is already mapped to another Agentic Bucket under the same UID. Unmap the wildcard CNAME from the original Agentic Bucket first, and then map it again.
CnameAlreadyExists	409	The following are possible causes of the error: The domain name is already mapped to another bucket in the current account. Symptom: The CnameType in the returned error message is CNAME_OSS. The domain name is an image processing domain name. Symptom: The CnameType in the returned error message is CNAME_IMG. To resolve these issues, unmap the domain name. For more information, see Unmap a domain name.
MethodNotAllowed	405	The CNAME feature is not enabled for the target bucket type.