文档

配置ossutil

更新时间:

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

通过config命令进行快速配置

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

以Linux环境为例进行说明。

  1. 输入配置命令。

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

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

    请输入配置文件名,文件名可以带路径(默认为:/home/user/.ossutilconfig,回车将使用默认路径。 如果用户设置为其他路径,在使用命令时需要将--config-file选项设置为该路径):
  3. 根据提示设置工具的语言。

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

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

    参数说明如下:

    参数

    说明

    endpoint

    填写Bucket所在地域的Endpoint。关于各地域Endpoint的更多信息,请参见访问域名和数据中心

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

    accessKeyID

    填写账号的AccessKey。

    accessKeySecret

    stsToken

    使用STS临时授权账号访问OSS时需要配置该项,否则置空即可。关于stsToken的生成方式,请参见临时访问凭证

    说明

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

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

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

    ./ossutil64 -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
  • 本页导读 (1)