命令行工具ossutil 2.0

快速接入

接入命令行工具ossutil 2.0的流程如下：

配置ossutil

为避免因配置缺失导致操作失败，推荐使用 ossutil config 命令的配置向导快速完成 AccessKey ID、AccessKey Secret 和地域 ID 的配置。若还需管理高级配置，可参考配置指南进行手动配置访问凭证等。

以使用 RAM 用户的 AccessKey 配置为访问凭证为示例，结合配置向导快速完成配置。

运行命令

1. 创建Bucket。

   ossutil mb oss://examplebucket

   以下输出结果表明已成功创建examplebucket。

   0.668238(s) elapsed

2. 上传文件到Bucket。

   1. 创建本地文件uploadFile.txt。

      echo 'Hello, OSS!' > uploadFile.txt

   2. 上传文件到存储空间examplebucket。

      ossutil cp uploadFile.txt oss://examplebucket

      以下输出结果表明文件已成功上传至examplebucket。

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

3. 下载文件。

   将已上传的示例文件uploadFile.txt从examplebucket下载至本地localfolder文件夹下。

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

   以下输出结果表明文件已成功下载至本地localfolder文件夹下。

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

4. 列举examplebucket下的文件。

   ossutil ls oss://examplebucket

   以下输出结果表明已成功列举examplebucket下的文件。

   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. 删除examplebucket下的uploadFile.txt。

   ossutil rm oss://examplebucket/uploadFile.txt

   以下输出结果表明已成功删除examplebucket下的uploadFile.txt。

   0.295530(s) elapsed

6. 删除examplebucket。

   ossutil rb oss://examplebucket

   以下输出结果表明已成功删除examplebucket。

   0.478659(s) elapsed

配置指南

ossutil 支持通过配置文件、环境变量和命令行选项进行配置，灵活性高。

配置的优先级

ossutil 按以下顺序读取配置：

命令行选项 (如 -i, -k, -e) > 环境变量 (如 OSS_ACCESS_KEY_ID) > 配置文件 (~/.ossutilconfig)

配置文件

可以利用配置文件（默认路径为 ~/.ossutilconfig，或通过 -c 选项指定自定义路径）配置 ossutil。如果使用默认配置文件，则不需要额外指定配置文件路径。直接运行 ossutil 命令即可，例如：

ossutil ls oss://examplebucket

如果使用自定义配置文件路径，例如 /path/yourconfig，则需要通过 -c 选项指定配置文件路径。例如：

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

配置环境变量

可以参照以下步骤配置环境变量。

当前支持配置的环境变量如下：

配置命令行选项

ossutil提供了多个命令行选项，支持配置全局命令行选项。命令行选项的优先级最高，可以覆盖配置文件设置或环境变量设置的参数。

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

访问凭证配置

使用 RAM 用户的 AK

如果应用程序部署运行在安全、稳定且不易受外部攻击的环境中，需要长期访问的OSS，且不能频繁轮转凭证时，可以使用阿里云主账号或RAM用户的AK（Access Key ID、Access Key Secret）初始化凭证提供者。需要注意的是，该方式需要手动维护一个AK，存在安全性风险和维护复杂度增加的风险。

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=cn-hangzhou

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

使用STS临时访问凭证

如果应用程序需要临时访问OSS，可以使用通过STS服务获取的临时身份凭证（Access Key ID、Access Key Secret和Security Token）初始化凭证提供者。需要注意的是，该方式需要手动维护一个STS Token，存在安全性风险和维护复杂度增加的风险。此外，如果需要多次临时访问OSS，需要手动刷新STS Token。

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=cn-hangzhou

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

使用RAMRoleARN

如果应用程序需要授权访问OSS，例如跨阿里云账号访问OSS，可以使用RAMRoleARN初始化凭证提供者。该方式底层实现是STS Token。通过指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具会前往STS服务获取STS Token，并在会话到期前调用AssumeRole接口申请新的STS Token。此外，还可以通过为policy赋值来限制RAM角色到一个更小的权限集合。

生成如下配置文件，并保存在~/.ossutilconfig。不支持通过环境变量或者命令行选项方式设置。

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

通过如下命令查询examplebucket中的对象。

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

使用ECSRAMRole

如果应用程序运行在ECS实例、ECI实例、容器服务Kubernetes版的Worker节点中，建议使用ECSRAMRole初始化凭证提供者。该方式底层实现是STS Token。ECSRAMRole允许将一个角色关联到ECS实例、ECI实例或容器服务 Kubernetes 版的Worker节点，实现在实例内部自动刷新STS Token。该方式无需提供一个AK或STS Token，消除了手动维护AK或STS Token的风险。如何获取ECSRAMRole，请参见CreateRole - 创建角色。

[default]
mode = EcsRamRole
# ecsRoleName可以不设置，当不设置时，自动获取。
ecsRoleName = EcsRamRoleOss 
region=cn-hangzhou

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

ossutil ls oss://examplebucket --mode EcsRamRole

使用OIDCRoleARN

在容器服务Kubernetes版中设置了Worker节点RAM角色后，对应节点内的Pod中的应用也就可以像ECS上部署的应用一样，通过元数据服务（Meta Data Server）获取关联角色的STS Token。但如果容器集群上部署的是不可信的应用（比如部署的客户提交的应用，代码也没有对开放），可能并不希望它们能通过元数据服务获取Worker节点关联实例RAM角色的STS Token。为了避免影响云上资源的安全，同时又能让这些不可信的应用安全地获取所需的STS Token，实现应用级别的权限最小化，可以使用RRSA（RAM Roles for Service Account）功能。该方式底层实现是STS Token。阿里云容器集群会为不同的应用Pod创建和挂载相应的服务账户OIDC Token文件，并将相关配置信息注入到环境变量中，Credentials工具通过获取环境变量的配置信息，调用STS服务的AssumeRoleWithOIDC接口换取绑定角色的STS Token。该方式无需提供一个AK或STS Token，消除了手动维护AK或STS Token的风险。详情请参见通过RRSA配置ServiceAccount的RAM权限实现Pod权限隔离。

生成如下的配置文件，并保存在~/.ossutilconfig。不支持通过环境变量或者命令行选项方式设置。

[default]
mode = oidcRoleArn
#指定 OIDC 提供者的 ARN（Aliyun Resource Name），格式为 acs:ram::account-id:oidc-provider/provider-name。
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
#指定 OIDC 令牌的文件路径，用于存储 OIDC 令牌
OIDCTokenFilePath=OIDCTokenFilePath
#填写角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::113511544585****:oidc-provider/TestOidcProvider
roleArn=acs:ram::113511544585****:role/testoidc
# 自定义角色会话名称，用于区分不同的令牌。
roleSessionName= TestOidcAssumedRoleSession
region=cn-hangzhou

通过如下命令查询examplebucket中的对象。

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

外部进程获取凭证

ossutil通过外部命令启动一个进程，该进程与ossutil进程是独立的，称为外部进程。外部进程执行后，通过标准输出把结果返回给进程的启动者，即ossutil。可以通过外部进程获取凭证。

外部命令返回的凭证，支持长期凭证和临时凭证，格式如下。

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

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

生成如下配置文件，并保存在~/.ossutilconfig。不支持通过环境变量或者命令行选项方式设置。

[default]
mode = Process
credentialProcess = user-cmd
region=cn-hangzhou

通过如下命令查询examplebucket中的对象。

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

匿名访问

如果只需要访问公共读取权限的OSS资源，可以使用匿名访问方式，无需提供任何凭证。

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

命令参考

ossutil提供了高级命令、API级命令、辅助命令等三类命令。

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

命令行选项

在命令行操作中，部分命令需要附加参数以指定操作对象或设置选项，而其他命令则不需要参数。对于带参数的命令，可以根据具体要求提供适当的参数值，以实现预期功能，例如，带参数的命令如：

ossutil ls --profile dev

ossutil ls --profile dev允许用户通过参数值dev指定特定的配置文件。带参数的选项通常需要通过空格或等号（=）将选项名称与参数值分隔，例如--profile dev或--profile=dev。当参数值包含空格时，必须使用双引号将整个参数值括起来，以确保命令正确解析，例如 --description "OSS bucket list"。

常见问题

使用ossutil执行相关命令时，报错region must be set in sign version 4

问题原因：在配置ossutil2.0时没有配置地域ID项。

解决方法：为避免在使用ossutil时因配置项缺失导致操作失败，请确保按照以下步骤配置必要的基础项：AccessKey ID、AccessKey Secret、地域ID。特别是地域ID，由于签名已升级到V4版本，因此成为必需项。关于如何获取地域ID，请参见OSS地域和访问域名。