All Products
Search

This Product

    Object Storage Service:put-bucket-replication

    Document Center

    Object Storage Service:put-bucket-replication

    Last Updated:Mar 20, 2026

    Configures data replication rules for a bucket. OSS supports two replication modes: cross-region replication (CRR) and same-region replication (SRR).

    For background on both modes, see CRR and SRR.

    Permissions

    By default, an Alibaba Cloud account has full permissions on its resources. RAM users and RAM roles start with no permissions and must be granted access via RAM policies or bucket policies.

    APIActionCondition
    PutBucketReplicationoss:PutBucketReplicationRequired on the source bucket
    oss:ReplicateGetRequired on both the source and destination buckets when replication is cross-account or a RAM role is specified

    Syntax

    ossutil api put-bucket-replication --bucket <value> [required]
                                   --replication-configuration <value> [required]
                                   [flags]

    Required parameters

    ParameterTypeDescription
    --bucketstringThe name of the source bucket
    --replication-configurationstringThe replication rule in XML or JSON format. Pass inline JSON, a JSON file (file://config.json), or an XML file (file://config.xml)

    For global flags, see Command-line options.

    This command maps to the PutBucketReplication API operation.

    Replication configuration

    The --replication-configuration value defines a single replication rule. Both XML and JSON formats are supported.

    Fields

    FieldTypeDescription
    PrefixSet.Prefixstring (repeatable)Limits replication to objects whose keys start with the specified prefix. You can specify multiple prefixes.
    ActionstringThe operation types to replicate. Example value: PUT.
    Destination.BucketstringThe name of the destination bucket
    Destination.LocationstringThe region of the destination bucket, for example, oss-cn-hangzhou
    Destination.TransferTypestringThe network path for replication traffic. Use oss_acc to route through OSS transfer acceleration.
    HistoricalObjectReplicationstringWhether to replicate objects that existed in the bucket before the rule was created. Example value: enabled.

    XML format

    <ReplicationConfiguration>
    <Rule>
        <PrefixSet>
            <Prefix>string</Prefix>
            <Prefix>string</Prefix>
        </PrefixSet>
        <Action>string</Action>
        <Destination>
            <Bucket>string</Bucket>
            <Location>string</Location>
            <TransferType>string</TransferType>
        </Destination>
        <HistoricalObjectReplication>string</HistoricalObjectReplication>
    </Rule>
</ReplicationConfiguration>

    JSON format

    {
    "Rule": {
        "PrefixSet": {
            "Prefix": [
                "string",
                "string"
            ]
        },
        "Action": "string",
        "Destination": {
            "Bucket": "string",
            "Location": "string",
            "TransferType": "string"
        },
        "HistoricalObjectReplication": "string"
    }
}

    Examples

    Configure data replication rules with a prefix filter

    This example configures data replication from examplebucket to destBucket in oss-cn-hangzhou. Only objects with the key prefix prefix_1 or prefix_2 are replicated. Historical objects are included, and traffic routes through OSS transfer acceleration.

    1. Create a file named replication-configuration.xml:

         <?xml version="1.0" encoding="UTF-8"?>
   <ReplicationConfiguration>
       <Rule>
           <PrefixSet>
               <Prefix>prefix_1</Prefix>
               <Prefix>prefix_2</Prefix>
           </PrefixSet>
           <Action>PUT</Action>
           <Destination>
               <Bucket>destBucket</Bucket>
               <Location>oss-cn-hangzhou</Location>
               <TransferType>oss_acc</TransferType>
           </Destination>
           <HistoricalObjectReplication>enabled</HistoricalObjectReplication>
       </Rule>
   </ReplicationConfiguration>

    2. Apply the rule:

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

    Use a JSON configuration file

    The same rule expressed in JSON:

    1. Create a file named replication-configuration.json:

         {
       "Rule": {
           "PrefixSet": {
               "Prefix": [
                   "prefix_1",
                   "prefix_2"
               ]
           },
           "Action": "PUT",
           "Destination": {
               "Bucket": "destBucket",
               "Location": "oss-cn-hangzhou",
               "TransferType": "oss_acc"
           },
           "HistoricalObjectReplication": "enabled"
       }
   }

    2. Apply the rule:

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

    Pass configuration inline

    Pass the JSON directly in the command without a file:

    ossutil api put-bucket-replication --bucket examplebucket --replication-configuration "{\"Rule\":{\"PrefixSet\":{\"Prefix\":[\"prefix_1\",\"prefix_2\"]},\"Action\":\"PUT\",\"Destination\":{\"Bucket\":\"destBucket\",\"Location\":\"oss-cn-hangzhou\",\"TransferType\":\"oss_acc\"},\"HistoricalObjectReplication\":\"enabled\"}}"

    What's next