Object Storage Service:ossutil 2.0

Quick integration

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

Configure ossutil

To prevent operation failures that are caused by missing configurations, 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 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.

      ossutil cp uploadFile.txt oss://examplebucket

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

      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 to the localfolder.

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

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

   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.

   ossutil ls oss://examplebucket

   The following output indicates that the files in the examplebucket 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.

   ossutil rm oss://examplebucket/uploadFile.txt

   The following output indicates that uploadFile.txt is deleted from the examplebucket.

   0.295530(s) elapsed

6. Delete the examplebucket.

   ossutil rb oss://examplebucket

   The following output indicates that the examplebucket is deleted.

   0.478659(s) elapsed

Configuration guide

ossutil supports configuration via configuration files, environment variables, and command-line options, offering 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 for this file is ~/.ossutilconfig, but you can specify a custom path with the -c option. If you use the default configuration file, you do not need to specify its path and can run ossutil commands directly. For example:

ossutil ls oss://examplebucket

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

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 global command-line options. These 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" --region cn-hangzhou

Access credential configuration

Use the AccessKey pair of a RAM user

If your application operates in a secure, stable environment that is resistant to external attacks, requires long-term access to OSS, and cannot frequently rotate credentials, initialize the credential provider using the AccessKey pair (AccessKey ID and AccessKey secret) from an Alibaba Cloud account or a RAM user. However, this approach necessitates manual maintenance of the AccessKey pair, thereby increasing 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—such as an AccessKey ID, an AccessKey secret, and a security token—obtained from the STS service. This method requires you to manually maintain the STS token, which increases both security risks and maintenance complexity. Additionally, you must manually refresh the STS token each time you need to access OSS temporarily.

[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

Use a RAMRoleARN

If your application requires authorized access to OSS, such as for cross-account access, you can initialize the credential provider by specifying a RAMRoleARN. This method uses Security Token Service (STS) tokens. By specifying the Alibaba Cloud Resource Name (ARN) of a RAM role, the provider calls the AssumeRole operation to obtain a temporary token and automatically renews it before the session expires. You can also set the policy parameter to further restrict the permissions for the session.

Generate the following configuration file and save it as ~/.ossutilconfig. You cannot configure these settings 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

Run the following command to query objects in the examplebucket.

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, you can initialize the credential provider with an EcsRamRole. This method is based on Security Token Service (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.

EcsRamRole mode

[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

EcsRamRole IMDSv2pattern

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

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

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

Use an OIDCRoleARN

After you assign a RAM role to worker nodes in Container Service for Kubernetes, applications running in pods on those nodes can retrieve the STS token for the associated role from the metadata service (Metadata Server), just as applications deployed on ECS instances do. However, if you deploy untrusted applications on the cluster—such as customer-submitted applications whose source code is not open—those applications might obtain the STS token for the worker node’s instance RAM role from the metadata service. To prevent security risks to your cloud resources and enable untrusted applications to securely retrieve the required STS tokens while enforcing application-level least privilege, use the RAM Roles for Service Accounts (RRSA) feature. This method uses an STS token under the hood. An ACK cluster creates and mounts an OpenID Connect (OIDC) token file for each application pod and injects relevant configuration information into environment variables. The Credentials tool retrieves this configuration from the environment variables and calls the STS AssumeRoleWithOIDC operation to obtain the STS token for the attached role. Because this method does not require an AccessKey pair or a pre-existing STS token, it eliminates risks associated with manual maintenance. For more information, see Pod permission isolation based on RRSA.

Create the following configuration file and save it as ~/.ossutilconfig. You cannot configure this using 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.

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

Obtain credentials from an external process

ossutil can start an independent external process by executing an external command. This process runs and returns its result to ossutil via standard output. You can use such an external process to obtain credentials.

You can use an external command to retrieve 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

You can run the following command to query the objects in the examplebucket:

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

Anonymous access

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

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

Command reference

You can use ossutil to run 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 command-line operations require additional parameters to specify the target or set options, while others do not. For commands that take parameters, provide appropriate parameter values to achieve the desired functionality. For example:

ossutil ls --profile dev

The command ossutil ls --profile dev lets you specify a particular configuration file 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 set up ossutil 2.0.

Solution: To prevent operation failures due to missing configuration items when using ossutil, ensure 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, making it a required item. For more information about how to obtain a region ID, see Regions and endpoints.