This topic describes how to use the osscmd tool.
Use the osscmd tool
After you have downloaded and decompressed the SDK installation package, you can use the osscmd tool.
You can call Python osscmd to obtain instructions about how to run the commands supported by the osscmd tool. You can use either of the following methods to run each command. The following example shows how to run the gs command to obtain buckets created by a specific user:
- Method 1: The osscmd tool reads the AccessKey ID and AccessKey Secret from the default
file. In this case, you do not need to specify the AccessKey ID and AccessKey Secret.
$ python osscmd gs can't get accessid/accesskey, setup use : config --id=accessid --key=accesskey
Note If a similar output is displayed, the AccessKey ID and AcccessKey Secret fail to be read. For more information about how to specify the AccessKey ID and AccessKey Secret, see Method 2.Ensure that the AccessKey ID and AccessKey Secret are valid. After you specify the AccessKey ID and AccessKey Secret, run the following command:$ python osscmd gs 2013-07-19 08:11 test-oss-sample Bucket Number is: 1
- Method 2: Specify the AccessKey ID and AccessKey Secret in the command. The osscmd
tool reads the AccessKey ID and AccessKey Secret from the command line. If the AccessKey
ID and AccessKey Secret are valid, run the following command:
$ python osscmd gs --id=your_id --key=your_key --host=your_endpoint 2013-07-19 08:11 test-oss-sample Bucket Number is: 1
To configure the AccessKey ID and AccessKey Secret and import them to the default file, run the following command. The default domain name of OSS is oss.aliyuncs.com.
$python osscmd config --id=your_id --key=your_key --host=your_endpoint
If a similar output Your configuration is saved into is displayed, the AccessKey ID and AccessKey Secret have been saved.
Basic operations
- List created buckets
$python osscmd getallbucket
No buckets are displayed if the user has no buckets in OSS.
- Create a bucket
Create a bucket named mybucketname.
$python osscmd createbucket mybucketname
The bucket may fail to be created. The cause is that the name of a bucket must be unique in OSS. You need to use another bucket name. For example, you can add a specific date to the bucket name.
- Check whether a bucket is created
$python osscmd getallbucket
If a bucket fails to be created, check the error message returned from the osscmd tool.
- View objects
After a bucket is created, you can view the objects in the bucket.
$python osscmd list oss://mybucketname/
If there are no objects in the bucket, no objects are displayed.
- Upload a file
Upload a local file to a bucket. If a local file is named local_existed_file, run the following commands to calculate the MD5 value of the file and upload the local file to the bucket:
$ md5sum local_existed_file 7625e1adc3a4b129763d580ca0a78e44 local_existed_file $ python osscmd put local_existed_file oss://mybucketname/test_object
Notemd5sum
runs in Linux only. - View objects again
You can view objects that have been uploaded to a bucket.
$python osscmd list oss://mybucketname/
- Download an object
Download an object from a bucket to a local file. Compare the MD5 value of the object that is downloaded with the object MD5 value calculated before the object is downloaded.
$ python osscmd get oss://mybucketname/test_object download_file $ md5sum download_file 7625e1adc3a4b129763d580ca0a78e44 download_file
Notemd5sum
runs in Linux only. - Delete an object
$ python osscmd delete oss://mybucketname/test_object
- Delete a bucket
Note If a bucket contains objects, the bucket cannot be deleted.
$ python osscmd deletebucket mybucketname
Use lifecycle
- Create a TXT file and save it as an XML file. Use the XML file to configure lifecycle
rules.
<LifecycleConfiguration> <Rule> <ID>1125</ID> <Prefix>log_backup/</Prefix> <Status>Enabled</Status> <Expiration> <Days>2</Days> </Expiration> </Rule> </LifecycleConfiguration>
If you run the preceding code, objects whose names are prefixed with log_backup/ and that are retained for two days from their last modification time are deleted. For more information about the configuration of lifecycle rules, see API Reference.
- Write a lifecycle rule.
python osscmd putlifecycle oss://mybucket lifecycle.xml 0.150(s) elapsed
- Read a lifecycle rule.
python osscmd getlifecycle oss://mybucket <? xml version="1.0" encoding="UTF-8"? > <LifecycleConfiguration> <Rule> <ID>1125</ID> <Prefix>log_backup/</Prefix> <Status>Enabled</Status> <Expiration> <Days>2</Days> </Expiration> </Rule> </LifecycleConfiguration> 0.027(s) elapsed
- Delete a lifecycle rule.
python osscmd deletelifecycle oss://mybucket 0.139(s) elapsed
- Read a lifecyle rule.
python osscmd getlifecycle oss://mybucket Error Headers: [('content-length', '288'), ('server', 'AliyunOSS'), ('connection', 'close'), ('x-oss-request-id', '54C74FEE5D7F6B24E5042630'), ('date', 'Tue, 27 Jan 2015 08:44:30 GMT'), ('content-type', 'application/xml')] Error Body: <? xml version="1.0" encoding="UTF-8"? > <Error> <BucketName>mybucket</BucketName> <Code>NoSuchLifecycle</Code> <Message>No Row found in Lifecycle Table. </Message> <RequestId>54C74FEE5D7F6B24E5042630</RequestId> <HostId>mybucket.oss-maque-hz-a.alibaba.net</HostId> </Error> Error Status: 404 getlifecycle Failed!
Configure hotlinking protection
- Allow access from a request that has an empty Referer field.
$osscmd putreferer oss://test --allow_empty_referer=true 0.004(s) elapsed
- Obtain the Referer whitelist.
$osscmd getreferer oss://test <? xml version="1.0" encoding="UTF-8"? > <RefererConfiguration> <AllowEmptyReferer>true</AllowEmptyReferer> <RefererList /> </RefererConfiguration>
- The Referer field is required. Only requests that have the Referer field value of
www.example.com are allowed.
$osscmd putreferer oss://test --allow_empty_referer=false --referer='www.example.com' 0.092(s) elapsed
- Obtain the Referer whitelist.
$osscmd getreferer oss://test <? xml version="1.0" encoding="UTF-8"? > <RefererConfiguration> <AllowEmptyReferer>false</AllowEmptyReferer> <RefererList> <Referer>www.example.com</Referer> </RefererList> </RefererConfiguration>
- The Referer field is required. Only requests that have the Referer field value of
www.example.com or www.example.org are allowed.
$osscmd putreferer oss://test --allow_empty_referer=false --referer='www.example.com,www.example.org'
- Obtain the Referer whitelist.
$osscmd getreferer oss://test <? xml version="1.0" encoding="UTF-8"? > <RefererConfiguration> <AllowEmptyReferer>false</AllowEmptyReferer> <RefererList> <Referer>www.example.com</Referer> <Referer>www.example.org</Referer> </RefererList> </RefererConfiguration>
Use logging
- Configure a logging rule
$osscmd putlogging oss://mybucket oss://myloggingbucket/mb
- Obtain logging rules that are configured for a bucket
$osscmd getlogging oss://mybucket