全部产品
Search

搜索本产品

    对象存储 OSS：配置ossutil

    文档中心

    对象存储 OSS：配置ossutil

    更新时间：Dec 10, 2024

    本文介绍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