全部產品
Search
文件中心

Object Storage Service:配置ossutil

更新時間:Jul 31, 2024

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

通過config命令進行快速配置

對於大多數情況,通過該命令可以快速設定您的ossutil工具。該命令提供了互動式方式組建組態檔案。

以Linux環境為例進行說明。

  1. 輸入配置命令。

    ossutil 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的產生方式,請參見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角色訪問

在Elastic Compute Service上,您還可以通過執行個體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