You can use the cp command to upload objects from your local computer to OSS.
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
- 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
./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
- Standard
- IA
- Archive
- 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
- default: ACL inherited from the bucket
- private
- public-read
- public-read-write
- 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
- 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
./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path
- 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.
- *: 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.
- 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.
--include "/usr/test/.jpg"
are not supported.
- 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