Object Storage Service:ossutil 2.0 CLI

Quick start

To use the ossutil 2.0 command line interface, you need to:

Configure ossutil

To avoid errors from missing settings, we recommend using the ossutil config wizard to quickly configure your AccessKey ID, AccessKey Secret, and region ID. For advanced options, see the Configuration guide to manually configure access credentials.

This example shows how to use the configuration wizard to quickly configure the AccessKey pair of a RAM user as your access credentials.

Run commands

1. Create a bucket.

   ossutil mb oss://examplebucket

   The following output indicates that the bucket examplebucket was created.

   0.668238(s) elapsed

2. Upload a file to the bucket.

   1. Create a local file named uploadFile.txt.

      echo 'Hello, OSS!' > uploadFile.txt

   2. Upload a file to the examplebucket bucket.

      ossutil cp uploadFile.txt oss://examplebucket

      The following output indicates that the file has been successfully uploaded to examplebucket.

      Success: Total 1 file, size 12 B, Upload done:(1 objects, 12 B), avg 44 B/s
      
      0.271779(s) elapsed

3. Download a file.

   Download the uploadFile.txt file from the examplebucket bucket to the localfolder directory.

   ossutil cp oss://examplebucket/uploadFile.txt localfolder/

   The following output indicates that the file was successfully downloaded to the localfolder directory.

   Success: Total 1 object, size 12 B, Download done:(1 files, 12 B), avg 74 B/s
   
   0.162447(s) elapsed

4. List the files in the examplebucket bucket.

   ossutil ls oss://examplebucket

   The following output indicates that the files in the examplebucket bucket were successfully listed.

   LastModifiedTime                   Size(B)  StorageClass   ETAG                                  ObjectName
   2024-11-26 14:35:29 +0800 CST           12      Standard   1103F650EB2C292D179A032D2A97B0F5      oss://examplebucket/uploadFile.txt
   Object Number is: 1
   
   0.124679(s) elapsed

5. Delete the uploadFile.txt file from the examplebucket bucket.

   ossutil rm oss://examplebucket/uploadFile.txt

   The following output indicates that uploadFile.txt was successfully deleted from the examplebucket bucket.

   0.295530(s) elapsed

6. Delete the examplebucket bucket.

   ossutil rb oss://examplebucket

   The following output indicates that the examplebucket bucket was successfully deleted.

   0.478659(s) elapsed

Configuration

ossutil is highly flexible and can be configured using a configuration file, environment variables, or command-line options.

Configuration precedence

ossutil reads settings in the following order of precedence:

command-line options (such as -i, -k, and -e) > environment variables (such as OSS_ACCESS_KEY_ID) > configuration file (~/.ossutilconfig)

Configuration file

You can configure ossutil by using a configuration file. The default path is ~/.ossutilconfig, or you can specify a custom path by using the -c flag. If you use the default configuration file, you can run ossutil commands directly without specifying the file path. For example:

ossutil ls oss://examplebucket

If you use a custom configuration file path, such as /path/yourconfig, you must use the -c option to specify the path. For example:

ossutil -c /path/yourconfig ls oss://examplebucket

[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"

[buckets name]
bucket-name = 
  key=value

[buckets dev-bucket]
bucket-hz-01 = 
  region=cn-hangzhou
bucket-hz-02 = 
  region=cn-hangzhou
  endpoint=test.com
  addressing-style=cname
bucket-bj-01 = 
  region=cn-beijing

Configure environment variables

The following environment variables are supported:

Command-line options

ossutil provides multiple command-line options, including global command-line options. Command-line options have the highest precedence and override parameters set in the configuration file or environment variables.

ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret" --region cn-hangzhou

Access credentials

RAM user AccessKey pair

If your application runs in a secure environment, requires long-term access to OSS, and cannot rotate credentials frequently, you can initialize the credential provider with the AccessKey pair (AccessKey ID and AccessKey Secret) of an Alibaba Cloud account or a RAM user. This method requires manual maintenance of an AccessKey pair, which increases both security risks and maintenance overhead.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourAccessKeyID -k yourAccessKeySecret

Temporary security credential

If your application requires temporary access to OSS, you can initialize the credential provider with a temporary security credential (AccessKey ID, AccessKey Secret, and security token) obtained from Security Token Service (STS). This method requires manual maintenance of the security token, increasing security risks and complexity. You must also refresh the token manually for repeated temporary access.

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourSTSAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourSTSAccessKeySecret
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourSTSAccessKeyID -k yourSTSAccessKeySecret -t yourSecurityToken --region cn-hangzhou

RAM role ARN

If your application needs authorized access to OSS, for example, to access OSS across Alibaba Cloud accounts, you can use RAMRoleARN to initialize the credential provider. This method uses STS tokens internally. By specifying the ARN (Alibaba Cloud Resource Name) of a RAM role, the credentials tool obtains an STS token from the STS service and calls the AssumeRole API to request a new STS token before the session expires. In addition, you can assign a value to policy to restrict the RAM role to a smaller set of permissions.

Create the following configuration file and save it as ~/.ossutilconfig. This configuration cannot be set by using environment variables or command-line options.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=ap-southeast-1

To query objects in the examplebucket bucket, run the following command:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ECS instance RAM role

If your application runs on an ECS instance, an ECI instance, or a worker node of Container Service for Kubernetes, we recommend that you use an ECSRAMRole to initialize the credential provider. This method uses STS tokens in its underlying implementation. An ECSRAMRole allows you to associate a role with an ECS instance, an ECI instance, or a worker node of Container Service for Kubernetes to automatically refresh the STS token within the instance. This method eliminates the need to provide an AccessKey (AK) or an STS token and removes the risks associated with manual maintenance. For more information about how to obtain an ECSRAMRole, see Create a role.

EcsRamRole mode

[default]
mode = EcsRamRole
# The ecsRoleName parameter is optional. If it is not set, the role is automatically obtained.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode EcsRamRole

EcsRamRole IMDSv2 mode

[default]
mode = Ali-EcsRamRole
# The ecsRoleName parameter is optional. If it is not set, the role is automatically obtained.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode Ali-EcsRamRole

OIDC role ARN

After you configure a worker node RAM role in Container Service for Kubernetes, applications in Pods on that node can obtain the STS token for the associated role through the metadata service, just like applications deployed on ECS instances. However, if untrusted applications, such as applications submitted by customers with closed-source code, are deployed on the container cluster, you may not want them to obtain the STS token of the RAM role that is associated with the worker node instance through the metadata service. To avoid compromising the security of your cloud resources while allowing these untrusted applications to securely obtain the required STS tokens and implement application-level least privilege, you can use the RRSA (RAM Roles for Service Account) feature. This method is based on STS tokens. The Alibaba Cloud container cluster creates and mounts a corresponding service account OIDC token file for each application Pod and injects the related configuration information into environment variables. A credentials tool then retrieves the configuration information from the environment variables and calls the AssumeRoleWithOIDC API of the STS service to exchange the OIDC token for an STS token that is associated with the role. This method does not require you to provide an Access Key (AK) or an STS token, which eliminates the risks associated with manually maintaining AKs or STS tokens. For more information, see Configure RAM permissions for a ServiceAccount by using RRSA to implement pod-level permission isolation.

Create the following configuration file and save it as ~/.ossutilconfig. You cannot specify this configuration by using environment variables or command-line options.

[default]
mode = oidcRoleArn
# Specifies the ARN (Aliyun Resource Name) of the OIDC provider. The format is acs:ram::account-id:oidc-provider/provider-name.
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Specifies the file path where the OIDC token is stored.
OIDCTokenFilePath=OIDCTokenFilePath
# The ARN of the role to assume. The format is acs:ram::account-id:role/role-name.
roleArn=acs:ram::113511544585****:role/testoidc
# A custom role session name to distinguish different tokens.
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

Run the following command to query objects in examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

External process credentials

ossutil can execute an external command to obtain credentials. The external process returns the credentials to ossutil through standard output (stdout).

The external command can return a long-term credential or a temporary credential in the following formats.

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk"
}

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2023-12-29T07:45:02Z",
  "SecurityToken" : "token"
}

Create the following configuration file and save it to ~/.ossutilconfig. These settings cannot be configured by using environment variables or command-line options.

[default]
mode = Process
credentialProcess = user-cmd
region=ap-southeast-1

Run the following command to query objects in the examplebucket bucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Anonymous access

If you only need to access OSS resources with the public-read permission, you can use anonymous access without providing any credentials.

ossutil cat oss://bucket/public-object --mode Anonymous

Command reference

ossutil provides three types of commands: high-level commands, API-level commands, and helper commands.

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

{
  "CORSRule": {
    "AllowedOrigin": ["www.aliyun.com"],
    "AllowedMethod": ["PUT","GET"],
    "MaxAgeSeconds": 10000
  }
}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json

{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"

cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -

ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
  <ResponseVary>false</ResponseVary>
</CORSConfiguration>

ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
  "CORSRule": {
    "AllowedMethod": [
      "PUT",
      "GET"
    ],
    "AllowedOrigin": "www.aliyun.com",
    "MaxAgeSeconds": "10000"
  },
  "ResponseVary": "false"
}

ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
  "PUT",
  "GET"
]

ossutil stat oss://bucketexample
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131072
...
StandardObjectCount         : 119212
StandardStorage             : 66756852803
Storage                     : 66756852813
StorageClass                : Standard
TransferAcceleration        : Disabled

ossutil stat oss://bucketexample --human-readable
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131.072k
...
StandardObjectCount         : 119.212k
StandardStorage             : 66.757G
Storage                     : 66.757G
StorageClass                : Standard
TransferAcceleration        : Disabled

Command-line options

Some commands require parameters to specify a target or an option. For these commands, provide the required values. For example:

ossutil ls --profile dev

The command ossutil ls --profile dev specifies the dev configuration profile. For options that require a parameter value, separate the option name from the value with a space or an equal sign (=), such as --profile dev or --profile=dev. Enclose parameter values that contain spaces in double quotation marks to ensure they are parsed correctly, for example, --description "OSS bucket list".

FAQ

Ossutil error: region must be set in sign version 4

Cause: You did not specify the region ID when you configured ossutil 2.0.

Solution: To prevent errors, configure the following required items: AccessKey ID, AccessKey Secret, and region ID. The region ID is required because the signature version has been upgraded to V4. For more information on obtaining a region ID, see Regions and endpoints.