全部產品
Search

搜尋本產品

    Object Storage Service：配置ossutil

    文件中心

    Object Storage Service：配置ossutil

    更新時間：Dec 20, 2024

    本文介紹ossutil的配置方式，您可以通過本文瞭解如何配置ossutil。

    前提條件

    基礎配置（必選）

    重要

    為避免在使用ossutil時因配置項缺失導致操作失敗，建議您首先按照以下步驟完成AccessKey ID、AccessKey Secret、地區ID的配置。

    Linux

    1. 輸入配置命令。

    ossutil config

    1. 根據提示設定設定檔路徑。您可以直接斷行符號使用預設的設定檔路徑。

    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作為設定檔。

    1. 根據提示分別設定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

    1. 輸入配置命令。

    ossutil config

    1. 根據提示設定設定檔路徑。您可以直接斷行符號使用預設的設定檔路徑。

      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作為設定檔。

    2. 根據提示分別設定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

    1. 輸入配置命令。

      ossutil config

    2. 根據提示設定設定檔路徑。您可以直接斷行符號使用預設的設定檔路徑。

      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作為設定檔。

    3. 根據提示分別設定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

    指定Proxy 伺服器，

    配置值可以為以下幾種：

    • 直接配置：可以直接指定Proxy 伺服器的詳細資料，例如：

      • http://proxy.example.com:8080

      • https://proxy.example.com:8443

    • env：表示使用環境變數 HTTP_PROXY 和 HTTPS_PROXY 來擷取Proxy 伺服器資訊。使用者需要在作業系統中配置這兩個環境變數，例如：

      • HTTP_PROXY=http://proxy.example.com:8080

      • HTTPS_PROXY=https://proxy.example.com:8443

      配置這些環境變數後，將Proxy 伺服器選項的值設定為 env，系統將自動使用這些環境變數中的代理設定。

    --log-file

    string

    指定日誌輸出檔案，配置值為：

    • -：表示將日誌輸出到標準輸出（Stdout）。

    • 檔案路徑：指定一個具體的檔案路徑，將日誌輸出到該檔案。

    如果未指定日誌輸出檔案，輸出到預設設定檔上。

    環境變數

    您可以參照以下步驟配置環境變數。

    Linux系統

    1. 執行以下命令。

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

    2. 執行以下命令，驗證該環境變數是否生效。

      echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

    macOS系統

    1. 執行以下命令。

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

    2. 執行以下命令，驗證該環境變數是否生效。

      echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

    Windows系統

    1. 在CMD中運行以下命令。

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

    2. 開啟一個新的CMD視窗。

    3. 在新的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