AI 助理
备案控制台
文档
输入文档关键字查找
首页 对象存储 开发参考 常用工具 命令行工具ossutil 2.0（预览版） 配置ossutil

配置ossutil

更新时间：
产品详情
相关技术圈
我的收藏

本文介绍ossutil的一些配置操作，您可以通过本文了解如何更好地使用ossutil。

前提条件

配置方式

您可以使用多种方式配置ossutil，包括配置文件、环境变量和命令行选项。

  • 配置文件：ossutil的配置文件采用INI格式，您可以在其中设置配置参数。

  • 环境变量：ossutil支持多个环境变量，其优先级要高于配置文件里的配置项，您可以使用这些变量配置ossutil。

  • 命令行选项：ossutil提供了多个命令行选项，您可以使用这些选项配置ossutil。

重要

通过命令行选项需要传入访问密钥，可能会被日志系统记录，存在密钥泄露的风险，请谨慎使用。

配置文件

您可以将常用的配置设置和凭证保存到配置文件中。这些配置按照节分成多个段，可以通过--profile使用某一个节的配置。 默认情况下，ossutil使用配置文件中的default设置。要使用其它设置，您可以创建和引用其他配置。

说明

当使用配置文件配置访问凭证时，您可以通过ossutil config credential命令设置。

配置文件格式

配置文件采用INI格式结构，以节（section）和键值（key）构成，配置参数保存在指定的节里。

  • 节中的设置项采用key=value形式。

  • 节名和键值中的key不区分大小写。

  • 配置参数的key支持多种格式，全小写、小驼峰、短划线（-）连接和下划线（_）连接，例如：accesskeyid、accessKeyId、access-key-id、access_key_id表示同一个参数名。

  • 井号字符（#）开头的行表示注释行。

支持的节（Section）类型

节（Section）名称

说明

其它说明

[default]

用于保存缺省设置，即当不设置--profile选项时，使用该节里的配置。

为[profile default]简化形式。

[profile name]

用于配置参数，通过--profile name来引用。

支持通过source_profile方式引用其它配置。

[buckets name]

针对具体bucket配置访问域名，包括region、 endpoint和addressing style。

支持内联写法。

说明

您可以使用config命令查看和设置配置内容。更多信息，请参见config（管理配置文件）。

节类型：profile

用于配置访问凭证和全局配置参数，支持的参数名如下：

  • 访问凭证相关参数

    参数名

    别名

    含义

    mode

    /

    鉴权模式。

    取值：AK、StsToken、RamRoleArn、EcsRamRole、Anonymous。

    access-key-id

    accessKeyId

    access_key_id

    访问OSS使用的AccessKey ID。

    access-key-secret

    accessKeySecret

    access_key_secret

    访问OSS使用的AccessKey Secret。

    sts-token

    stsToken

    sts_token

    访问OSS使用的STS Token。

    role-arn

    roleArn

    role_arn

    RAM角色的ARN，主要用于RamRoleArn模式。

    role-session-name

    roleSessionName

    role_session_name

    会话名字，主要用于RamRoleArn模式。

    ecs-role-name

    ecsRoleName

    ecs_role_name

    角色名，主要用于EcsRamRole模式。

    credential-process

    credentialProcess

    credential_process

    指定一个外部命令。

    credential-uri

    credentialUri

    credential_uri

    指定一个获取访问凭证的URI地址。

    oidc-provider-arn

    oidcProviderArn

    oidc_provider_arn

    指定OIDC提供者的ARN（Aliyun Resource Name），格式为acs:ram::account-id:oidc-provider/provider-name。

    oidc-token-file-path

    oidcTokenFilePath

    oidc_token_file_path

    指定OIDC令牌的文件路径，用于存储OIDC令牌。

    credential-process-timeout

    credentialProcessTimeout

    credential_process_timeout

    用于指定外部凭证请求的超时时间，单位为秒。默认值为15即指定15秒；最大值为600即指定10分钟；credential-process-timeout = 60即指定60秒的超时时间。

  • 全局参数

    参数名

    别名

    含义

    loglevel

    /

    日志级别 。取值：

    • off（默认值）

    • info

    • debug

    read-timeout

    readTimeout

    read_timeout

    客户端读写请求超时时间。单位为秒，默认值20。

    connect-timeout

    connectTimeout

    connect_timeout

    客户端连接超时的时间。单位为秒，默认值10。

    retry-times

    retryTimes

    retry_times

    当错误发生时的重试次数。默认值10。

    skip-verify-cert

    skipVerifyCert

    skip_verify_cert

    不校验服务端的数字证书。

    sign-version

    signVersion

    sign_version

    请求使用的签名算法版本。取值：

    • v1

    • v4（默认值）

    output-format

    outputFormat

    output_format

    输出格式。取值：

    • raw（默认值）

    • json

    • xml

    • yaml

    addressing-style

    addressingStyle

    addressing_style

    请求地址的格式 。取值：

    • virtual（默认值）

    • path

    • cname

    language

    /

    显示的语言。

    endpoint

    /

    对外服务的访问域名，可不设置。

  • 其它参数

    参数名

    别名

    含义

    source-profile

    sourceProfile

    source_profile

    引用指定profile里的参数，例如：

    [profile cred]
access-key-id=ak
access-key-secret=sk

[profile dev]
region=cn-hangzhou
source-profile=cred

    buckets

    /

    引用指定buckets里的参数。

    [profile dev]
region=cn-hangzhou
access-key-id=ak
access-key-secret=sk
buckets=dev-bucket

[bucktes dev-bucket]
bucket-name-hz =
 endpoint=oss-cn-hangzhou-internal.aliyuncs.com
bucket-name-bj =
 region=cn-beijing

节类型：buckets

用于配置特定Bucket和访问点的映射关系。支持嵌套写法，即buckets节按bucket-name = 行分成多个小节。格式如下：

[buckets name]
bucket-name = 
  key=value

其中，name为该buckets节的名字，bucket-name为具体的Bucket名字，key=value配置参数，支持的参数如下：

参数名

别名

含义

region

/

数据中心所在的地域。

当不设置时，使用引入该参数的profile里的region值。

endpoint

/

对外服务的访问域名，可不设置。

addressing-style

addressingStyle

addressing_style

请求地址的格式。取值：

virtual（默认值）：使用Bucket虚拟域名请求地址格式。

path：使用path style请求地址格式。

cname：使用cname请求地址格式。

节类型buckets示例如下：

[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

环境变量

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

环境变量名

对应的参数名

OSS_ACCESS_KEY_ID

access-key-id

OSS_ACCESS_KEY_SECRET

access-key-secret

OSS_SESSION_TOKEN

sts-token

OSS_ROLE_ARN

ram-role-arn

OSS_ROLE_SESSION_NAME

role-session-name

OSS_REGION

region

OSS_ENDPOINT

endpoint

OSSUTIL_CONFIG_FILE

config-file

OSSUTIL_PROFILE

profile

配置访问凭证

您可以参考以下方法配置不同类型的访问凭证的实例配置。

短期访问凭证

通过配置文件

生成如下的配置文件，并保存在~/.myossutilconfig。

[default]
accessKeyID = STS.LTAI4Fw2NbDUCV8z********
accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
stsToken = yourSecurityToken
region=cn-hangzhou

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

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

通过环境变量

export OSS_ACCESS_KEY_ID=STS.LTAI4Fw2NbDUCV8z********
export OSS_ACCESS_KEY_SECRET=67DLVBkH7EamOjy2W5RVAH********
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

通过命令行选项（不推荐）

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

ossutil ls oss://examplebucket -i STS.LTAI4Fw2NbDUCV8z******** -k 67DLVBkH7EamOjy2W5RVAH******** -t yourSecurityToken

长期访问凭证

通过配置文件

生成如下的配置文件，并保存在~/.myossutilconfig。

[default]
accessKeyID = LTAI4Fw2NbDUCV8z********
accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
region=cn-hangzhou

通过如下命令查询example-bucket中的对象。

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

通过环境变量

export OSS_ACCESS_KEY_ID=LTAI4Fw2NbDUCV8z********
export OSS_ACCESS_KEY_SECRET=67DLVBkH7EamOjy2W5RVAH********
ossutil ls oss://examplebucket

通过命令行选项（不推荐）

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

ossutil ls oss://examplebucket -i LTAI4Fw2NbDUCV8z******** -k 67DLVBkH7EamOjy2W5RVAH********

RAM角色访问凭证

通过配置文件

生成如下的配置文件，并保存在~/.myossutilconfig。

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

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig
说明

不支持通过环境变量或者命令行选项方式设置。

实例角色访问凭证

通过配置文件

生成如下的配置文件，并保存在~/.myossutilconfig。

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

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

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

通过命令行选项

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

ossutil ls oss://examplebucket --mode EcsRamRole
说明

不支持通过环境变量方式设置。

OIDC访问凭证

关于OIDC角色SSO的更多信息，请参见OIDC角色SSO概览。

通过配置文件

生成如下的配置文件，并保存在~/.myossutilconfig。

[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 ~/.myossutilconfig
说明

不支持通过环境变量或者命令行选项方式设置。

外部进程获取凭证

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

说明

  • 生成凭证的命令不可由未经批准的进程或用户访问，否则可能存在安全风险。

  • 生成凭证的命令不会把任何秘密信息写入stderr或stdout，因为该信息可能会被捕获或记录，可能会将其向未经授权的用户公开。

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

长期凭证

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

临时凭证

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

通过配置文件

生成如下的配置文件，并保存在~/.myossutilconfig。

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

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig
说明

不支持通过环境变量或者命令行选项方式设置。

上一篇：安装ossutil下一篇：ossutil命令
文档推荐