You can use the cp command to upload objects from your local computer to OSS.

Note For more information about the format and supported parameters of the cp command, see Overview.

Sample environment

In this topic, local files or folders are uploaded from your local computer to OSS in Linux. You can modify the corresponding parameters based on your operating system and environment. Sample environment:

  • Operating system: Linux
  • Local file: examplefile.txt (file in the root folder)
  • Local folder: localfolder (folder in the root folder)
  • Destination bucket: examplebucket
  • Folder specified by the destination bucket: desfolder

Example for simple upload

  • Upload a single object 
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/
    If the name is not specified for the local file you want to upload, the original name is used by default. If the name of the local file is specified, the object is saved in OSS based on the specified name. Example: 
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/example.txt
  • Upload a folder
    You can add the -r option to the cp command to upload a folder to OSS. 
    ./ossutil cp -r localfolder/ oss://examplebucket/desfolder/
    Note If the object to upload is a symbolic link that points to a local folder, you must add a forward slash (/) to the symbolic link when you use the cp command to upload the object. 
    ./ossutil cp -r symbolic_link/ oss://examplebucket/desfolder/
  • Upload a single object and specify the --meta option.
    When you upload an object, you can use the --meta option to configure object metadata in the header:value#header:value... format. 
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
    Note For more information about how to configure metadata, see set-meta.
  • Upload a folder without uploading the existing objects

    If you specify the --update (abbreviated as -u) option when you upload multiple objects, ossutil only uploads 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. Command: 

    ./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u

    This option can be used to perform incremental upload on objects that fail to be uploaded.

  • Upload an object to a bucket that has pay-by-requester enabled 
    ./ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester
  • Upload only objects in the current folder and ignore subfolders 
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r
  • Do not generate an object for an uploaded folder

    The OSS folder is an object that is 0 KB in size and whose name ends with a forward slash (/). If you specify the --disable-dir-object option when you upload objects, ossutil does not generate an object for the folder to which the objects belong. However, you can view the corresponding folder structure in the OSS console. If you delete objects from the folder, the folder is also deleted. 

    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
  • Upload objects in the subfolder to which the symbolic link points 
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r
  • All objects in the subfolder to which the symbolic link points and the subfolder to which the symbolic link points are ignored during object upload 
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

Set the maximum upload speed

When you upload an object or a folder, you can use the --maxupspeed option to set the maximum upload speed in KB/s. The default value is 0, which indicates that the maximum upload speed is unlimited. Command:
  • Upload an object and set the maximum upload speed to 1 MB/s
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024
  • Upload a folder and set the maximum upload speed to 1 MB/s 
    ./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

Configure object tagging

You can add the --tagging option to configure object tags when you upload objects. Separate multiple tags with ampersands (&). Command: 
./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&……"

For more information about object tagging, see object-tagging.

Set the storage class of objects

When you upload an object, you can use the --meta option to set the storage class of the object. Valid values:
  • Standard
  • IA
  • Archive
IA (Infrequent access) For more information, see Overview. Command:
  • Upload an object and set its storage class to IA 
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA
  • Upload a folder and set the storage class of all objects in the specified folder to Standard 
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

Set ACL of objects

You can use the --meta option to set ACL of objects when you upload objects. Valid values:
  • default: ACL inherited from the bucket
  • private
  • public-read
  • public-read-write
Command:
  • Upload an object and set ACL to private
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta x-oss-object-acl:private
  • Upload a folder and set ACL to public-read
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta x-oss-object-acl:public-read  -r

Specify the server-side encryption method

You can specify the server-side encryption method when you upload an object and store the encrypted object in a bucket. For more information about server-side encryption, see Server-side encryption. Command:
  • Upload an object and set the server-side encryption method to AES-256 
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256
  • Upload an object and set the server-side encryption method to KMS 
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS

    When you use KMS to encrypt an object, OSS creates a customer master key (CMK) in the KMS console for the object and incurs a small amount of fees when the KMS API operation is called. For more information, see KMS billing methods.

Generate snapshot information

If you specify the --snapshot-path option when you upload multiple objects, ossutil generates the snapshot information of the uploaded objects in a specified folder, records and compares the local lastModifiedTime of uploaded or downloaded objects with that of snapshots to determine which objects can be skipped. When you use this option, ensure that the corresponding objects in OSS are not modified between the two uploads or downloads. The ---snapshot-path option is used in specific scenarios to accelerate the incremental upload or download of objects. This option cannot be used to copy objects. This option can be used when the number of objects is large and no other users modify the corresponding objects in OSS between the two uploads. Command: 
./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path
Notice
  • ossutil does not automatically delete snapshot information from the folder specified by snapshot-path. You can remove the folder if you no longer use the snapshot information.
  • Additional overheads are required to read and write snapshot information. We recommend that you do not use this option in the following scenarios: The number of objects to upload or download is small. The network is properly connected. Other users need to perform operations on those objects. In this case, you can use the --update option to perform incremental upload or download.
  • The --update and --snapshot-path options can be used together. ossutil first uses the --snapshot-path option to determine whether to skip the upload or download of an object. If the upload or download is not skipped by --snapshot-path, ossutil uses the --update option to determine whether to skip the upload or download of the object.

Upload multiple objects that meet specified conditions

When you copy multiple objects, you can include the --include and --exclude options in the cp command to specify conditions to match objects. You must specify the --recursive (-r) option at the same time.

The --include and --exclude options support the following formats:
  • *: matches all characters. For example, *.txt specifies any TXT objects.
  • ?: matches any single character. For example, abc?.jpg specifies all JPG objects whose names begin with abc and are followed by any single character such as abc1.jpg.
  • [sequence]: matches any characters in a sequence. For example, abc[1-5].jpg specifies the objects whose names begin with abc and are followed by a number contained in sequence [1-5]. The objects include abc1.jpg, abc2.jpg, abc3.jpg, abc4.jpg, and abc5.jpg.
  • [! sequence]: matches any characters that are not in a sequence. For example, abc[! 0-7].jpg specifies the objects whose names begin with abc and are not followed by a number contained in the sequence [0-7] such as abc8.jpg.
One rule can contain multiple conditions specified by include and exclude. If these conditions are set, ossutil reads each rule from left to right to obtain the final matching results. If the test.txt object exists in a valid folder, results are generated based on different matching rules.
  • Rule 1: --include "*test*" --exclude "*.txt" . When ossutil reads the --include "*test*" condition, the test.txt object matches the condition. When ossutil reads the --exclude "*.txt" condition, the test.txt object is excluded because its name is in the TXT format. The final matching results exclude the test.txt object.
  • Rule 2: --exclude "*.txt" --include "*test*". When ossutil reads the --exclude "*.txt" condition, the test.txt object is excluded. When ossutil reads the --include "*test*" condition, the test.txt object matches the condition because its name contains test. The final matching results include the test.txt object.
  • Rule 3: --include "*test*" --exclude "*.txt" --include "te? t.txt" . When ossutil reads the --include "*test*" condition, the test.txt object matches the condition. When ossutil reads the --exclude "*.txt"condition, the test.txt object is excluded because its name is in the TXT format. When ossutil reads the --include "te? t.txt" condition, the test.txt object matches the condition. The final matching results include the test.txt object.
Note Names that include folders such as --include "/usr/test/.jpg" are not supported.
Command:
  • Upload all objects that are in the TXT format 
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r
  • Upload all objects that contain abc in their names and are not in the JPG or TXT format 
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r