Cross-region replication (CRR) provides automatic and asynchronous (near real-time) replication of objects across buckets in different Object Storage Service (OSS) regions. This topic describes how to run the replication command to manage the configurations of CRR rules. After you configure a CRR rule, OSS replicates the objects in the source bucket to the destination bucket located in a different OSS region based on the CRR rule.

Notice
  • Sample command lines in this topic 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.
  • For more information about the scenarios and usage notes of CRR, see Cross-region replication.

Add a CRR rule

You can configure CRR rules to replicate data from the source bucket to multiple destination buckets. You can configure up to 100 CRR rules for a bucket.

To add a CRR rule, you must first create a local file and specify the CRR rule that you want to add. Then, add the CRR rule for the source bucket.

  • Command syntax
    ./ossutil64 replication --method put oss://bucketname local_xml_file

    The following table describes the parameters that you can configure when you run this command to add CRR rules for a bucket.

    Parameter Description
    bucketname The name of the bucket for which you want to add CRR rules.
    local_xml_file The name of the local file in which the CRR rules are specified. Example: localfile.txt.
  • Examples
    1. Create a file named localfile.txt on the local device and specify CRR rules in the file based on your requirements.
      The following code provides an example on how to configure a rule. This rule allows you to synchronize create, delete, and modify operations performed on objects whose names contain the specified srcdir prefix in the source bucket to the destination bucket named destbucket that is located in the China (Hangzhou) region. In addition, transfer acceleration is enabled in the synchronization process, and historical data is also synchronized to the destination bucket.
       <?xml version="1.0" encoding="UTF-8"?>
       <ReplicationConfiguration>
          <Rule>
               <PrefixSet>
                   <Prefix>srcdir</Prefix>             
               </PrefixSet>
               <Action>ALL,PUT</Action>
               <Destination>
                   <Bucket>destbucket</Bucket>
                   <Location>oss-cn-hangzhou</Location>
                   <TransferType>oss_acc</TransferType>
               </Destination>
               <HistoricalObjectReplication>enabled</HistoricalObjectReplication>
          </Rule>
       </ReplicationConfiguration>
    2. Add the CRR rule for the source bucket named srcbucket.
      ./ossutil64 replication --method put oss://srcbucket localfile.txt
  • Output

    If a similar output is displayed, the CRR rule is added for the srcbucket bucket:

    0.856895(s) elapsed

Query the CRR rules added for a bucket

  • Command syntax
    ./ossutil64 replication --method get oss://bucketname
  • Examples

    You can run the following command to query the CRR rules added for the srcbucket bucket and view the results that are displayed on the screen:

    ./ossutil64 replication --method get oss://srcbucket

    If a similar output is displayed, the CRR rules added for the srcbucket bucket are obtained:

    <?xml version="1.0" encoding="UTF-8"?>
    <ReplicationConfiguration>
      <Rule>
        <ID>37417af4-f2dc-4b24-92d3-82092af6****</ID>
        <Action>ALL</Action>
        <Destination>
          <Bucket>destbucket</Bucket>
          <Location>oss-cn-beijing</Location>
        </Destination>
        <Status>doing</Status>
        <HistoricalObjectReplication>enabled</HistoricalObjectReplication>
      </Rule>
    </ReplicationConfiguration>
    
    
    0.069195(s) elapsed

Query the regions where CRR can be performed

  • Command syntax
    ./ossutil64 replication --method get --item location oss://bucketname
  • Examples

    You can run the following command to query to which regions data in the srcbucket bucket can be synchronized:

    ./ossutil64 replication --method get --item location oss://srcbucket

    If a similar output is displayed, the regions to which you can synchronize data in the srcbucket bucket are obtained:

    <?xml version="1.0" ?>
    <ReplicationLocation>
      <Location>oss-cn-beijing</Location>
      <Location>oss-cn-qingdao</Location>
      <Location>oss-cn-shenzhen</Location>
      <Location>oss-cn-hongkong</Location>
      <Location>oss-us-west-1</Location>
      <LocationTransferTypeConstraint>
        <LocationTransferType>
          <Location>oss-cn-hongkong</Location>
            <TransferTypes>
              <Type>oss_acc</Type>          
            </TransferTypes>
          </LocationTransferType>
          <LocationTransferType>
            <Location>oss-us-west-1</Location>
            <TransferTypes>
              <Type>oss_acc</Type>
            </TransferTypes>
          </LocationTransferType>
        </LocationTransferTypeConstraint>
      </ReplicationLocation>
    
    0.226523(s) elapsed

Query the progress of a CRR task performed on a specified bucket

  • Command syntax
    ./ossutil64 replication --method get --item progress oss://bucketname [ruleID]

    The following table describes the parameters that you can configure when you run this command to query the progress of a CRR task performed on a specified bucket.

    Parameter Description
    bucketname The name of the bucket on which the CRR task is performed.
    ruleID Specify the ID of the CRR rule of which you want to query the CRR task progress. If you do not specify the ID of a CRR rule, the CRR task progress of all the CRR rules added for the bucket is queried. The results of the CRR task progress can only be displayed on the screen.
  • Examples

    You can run the following command to query the progress of a specified CRR task performed on the srcbucket bucket:

    ./ossutil64 replication --method get --item progress oss://srcbucket 37417af4-f2dc-4b24-92d3-82092af6****

    You can run the following command to query the progress of all CRR tasks performed on the srcbucket bucket:

    ./ossutil64 replication --method get --item progress oss://srcbucket

    If a similar output is displayed, the progress of replicating existing data from the srcbucket bucket to the destination bucket before CRR is enabled is 100%. After CRR is enabled, data written to the srcbucket bucket before 06:00:59.000 on August 9, 2021 UTC is replicated to the destination bucket named destbucket.

    <?xml version="1.0" encoding="UTF-8"?>
    <ReplicationProgress>
      <Rule>
        <ID>37417af4-f2dc-4b24-92d3-82092af6****</ID>
        <Action>ALL</Action>
        <Destination>
          <Bucket>destbucket</Bucket>
          <Location>oss-cn-beijing</Location>
        </Destination>
        <Status>doing</Status>
        <HistoricalObjectReplication>enabled</HistoricalObjectReplication>
        <Progress>
          <HistoricalObject>1.00</HistoricalObject>
          <NewObject>2021-08-09T06:00:59.000Z</NewObject>
        </Progress>
      </Rule>
    </ReplicationProgress>
    
    
    0.125002(s) elapsed

Remove CRR configurations

  • Command syntax
    ./ossutil64 replication --method delete oss://bucketname ruleID
  • Examples

    You can run the following command to remove the configurations of a specified CRR rule added for the srcbucket bucket:

    ./ossutil64 replication --method delete oss://srcbucket 37417af4-f2dc-4b24-92d3-82092af6****

    If a similar output is displayed, the configurations of the specified CRR rule added for the srcbucket bucket are removed:

    0.069195(s) elapsed

Common options

To use ossutil to manage buckets that are located in different regions, you can use the -e option to use the endpoint of a specified bucket. To use ossutil to manage buckets that are owned by different Alibaba Cloud accounts, you can use the -i option to use the AccessKey ID of a specified account, and use the -k option to use the AccessKey secret of the specified account.

For example, you can run the following command to configure CRR rules for a bucket named testbucket, which is located in the China (Shanghai) region and is owned by another Alibaba Cloud account. The CRR rule is specified by using the local file named localfile.txt.

./ossutil64 replication --method put oss://testbucket localfile.txt -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about other common options that you can use for the replication command, see Common options.