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

配置ossutil

更新时间：
产品详情
我的收藏

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

版本升级

推荐您使用全新升级的ossutil2.0，快速安装并使用，请参见安装ossutil。

ossutil2.0重点功能如下：

  • 全新的命令组织结构：引入了多级命令支持，包括API级命令（例如ossutil api put-bucket-acl）和高级命令（如ossutil config）。

  • 改进的配置管理机制：简化了初始配置流程，用户仅需提供AccessKey ID、AccessKey Secret及地域ID即可完成安装后的基础配置，并且支持通过--profile参数指定多个配置文件，增强了灵活性。

  • 丰富的过滤参数：对于批量处理命令（如ls、cp、rm等），新增了基于路径、文件大小、修改时间以及对象元数据等多种过滤条件的支持，极大地提升了操作的精确性和效率。

  • 灵活的输出格式调整：新增--output-format参数，允许用户将输出格式设定为JSON、YAML或XML，以便更好地适配不同的数据处理需求；同时引入了--output-query选项，让用户能够对输出内容进行筛选，获取所需信息。

  • 安全性增强：为了提高安全性，ossutil 2.0支持通过环境变量设置敏感参数，避免在命令行中直接暴露密钥，减少了泄露风险；此外，新增的--dry-run选项使用户能够在实际执行命令前验证其行为，确保操作无误。

通过config命令进行快速配置

对于大多数情况，通过该命令可以快速设置您的ossutil工具。该命令提供了交互式方式生成配置文件。

以Linux环境为例进行说明。

  1. 输入配置命令。

    ossutil config

  2. 根据提示设置配置文件路径。

    您可以根据实际需要设置配置文件的路径。默认情况下，配置文件保存到~/.ossutilconfig文件里， 直接按回车则使用默认配置。

    请输入配置文件名，文件名可以带路径（默认为：/home/user/.ossutilconfig，回车将使用默认路径。 如果用户设置为其他路径，在使用命令时需要将--config-file选项设置为该路径）：

  3. 根据提示设置工具的语言。

    请输入语言CH或EN。工具使用的语言默认与操作系统保持一致。该配置项将在此次config命令设置成功后生效。

  4. 根据提示分别设置Endpoint、AccessKey ID、AccessKey Secret和STSToken参数。

    参数说明如下：

    参数

    说明

    endpoint

    填写Bucket所在地域的Endpoint。关于各地域Endpoint的更多信息，请参见OSS地域和访问域名。

    您也可以增加http://或https://指定ossutil访问OSS使用的协议，默认使用HTTP协议。例如，使用HTTPS协议访问华东1（杭州）的Bucket，设置为https://oss-cn-hangzhou.aliyuncs.com。

    accessKeyID

    填写账号的AccessKey。

    accessKeySecret

    stsToken

    使用STS临时授权账号访问OSS时需要配置该项，否则置空即可。关于stsToken的生成方式，请参见AssumeRole - 获取扮演角色的临时身份凭证。

    说明

    关于配置文件的更多信息，请参见config。

  5. 如果在步骤2设置了配置文件的路径，则每次使用命令时需增加-c选项指定配置文件。

    例如，配置文件保存为/home/config，使用ls时，命令格式如下：

    ossutil -c /home/config ls oss://examplebucket

命令配置文件

您可以将常用的凭证信息和配置信息保存到配置文件里，以方便使用。配置文件采用了INI格式结构，以节（section）和键（key）构成， 配置参数保存在指定的节里。常用的配置参数如下：

配置参数

说明

示例代码

language

设置ossutil工具的语言。取值：

  • CH：中文。

  • EN：英文。

[Credentials]
language = CH

endpoint

设置Bucket所在地域的域名信息。

  • [Credentials]
endpoint  = oss-cn-hangzhou.aliyuncs.com
  • [Credentials]
endpoint  = https://oss-cn-hangzhou.aliyuncs.com

accessKeyID

访问密钥的一部分，用于标识用户身份，以对命令请求进行身份验证。

[Credentials]
accessKeyID = your_accesskey_id

accessKeySecret

访问密钥的一部分，用于验证用户的密钥，以对命令请求进行身份验证。

[Credentials]
accessKeySecret = your_accesskey_secret

stsToken

临时密钥的Token，以对命令请求进行身份验证。

[Credentials]
stsToken = your_sts_token

mode

采用的鉴权模式，取值可以为AK、StsToken、RamRoleArn或者EcsRamRole。

[Credentials]
mode = RamRoleArn

ramRoleArn

鉴权模式下的RAM角色ARN。

[Credentials]
ramRoleArn = your_ram_role_arn

roleSessionName

鉴权模式下的会话名称，用于RamRoleArn模式。不设置时，会生成随机值。

[Credentials]
roleSessionName = your_ram_role_seesion_name

tokenTimeout

表示Token的有效时间，单位为秒，默认值为3600，用于RamRoleArn模式。

[Credentials]
tokenTimeout = your_token_timetout

ecsRoleName

EcsRamRole鉴权模式下的角色名称。

[Credentials]
ecsRoleName = your_ecs_role_name

更多命令配置参数，请参见编辑配置文件。

命令行选项

除了通过命令配置文件外，您还可以使用命令行参数设置相关的配置。命令行选项的优先级要高于命令配置文件。常用命令行选项如下：

选项

说明

示例代码

--loglevel

日志级别，默认为空，表示不输出日志文件。取值：

  • info：输出提示信息日志。

  • debug：输出详细信息日志（包括HTTP请求和响应信息）。

ossutil64 commandname options --loglevel debug

--connect-timeout

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

ossutil64 commandname options --connect-timeout 60

--read-timeout

表示客户端读超时的时间，单位为秒，默认值为1200。

ossutil64 commandname options --read-timeout 60

--retry-times

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

ossutil64 commandname options --retry-times 20

-e, --endpoint

请求的域名。

  • ossutil64 commandname options -e oss-cn-hangzhou.aliyuncs.com
  • ossutil64 commandname options -e https://oss-cn-hangzhou.aliyuncs.com

-i, --access-key-id

访问OSS使用的访问凭证。

ossutil64 commandname options -i your_access_key

-k, --access-key-secret

访问OSS使用的访问凭证。

ossutil64 commandname options -k your_access_key_secrect

-t, --sts-token

访问OSS使用的STSToken。

ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token

--mode

表示鉴权模式，取值可以为AK、StsToken、RamRoleArn、EcsRamRole，默认值为空。

使用AK模式访问的示例代码如下：

ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK

--ram-role-arn

鉴权模式下的RAM角色ARN。

ossutil64 commandname options --ram-role-arn your_ram_role_arn

--role-session-name

鉴权模式下的会话名字。

ossutil64 commandname options --role-session-name your_ram_session_name

--token-timeout

表示Token的有效时间，单位为秒，默认值为3600。 

ossutil64 commandname options --token-timeout 1800

--ecs-role-name

EcsRamRole鉴权模式下的角色名称。

ossutil64 commandname options --ecs-role-name your_ecs_role_name

更多选项配置，请参见通用选项。

配置访问凭证

您可以使用多种方式，通过配置文件或者命令行选项配置访问凭证。

使用访问密钥访问

以杭州地域名称为example-bucket的Bucket为例进行说明。

  • 通过配置文件

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

    [Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****

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

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

  • 通过命令行选项

    您也可以直接将访问密钥通过命令行参数传入，示例代码如下：

    ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** ls oss://example-bucket
    重要

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

使用临时Token访问

以杭州地域名称为example-bucket的Bucket为例进行说明。

  • 通过配置文件

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

    [Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = STS.LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
stsToken = yourSecurityToken

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

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

  • 通过命令行选项

    您也可以直接将访问密钥通过命令行参数传入，示例代码如下：

    ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i STS.LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** -t yourSecurityToken ls oss://example-bucket
    说明

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

使用RAM角色访问

以杭州地域名称为example-bucket的Bucket，需要扮演的角色为ramRoleArnExample为例进行说明。

  • 通过配置文件

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

    [Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
mode = RamRoleArn
ramRoleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example (可以不设置)
tokenTimeout = 1800 (可以不设置)

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

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

  • 通过命令行选项

    您也可以直接将访问密钥通过命令行参数传入，示例代码如下：

    ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
    说明

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

使用实例RAM角色访问

在云服务器ECS上，您还可以通过实例RAM角色的方式来配置ossutil访问凭证。实例RAM角色允许您将一个角色关联到云服务器实例，在实例内部基于临时凭证STS使用ossutil。临时凭证由系统自动生成和更新，应用程序可以使用指定的实例元数据URL获取临时凭证，无需特别管理。借助于RAM，一方面保证AccessKey安全，另一方面实现权限的精细化控制和管理。

使用前请先在ECS上创建实例RAM角色。更多信息，请参见概述。

以杭州地域名称为example-bucket的Bucket、ECS上创建的角色名称为EcsRamRoleOss为例进行说明。

  • 通过配置文件

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

    [Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss

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

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

  • 通过命令行选项

    您也可以直接将访问密钥通过命令行参数传入，示例代码如下：

    ossutil64 -e oss-cn-hangzhou.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket

为Bucket单独配置Endpoint

在使用ossutil的过程中，您需要管理多个Bucket，此时需要对Bucket单独配置Endpoint。您可以通过如下两种方式进行配置：

  • 通过配置文件

    在配置文件里，增加一个[Bucket-Endpoint]配置段，为每个指定的Bucket单独配置Endpoint，格式如下：

    [Bucket-Endpoint]
bucket1 = endpoint1
bucket2 = endpoint2
...

    以杭州地域Bucket（example-bucket-hz）、北京地域Bucket（example-bucket-bj）、上海地域Bucket（example-bucket-sh）为例进行说明。

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

    [Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = LTAI4Fw2NbDUCV8zYUzA****
[Bucket-Endpoint]
example-bucket-hz=oss-cn-hangzhou.aliyuncs.com
example-bucket-bj=oss-cn-beijing.aliyuncs.com
example-bucket-sh=oss-cn-shanghai.aliyuncs.com

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

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-hz
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-bj
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sh

  • 通过命令行选项

    以杭州地域Bucket（example-bucket-hz）、北京地域Bucket（example-bucket-bj）、上海地域Bucket（example-bucket-sh）为例进行说明。

    将账号信息配置在~/.myossutilconfig中。

    [Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****

    通过-e参数指定Endpoint。

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-hz
ossutil64 -c ~/.myossutilconfig -e oss-cn-beijing.aliyuncs.com ls oss://example-bucket-bj
ossutil64 -c ~/.myossutilconfig -e oss-cn-shanghai.aliyuncs.com ls oss://example-bucket-sh

配置自定义域名

ossutil支持通过自定义域名来访问OSS资源。在使用之前，需要通过配置文件设置Bucket和自定义域名的映射关系。

在配置文件里，增加一个[Bucket-Cname]配置段，为每个指定的Bucket单独配置Endpoint，格式如下：

[Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...

以杭州地域名称为example-bucket的Bucket、通过cname.example-***.com自定义域名访问为例进行说明。

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

[Credentials]
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
[Bucket-Cname]
example-bucket=cname.example-***.com

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

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
上一篇：安装ossutil下一篇：常用命令
文档推荐