Updated on 2026-09-21 GMT+08:00

Configuring a User-Defined Domain Name for a Bucket

Function

You can use this command to configure a user-defined domain name for a bucket.

Constraints

To configure a user-defined domain name for a bucket, you must be the bucket owner or have the required permission (obs:bucket:SetBucketCustomDomainConfiguration granted using IAM or SetBucketCustomDomainConfiguration granted using a bucket policy). For details, see Differences Between OBS Permissions Control Methods, Using IAM Roles or Policies to Grant Access to OBS, and Creating a Custom Bucket Policy.

Command Line Structure

Windows

obsutil custom-domain obs://bucket -method=put -cname=xxx [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

macOS or Linux

./obsutil custom-domain obs://bucket -method=put -cname=xxx [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

Take Windows as an example. Run obsutil custom-domain obs://test-bucket -method=put -cname=www.obs-example.com to bind www.obs-example.com to bucket test-bucket.

obsutil custom-domain obs://test-bucket -method=put -cname=www.obs-example.com 

Start at 2024-09-30 07:59:28.8675681 +0000 UTC

Put customDomain configuration succeed for bucket [test-bucket], customDomain is [www.obs-example.com], requestId is [00000199765243C44018D688E9F5CFF5]

Parameter Description

Parameter	Optional or Mandatory	Description
bucket	Mandatory	The bucket name
method	Mandatory	The method. Set it to put when you configure a user-defined domain name for a bucket.
cname	Mandatory	The user-defined domain name for the bucket A bucket can have up to 30 user-defined domain names. One user-defined domain name can only be used for one bucket. A bucket can have up to 100 user-defined domain names. One user-defined domain name can only be used for one bucket.
certificateName	Optional (additional parameter)	The certificate name. It can be 3 to 63 characters long. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.
certificateId	Optional (additional parameter)	The certificate ID
certificate	Optional (additional parameter)	The certificate content. It can contain intermediate and root certificates. If the certificate_chain field contains a certificate chain, the certificate field should include only the certificate itself. Use escape characters \n or \r\n to replace line breaks in the certificate content.
certificateChain	Optional (additional parameter)	The certificate chain, which can be passed through the certificate field. Use escape characters \n or \r\n to replace line breaks in the certificate chain content.
privateKey	Optional (additional parameter)	The private key of the certificate. Private keys protected by passwords cannot be uploaded. Use escape characters \n or \r\n to replace line breaks in the private key content.
config	Optional (additional parameter)	The user-defined configuration file for executing the current command. For details about parameters that can be configured, see Configuration Parameters.
e	Optional (additional parameter)	The endpoint
i	Optional (additional parameter)	The user's AK
k	Optional (additional parameter)	The user's SK
t	Optional (additional parameter)	The user's security token

Helpful Links

For details about the API for configuring a user-defined domain name for a bucket, see Configuring a Custom Domain Name for a Bucket.
For details about the meanings, causes, and handling methods of error codes that may be returned during the operation, see OBS Error Codes.

Parent topic: Bucket Commands