This topic describes how to run the cp command to copy an Object Storage Service (OSS) object to other directories within the same bucket or to other buckets that are located in the same region as the source object. Currently, only objects can be copied. Parts that are generated by incomplete multipart copy tasks cannot be copied.

Note 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.

Command syntax

./ossutil64 cp cloud_url cloud_url
[-r, --recursive]
[-f --force]
[-u --update]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--disable-crc64]
[--payer <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]

The following table describes the parameters that you can configure when you run this command to copy an object.

Parameter Description
cloud_url Specify the paths of the source object and the destination object. oss://bucketname/objectname format. For example, to copy the srcobject.jpg source object from the examplebucket bucket to the destobject.jpg object in the same bucket, specify the path of the source object as oss://examplebucket/srcobject.jpg and the path of the destination bucket as oss://examplebucket/destobject.jpg.
-r, --recursive Specify recursive operations. If this parameter is specified, commands that support this parameter are run to perform operations on all objects in a bucket that meet the specified conditions. If this parameter is not specified, commands that support this parameter are run to perform operations only on the single specified object.
-f --force Specifies the command to forcibly run without prompting the user for confirmation.
-u, --update Specifies that ossutil copies the source object only when the object does not exist in the destination bucket or when the last modified time of the source object is later than that of the destination object.
--disable-ignore-error Specifies that errors are not ignored during batch operations.
--only-current-dir Specifies that only objects in the current directory are copied. Subdirectories in the current directory and objects in these subdirectories are not copied.
-bigfile-threshold Specifies the maximum size of objects that can be copied by using resumable upload or download. Unit: bytes.

Default value: 104857600 (100 MB).

Valid values: 0 to 9223372036854775807.

--part-size Specifies the size of each part. Unit: bytes. By default, ossutil determines the size of each part based on the object size.

Valid values: 1 to 9223372036854775807.

--checkpoint-dir Specifies the directory in which the log objects of resumable upload or download tasks are stored. Default value: .ossutil_checkpoint. When a resumable upload or download task fails, ossutil creates this directory and stores the checkpoint information about the task in this directory. ossutil deletes the directory after the task is completed. Therefore, if you specify a checkpoint directory, make sure that ossutil can delete the directory.
--encoding-type Specifies the method used to encode the names of objects. Valid values: url. If you do not specify this parameter, the names of objects are not encoded.
--include Specifies that the command applies to all objects that meet the specified conditions.
--exclude Specifies that the command applies to all objects that do not meet the specified conditions.
--meta Specifies the object metadata in the header:value#header:value format. Example: Cache-Control:no-cache#Content-Encoding:gzip. For more information about object metadata, see set-meta.
--acl Specifies the access control list (ACL) of the object. Default value: private. Valid values:
  • default: The ACL of the objects is the same as the ACL of the bucket in which the objects are stored.
  • private: Only the bucket owner can perform read and write operations on objects in the bucket. Other users cannot access the objects in the bucket.
  • public-read: Only the bucket owner can perform write operations on objects in the bucket. Other users, including anonymous users, can perform only read operations on the objects in the bucket. If you set this parameter to public-read, the objects may be unexpectedly accessed, which results in out-of-control costs. If a user uploads prohibited data or information, your legitimate interests and rights may be infringed. Therefore, we recommend that you do not set the object ACL to this value except in special cases.
  • public-read-write: All users, including anonymous users, can perform read and write operations on the objects in the bucket. If you set this parameter to public-read-write, data leakage may occur and you may be charged additional fees. Exercise caution when you set this parameter to public-read-write.
--disable-crc64 Specifies that CRC-64 is disabled. By default, CRC-64 is enabled when you use ossutil to transfer data.
--payer Specifies the payer of the traffic and request fees charged to copy the object. If you want the requester who accesses the resources in the specified path to pay for the traffic and request fees charged during the copy operation, set this parameter to requester.
-j, --jobs Specifies the number of concurrent tasks performed across multiple objects. Valid values: 1 to 10000. Default value: 3.
--parallel Specifies the number of concurrent tasks performed for a single object. Valid values: 1 to 10000. By default, if you do not set this parameter, ossutil sets the value of this parameter based on the operation type and the size of the object.
--version-id Specifies the version ID of the object that you want to copy. You can use this option for objects only in a bucket that has versioning enabled.

When the default configuration of the number of concurrent tasks based on the -j, --jobs and --parallel parameters cannot meet your requirements, you can configure these two parameters based on your requirements. By default, ossutil calculates the number of concurrent tasks based on the size of the object. When you copy multiple large objects, the actual number of concurrent tasks is calculated by multiplying the number of concurrent jobs by the number of concurrent operations.

  • We recommend that you adjust the number of concurrent tasks to a value smaller than 100 if the resources such as network bandwidth, memory, and CPU of your ECS instance or server are limited. If resources such as the network bandwidth, memory, and CPU are available, you can increase the number of concurrent tasks.
  • If the number of concurrent tasks is too large, the copy performance of ossutil may decrease, or an end-of-file (EOF) error may occur because thread resources are switched and threads compete for resources. To resolve this issue, you must adjust the values of the -j, --jobs and --parallel parameter based on the actual conditions of machines. To perform stress testing, set a small value for the two options before you adjust them incrementally to the optimal values.

Sample environment

In this topic, objects are copied between different directories or buckets in Linux. You can modify the parameters in the following examples based on your operating system and environment. Sample environment:

  • Operating system: Linux
  • Source bucket: examplebucket1
  • Directory 1 specified by the source bucket: srcfolder1
  • Directory 2 specified by the source bucket: srcfolder2
  • Source object: examplefile.txt
  • Destination bucket: examplebucket2
  • Directory specified by the destination bucket: desfolder

Example for simple copy

  • Copy a single object
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/                                 
  • Copy a directory
    You can run the following command in which the -r parameter is added to copy multiple objects:
    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ -r                                   
  • Copy incremental objects
    To copy multiple objects, if you specify the --update parameter, ossutil copies the objects only when the destination objects do not exist, or the last modified time of the source objects is later than that of the destination objects. You can run the following command to copy multiple objects:
    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ -r --update
    This option can be used to copy objects that fail to copy or to skip copied objects when you copy incremental objects.
  • Rename the object
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/example.txt                        
    When you run the cp command to rename an object, the original object still exists. You can delete the original object after you rename the object.
  • Copy only objects in the current directory and ignore subdirectories
    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder2/ --only-current-dir -r
  • Modify the metadata of the object
    When you copy an object, you can use the --meta parameter to modify the object metadata in the header:value#header:value... format.
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --meta=Cache-Control:no-cache
  • Copy an object from a bucket that has pay-by-requester enabled to a bucket that has pay-by-requester disabled
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/  --payer=requester

Modify the storage class of an object

When you overwrite an object, you can use the --meta option to convert the storage class of the object. OSS supports the following storage classes:
  • Standard
  • Infrequent Access (IA)
  • Archive
For more information, see Overview. Examples:
  • You can run the following command to convert the storage class of the specified object to Archive:
    ./ossutil64 cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta X-oss-Storage-Class:Archive
  • You can run the following command to convert the storage class of all objects in a specified directory to Standard:
    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta X-oss-Storage-Class:Standard -r
    Notice
    • You cannot convert the storage class of an Archive or Clod Archive object to other storage classes by running the cp command. You must first run the restore (restore objects) command to restore the object, and then run the cp command to convert the storage class of the object.
    • When you run the cp command to overwrite an object, fees may be charged. If an object of the IA, Archive, or Cold Archive storage class is stored for less than the minimum storage duration and is overwritten, you are charged for the minimum storage duration, which includes the remaining duration. For more information, see Storage fees.

Modify the tags of an object

You can run the following command to which the --tagging parameter is added to modify the tags of an object. Separate the tags with ampersands (&).
./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"

For more information about object tagging, see object-tagging (add, modify, query, and delete object tags).

Copy and encrypt an object

You can specify the server-side encryption method when you copy an object and store the encrypted object in a bucket. For more information about server-side encryption, see Server-side encryption.
  • You can run the following command to copy an object and set the server-side encryption method to AES-256:
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/ --meta=x-oss-server-side-encryption:AES256
  • You can run the following command to copy an object and set the server-side encryption method to KMS:
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS
    Notice When you use KMS to encrypt an object, OSS creates a customer master key (CMK) in the KMS console for the object and charges a small amount of fees when the KMS API operation is called. For more information, see Billing.
  • You can run the following command to copy an object, set the encryption method of the object to SSE-KMS, and specify a CMK ID:
    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

Recover objects in a versioning-enabled bucket

After you enable versioning for a bucket, objects that are overwritten or deleted in the bucket are saved as previous versions. You can run the following cp command to which the --version-id parameter is added to overwrite the previous version of an object as the latest version:
./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
Notice
  • To use the --version-id parameter, you must run the ls --all-versions command to query version IDs of the object.
  • The --version-id parameter can be used for objects only in versioning-enabled buckets. For more information about the command used to enable versioning for a bucket, see bucket-versioning.

Copy multiple objects that meet specified conditions

To copy objects that match specified conditions, you can use the --include and --exclude parameters. For more information, see Batch upload files that meet specified conditions.
  • You can run the following command to copy all objects that are not in the JPG format:
    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --exclude "*.jpg" -r
  • You can run the following command to copy all objects that contain abc in their names and are not in the JPG or TXT format:
    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

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 the 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 the 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 copy the srcobject.png object in the root directory of the examplebucket bucket to the destination bucket named destbucket. The source bucket is located in the China (Shanghai) region and is owned by another Alibaba Cloud account.
./ossutil64 cp oss://examplebucket/srcobject.png  oss://destbucket  -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

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