如何配置ossutil_对象存储(OSS)-阿里云帮助中心

本文介绍ossutil的配置方式，您可以通过本文了解如何配置ossutil。

前提条件

已安装ossutil。
已开通OSS服务。

基础配置（必选）

重要

为避免在使用ossutil时因配置项缺失导致操作失败，建议您首先按照以下步骤完成AccessKey ID、AccessKey Secret、地域ID的配置。

Linux

输入配置命令。

ossutil config

根据提示设置配置文件路径。您可以直接回车使用默认的配置文件路径。

Please enter the config file name,the file name can include path(default /root/.ossutilconfig, carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

ossutil默认使用/root/.ossutilconfig作为配置文件。

根据提示分别设置AccessKey ID、AccessKey Secret、地域ID信息。
输入您创建的AccessKey ID。
```
Please enter Access Key ID [****************id]:LTAI****************
```
输入您创建的AccessKey Secret。
```
Please enter Access Key Secret [****************sk]:R6vg*********************
```
输入您的OSS的数据中心所在的地域，如无任何输入，默认值为cn-hangzhou。
```
Please enter Region [cn-hangzhou]:cn-hangzhou
```
本文以杭州地域为例，其他地域的ID参见OSS地域和访问域名。

Windows

输入配置命令。

ossutil config

根据提示设置配置文件路径。您可以直接回车使用默认的配置文件路径。

Please enter the config file name,the file name can include path(default "C:\Users\issuser\.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

ossutil默认使用C:\Users\issuser\.ossutilconfig作为配置文件。

根据提示分别设置AccessKey ID、AccessKey Secret、地域等信息。
输入您创建的AccessKey ID。
```
Please enter Access Key ID [****************id]:LTAI****************
```
输入您创建的AccessKey Secret。
```
Please enter Access Key Secret [****************sk]:R6vg*********************
```
输入您的OSS的数据中心所在的地域，如无任何输入，默认值为cn-hangzhou。
```
Please enter Region [cn-hangzhou]:cn-hangzhou
```
本文以杭州地域为例，其他地域的ID参见OSS地域和访问域名。

macOS

输入配置命令。
```
ossutil config
```

根据提示设置配置文件路径。您可以直接回车使用默认的配置文件路径。

Please enter the config file name,the file name can include path(default "/Users/user/.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

ossutil默认使用/Users/user/.ossutilconfig作为配置文件。

根据提示分别设置AccessKey ID、AccessKey Secret、地域等信息。
输入您创建的AccessKey ID。
```
Please enter Access Key ID [****************id]:LTAI****************
```
输入您创建的AccessKey Secret。
```
Please enter Access Key Secret [****************sk]:R6vg*********************
```
输入您的OSS的数据中心所在的地域，如无任何输入，默认值为cn-hangzhou。
```
Please enter Region [cn-hangzhou]:cn-hangzhou
```
本文以杭州地域为例，其他地域的ID参见OSS地域和访问域名。

支持的配置方式

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

配置文件：ossutil的配置文件采用INI格式，允许您在此文件中设定各种配置参数。
命令行选项：ossutil提供了多个命令行选项，您可以直接使用这些选项进行配置。命令行选项优先级最高。
重要
通过命令行选项需要传入访问密钥，可能会被日志系统记录，存在密钥泄露的风险，请谨慎使用。
环境变量：ossutil支持多种环境变量，其优先级要高于配置文件中的设置，您可以使用这些变量配置ossutil。

配置文件

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

ossutil ls oss://examplebucket

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

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

配置文件格式

配置文件采用INI格式结构，以节（section）和键值（key）构成，配置参数保存在指定的节里。这些配置按照节分成多个段，可以通过--profile使用某一个节的配置。默认情况下，ossutil使用配置文件中的[default]设置。要使用其他设置，您可以创建和引用其他配置。

节和键值对

配置文件中的每个节由方括号 [ ] 包围的名称标识，节内的设置项采用 key=value 形式。例如：

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

节中的设置项采用key=value形式。
节名和键值中的key不区分大小写。
配置参数的key支持多种格式，全小写、小驼峰、短划线（-）连接和下划线（_）连接，例如：accesskeyid、accessKeyId、access-key-id、access_key_id表示同一个参数名。
井号字符（#）开头的行表示注释行。

支持的节类型

节（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秒的超时时间。

全局参数

参数名	别名	含义
region	/	地域ID，必须设置。
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

命令行选项

在运行ossutil命令时，您可以直接通过命令行选项传递配置信息。这种方式非常适合临时性的配置需求，例如：

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

当前支持配置的命令行选项如下：

参数	类型	说明
-i, --access-key-id	string	访问OSS使用的AccessKey ID。
-k, --access-key-secret	string	访问OSS使用的AccessKey Secret。
--addressing-style	string	请求地址的格式。取值范围如下： virtual（默认值），表示虚拟托管模式。 path，表示路径模式。 cname，表示自定义域名模式。
-c, --config-file	string	配置文件的路径。默认值为`~\.ossutilconfig`。
--connect-timeout	int	客户端连接超时的时间。单位为秒，默认值为10。
-n, --dry-run	/	在不进行任何更改的情况下执行试运行。
-e, --endpoint	string	对外服务的访问域名。
-h, --help	/	显示帮助信息。
--language	string	显示的语言。
--loglevel	string	日志级别。取值范围如下： off（默认值） info debug
--mode	string	鉴权模式。取值： AK，表示访问密钥。 StsToken，表示临时安全凭证。 EcsRamRole，表示使用ECS实例角色（RAM Role）进行鉴权。 Anonymous，表示匿名访问。
--output-format	string	输出格式，默认值为raw。
--output-query	string	JMESPath查询条件。
--profile	string	指定配置文件里的profile。
-q, --quiet	/	安静模式，打印尽可能少的信息。
--read-timeout	int	客户端读写请求超时时间。单位为秒，默认值为20。
--region	string	数据中心所在的地域，配置值可设置为cn-hangzhou。
--retry-times	int	当错误发生时的重试次数。默认值为10。
--sign-version	string	请求使用的签名算法版本。取值： v1 v4（默认值）
--skip-verify-cert	/	表示不校验服务端的数字证书。
-t, --sts-token	string	访问OSS使用的STS Token。
--proxy	string	指定代理服务器，配置值可以为以下几种：直接配置：可以直接指定代理服务器的详细信息，例如： `http://proxy.example.com:8080` `https://proxy.example.com:8443` `env`：表示使用环境变量 `HTTP_PROXY` 和 `HTTPS_PROXY` 来获取代理服务器信息。用户需要在操作系统中配置这两个环境变量，例如： `HTTP_PROXY=http://proxy.example.com:8080` `HTTPS_PROXY=https://proxy.example.com:8443` 配置这些环境变量后，将代理服务器选项的值设置为 `env`，系统将自动使用这些环境变量中的代理设置。
--log-file	string	指定日志输出文件，配置值为： `-`：表示将日志输出到标准输出（Stdout）。 `文件路径`：指定一个具体的文件路径，将日志输出到该文件。如果未指定日志输出文件，输出到默认配置文件上。

环境变量

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

Linux系统

执行以下命令。

export OSS_ACCESS_KEY_ID="your-access-key-id"
export OSS_ACCESS_KEY_SECRET="your-access-key-secret"

执行以下命令，验证该环境变量是否生效。
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS系统

执行以下命令。

export OSS_ACCESS_KEY_ID="your-access-key-id"
export OSS_ACCESS_KEY_SECRET="your-access-key-secret"

执行以下命令，验证该环境变量是否生效。
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

Windows系统

在CMD中运行以下命令。

set OSS_ACCESS_KEY_ID "your-access-key-id"
set OSS_ACCESS_KEY_SECRET "your-access-key-secret"

打开一个新的CMD窗口。
在新的CMD窗口运行以下命令，检查环境变量是否生效。
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

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

环境变量名	对应的参数名
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

配置示例

您可以参考以下方法，通过配置文件、环境变量或命令行选项配置不同类型的访问凭证的实例并查询examplebucket中的对象。

长期访问凭证

通过配置文件

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

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

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

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********

短期访问凭证

通过配置文件

生成如下的配置文件，并保存在~/.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

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