The cp command is used to upload, download, or copy objects.

Note The commands described in this topic apply to Linux. To use the commands in other systems, replace ./ossutil in the command with the actual executable program name. For example, you can use the help command in 32-bit Windows systems by running ossutil32.exe help.

Command syntax

  • Upload objects
    ./ossutil cp file_url cloud_url  [-r] [-f] [-u] [--enable-symlink-dir] [--disable-all-symlink] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir] [--payer requester] [--tagging]
    Use the cp command to upload local files to OSS:
    • file_url: the path of the local file. Examples: The path of the local file in Linux is /localfolder/examplefile.txt. The path of the local file in Windows is D:\localfolder\examplefile.txt.
    • cloud_url: the path of objects in OSS. The format is oss://bucketname/objectname. Example: oss://examplebucket/examplefile.txt.
  • Download objects
    ./ossutil cp cloud_url file_url  [-r] [-f] [-u] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--range=x-y] [--payer requester] [--version-id versionId]
  • Copy objects
    ./ossutil cp cloud_url cloud_url [-r] [-f] [-u] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--payer requester] [--version-id versionId] [--tagging]

Examples

Performance optimization

You can add the --jobs and --parallel options to the cp command to specify the number of concurrent operations. If the default number of concurrent operations set by ossutil does not meet your performance requirements, you can modify the values of these two options to adjust the performance.
  • --jobs: specifies the number of concurrent jobs when multiple objects are uploaded, downloaded, or copied.
  • --parallel: specifies the number of concurrent operations performed on an object during multipart upload, download, or copy.
By default, ossutil calculates the number of concurrent operations based on the object size. When you upload, download, or copy multiple large objects, the actual number of concurrent operations is calculated by multiplying the number of concurrent jobs by the number of concurrent operations.
  • We recommend that you adjust the number of concurrent operations 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, memory, and CPU are available, you can increase the number of concurrent operations.
  • If you specify a large number of concurrent operations, inter-thread resource switching and snatching may degrade the upload, download, and copy performance of ossutil or lead to an EOF error. To resolve this issue, you must adjust the values of the --jobs and --parallel options based on the actual conditions. To perform stress testing, set the two options to small values at first, and slowly adjust them to the optimal values.

Common options

The following table describes the options you can add to the cp command.
Option Description
-r, --recursive Performs operations on objects in a bucket. If this option is specified, commands that support this option are run to perform operations on all objects in a bucket that meet the specified conditions. If this option is not specified, commands that support this option are run to perform operations only on the specified object.
-f, --force Forces an operation without prompting the user for confirmation.
-u, --update Specifies that ossutil only uploads, downloads, or copies objects that do not exist in the destination bucket or objects whose last modified time is later than that of their corresponding objects in the destination bucket.
--output-dir Specifies the folder in which the output objects are located. Output objects include report objects generated due to errors that occur when you use the cp command to copy multiple objects. The default value is the ossutil_output folder in the current folder.
--bigfile-threshold Specifies the size of a large object for which to start resumable data transfer. Unit: bytes. Default value: 100 MB. Valid values: non-negative integers.
--part-size Specifies the part size in bytes. By default, ossutil calculates the appropriate part size based on the object size. You can set this option to any positive integer if you need to optimize performance or operate under special constraints.
--checkpoint-dir Specifies the checkpoint folder. Default value: .ossutil_checkpoint. If a resumable data transfer task fails, ossutil automatically creates this folder and records the checkpoint information in the folder. If a resumable data transfer task succeeds, ossutil deletes this folder. If this option is specified, ensure that you have the permissions to delete the specified folder.
--range Specifies the byte range of the object to be downloaded. Bytes are numbered from 0.
  • You can specify a range. For example, 3-9 indicates a range from byte 3 to byte 9, which includes byte 3 and byte 9.
  • You can specify the field from which the download starts. For example, 3- indicates a range from byte 3 to the end of the object, which includes byte 3.
  • You can specify the field with which the download ends. For example, -9 indicates a range from byte 0 to byte 9, which includes byte 9.
--encoding-type Specifies the encoding type of the object name. If this option is specified, this value must be url. If this option is not specified, the object name is not encoded. Bucket names cannot be URL-encoded.
--include Includes objects that match a specific string such as *.jpg.
--exclude Excludes objects that match a specified string such as *.txt.
--meta Specifies the metadata of an object in the [header:value#header:value...] format. Example: Cache-Control:no-cache#Content-Encoding:gzip. For more information, see set-meta.
--acl Configures ACL for an object. Valid values:
  • default: ACL inherited from the bucket
  • private
  • public-read
  • public-read-write
--snapshot-path If you specify the --snapshot-path option when you upload or download multiple objects, ossutil takes a snapshot of the upload or download and stores the snapshot information in a specified folder. The next time the objects are uploaded or downloaded while this option is specified, ossutil reads the snapshot information from the specified folder and performs incremental upload or download. For more information, see Generate snapshot information.
--disable-crc64 Disables CRC-64. By default, ossutil enables CRC-64 during data transfer.
--maxupspeed Specifies the maximum upload speed. Unit: KB/s. Default value: 0. 0 indicates that the maximum upload speed is unlimited.
--payer Specifies the payer of the request. If pay-by-requester is enabled, you can set this option to requester.
--partition-download Specifies the partition you want to download. The value of this option is in the "partition number: the total number of partitions" format. A value of 1:5 indicates that ossutil downloads partition 1 out of the total five partitions. Partitions are numbered from 1. Partitioning rules for objects are determined by ossutil. This option splits an object to download into multiple partitions that can be downloaded by multiple ossutil commands. Each ossutil command downloads their own partition. You can run multiple ossutil commands on different machines at the same time.
-j, --jobs Specifies the number of concurrent jobs performed across multiple objects. Default value: 3. Valid values: 1 to 10000.
--parallel Specifies the number of concurrent operations performed on a single object. Valid values: 1 to 10000. By default, ossutil sets the value of this option based on the operation type and object size.
--loglevel Specifies the log level. This parameter is empty by default, which indicates that no log files are generated. Valid values:
  • info: generates prompt logs.
  • debug: generates detailed logs that contain corresponding HTTP request and response information.
--retry-times Specifies the number of times an operation is retried if the operation fails. Default value: 10. Valid values: 1 to 500.
--version-id Specifies the version ID of an object you want to download or copy. You can use this option for objects only in a bucket that has versioning enabled.
--proxy-host Specifies the URL of the proxy server. HTTP, HTTPS, and SOCKS5 proxies are supported. Examples: http://120.79. **.**:3128 and socks5://120.79. **. **:1080.
--proxy-user Specifies the username of the proxy server. This parameter is empty by default.
--proxy-pwd Specifies the password of the proxy server. This parameter is empty by default.
--local-host Specifies the local IP address of ossutil. If your computer has multiple IP addresses, you can specify this option so that ossutil can access OSS by using the specified IP address.
--enable-symlink-dir Specifies whether to upload the subfolder of the symbolic link. By default, the subfolder is not uploaded. The probe command can be used to check whether an object or a folder to which the symbolic link points is also a symbolic link.
--only-current-dir Specifies that only objects in the current folder are uploaded, downloaded, or copied. The subfolders in the current folder ignored.
--disable-dir-object Specifies that no OSS object is generated for the folder during object upload.
--disable-all-symlink Specifies that all objects in the subfolder and the subfolder to which the symbolic link points are ignored during object upload.
--tagging Specifies the object tag when you upload or copy an object in the "abc=1&bcd=2&……" format.
--disable-ignore-error Specifies that errors are not ignored during batch operations.
Note For more information about common options, see View options.