This topic describes how to use the osscmd tool.

Notice Commands supported by the osscmd tool have been integrated with the ossutil tool. The osscmd tool is no longer available for download as of July 31, 2019.

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
    Note md5sum 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
    Note md5sum 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 test are allowed.
    $osscmd putreferer oss://test --allow_empty_referer=false --referer='www.test.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.test.com</Referer>
      </RefererList>
    </RefererConfiguration>
  • The Referer field is required. Only requests that have the Referer field value of test or test1 are allowed.
    $osscmd putreferer oss://test --allow_empty_referer=false --referer='www.test.com,www.test1.com'
  • Obtain the Referer whitelist.
    $osscmd getreferer oss://test
    <? xml version="1.0" encoding="UTF-8"? >
    <RefererConfiguration>
      <AllowEmptyReferer>false</AllowEmptyReferer>
      <RefererList>
        <Referer>www.test.com</Referer>
        <Referer>www.test1.com</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