Object Storage Service:ossutil command-line interface 2.0

Quick integration

To get started with the ossutil 2.0 command line interface, follow these steps:

Configure ossutil

To prevent operation failures caused by missing configurations, you can use the `ossutil config` command wizard to quickly configure your AccessKey ID, AccessKey secret, and region ID. To manage advanced configurations, see the Configuration guide for information about how to manually configure access credentials.

The following 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 `examplebucket` bucket is 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 the file to the examplebucket bucket.

      ossutil cp uploadFile.txt oss://examplebucket

      The following output indicates that the file is uploaded to the examplebucket bucket.

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

3. Download the file.

   Download the `uploadFile.txt` sample file from the `examplebucket` bucket to the local `localfolder` folder.

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

   The following output indicates that the file is downloaded to the local `localfolder` folder.

   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 are 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 `uploadFile.txt` from the `examplebucket` bucket.

   ossutil rm oss://examplebucket/uploadFile.txt

   The following output indicates that `uploadFile.txt` is 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 is deleted. 0.478659s elapsed

   0.478659(s) elapsed

Configuration guide

ossutil supports configuration through configuration files, environment variables, and command-line options. This provides a high degree of flexibility.

Configuration precedence

ossutil reads configurations 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 using a configuration file (the default path is ~/.ossutilconfig, or you can specify a custom path with the -c option). If you use the default configuration file, you do not need to specify the file path and can run ossutil commands directly. Example:

ossutil ls oss://examplebucket

If you use a custom configuration file path, such as /path/yourconfig, you must specify the path with the -c option. 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

You can configure environment variables by following these steps.

The following environment variables can be configured:

Configure command-line options

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

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

Access credential configuration

Use the AccessKey pair of a RAM user

If your application runs in a secure and stable environment that is not susceptible to external attacks, 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 you to manually maintain an AccessKey pair, which increases security risks and maintenance complexity.

[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

Use an STS token

If your application requires temporary access to OSS, you can initialize the credential provider with temporary identity credentials (AccessKey ID, AccessKey secret, and Security Token) obtained from the STS service. This method requires you to manually maintain an STS token, which increases security risks and maintenance complexity. Additionally, to access OSS temporarily multiple times, you must manually refresh the STS token.

[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

Use a RAMRoleARN

If your application requires authorized access to OSS, such as cross-account access, you can initialize the credential provider with a RAMRoleARN. This method is based on STS tokens. By specifying the Alibaba Cloud Resource Name (ARN) of a RAM role, the credentials tool requests an STS token from the STS service and calls the AssumeRole operation to apply for a new STS token before the current session expires. You can also assign a value to the policy parameter to restrict the RAM role to a smaller set of permissions.

Create the following configuration file and save it as ~/.ossutilconfig. This method is not supported through 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

Run the following command to query objects in the `examplebucket` bucket.

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

Use an EcsRamRole

If your application runs on an ECS instance, an ECI instance, or a worker node of Container Service for Kubernetes, we recommend that you initialize the credential provider with an EcsRamRole. This method is based on STS tokens. EcsRamRole lets you 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 does not require you to provide an AccessKey pair or an STS token, which eliminates the risks of manual maintenance. For more information about how to obtain an EcsRamRole, see CreateRole.

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

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

ossutil ls oss://examplebucket --mode EcsRamRole

Use an OIDCRoleARN

After you configure a RAM role for worker nodes in Container Service for Kubernetes, applications in pods on those nodes can obtain the STS token for the associated role through the Metadata Server, similar to applications deployed on ECS instances. However, if you deploy untrusted applications on the cluster, such as applications submitted by customers with unvetted code, you may not want them to access the STS token of the instance RAM role that is associated with the worker node. To protect your cloud resources while allowing these untrusted applications to securely obtain the necessary STS tokens and achieve application-level permission minimization, you can use the RAM Roles for Service Accounts (RRSA) feature. This method is based on STS tokens. The Alibaba Cloud container cluster creates and mounts a corresponding service account OIDC token file for different application pods and injects the relevant configuration information into environment variables. The credentials tool retrieves this configuration from the environment variables and calls the `AssumeRoleWithOIDC` operation of STS to exchange the OIDC token for an STS token for the bound role. This method eliminates the risk of manually maintaining an AccessKey pair or an STS token. For more information, see Pod permission isolation based on RRSA.

Create the following configuration file and save it as ~/.ossutilconfig. This method is not supported through environment variables or command-line options.

[default]
mode = oidcRoleArn
# Specifies the Alibaba Cloud Resource Name (ARN) 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 for the OIDC token.
OIDCTokenFilePath=OIDCTokenFilePath
# Enter the ARN of the role to assume. The format is acs:ram::113511544585****:oidc-provider/TestOidcProvider.
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 the `examplebucket` bucket.

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

Obtain credentials from an external process

ossutil can start an independent external process using an external command. The external process runs and returns its result to ossutil through standard output. You can use an external process to obtain credentials.

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

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

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

Generate the following configuration file and save it to ~/.ossutilconfig. You cannot configure these settings using environment variables or command-line options.

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

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

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

Anonymous Access

If you only need to access OSS resources that have 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

In command-line operations, some commands require additional parameters to specify the target of the operation or to set options, whereas other commands do not. For commands that take parameters, you can provide appropriate parameter values to achieve the desired functionality. For example:

ossutil ls --profile dev

The command ossutil ls --profile dev allows the user to specify a particular configuration profile using the parameter value dev. Options that take parameters usually require a space or an equal sign (`=`) to separate the option name from the parameter value, such as --profile dev or --profile=dev. If a parameter value contains spaces, you must enclose the entire value in double quotation marks to ensure that the command is parsed correctly, such as --description "OSS bucket list".

FAQ

When I run an ossutil command, the error "region must be set in sign version 4" is reported

Cause: The region ID was not configured when you configured ossutil 2.0.

Solution: To prevent operation failures caused by missing configuration items when you use ossutil, make sure that you configure the necessary basic items: AccessKey ID, AccessKey secret, and region ID. The region ID is especially important because the signature has been upgraded to V4, which makes it a required item. For more information about how to obtain a region ID, see Regions and endpoints.