Object Storage Service:Configure ossutil

Configuration file settings

You can save commonly used ossutil configuration settings and access credentials in a configuration file. Settings in a configuration file are categorized into sections. You can use the --profile option to specify a specific section for ossutil to use. By default, ossutil uses settings in the default section of a configuration file. You can create and reference other settings.

Configuration file format

A configuration file for ossutil is in the INI file format. An INI configuration file consists of sections.

• Parameters in sections are in the key=value format.

• Section names and key names are case-insensitive.

• Keys can be in lowercase and small camel case. Words in a key can be separated by a hyphen character (-) or an underscore character (_). For example, you can set an AccessKey ID in a configuration file by using accesskeyid, accessKeyId, access-key-id, or access_key_id.

• Comments start with a number sign (#).

Supported section types

[buckets name]
bucket-name = 
  key=value

[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

Environment variables

You can also configure options and access credentials by using environment variables. Environment variables take precedence over configuration files. The following table describes environment variables supported by ossutil.

Access credentials

You can configure access credentials by using configuration files, environment variables, or command line options.

Configure temporary access credentials

• By using a configuration file

  Create a configuration file ~/.myossutilconfig that contains the following settings.

  [default]
  accessKeyID = STS.LTAI4Fw2NbDUCV8z********
  accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
  stsToken = yourSecurityToken
  region=cn-hangzhou

  Run the following command to list objects in the example-bucket bucket.

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

• By using environment variables

  export OSS_ACCESS_KEY_ID=STS.LTAI4Fw2NbDUCV8z********
  export OSS_ACCESS_KEY_SECRET=67DLVBkH7EamOjy2W5RVAH********
  export OSS_SESSION_TOKEN=yourSecurityToken
  ossutil ls oss://example-bucket

• By using command line options (not recommended)

  Run the following command to list objects in the example-bucket bucket.

  ossutil ls oss://example-bucket -i STS.LTAI4Fw2NbDUCV8z******** -k 67DLVBkH7EamOjy2W5RVAH******** -t yourSecurityToken

Configure long-term access credentials

• By using a configuration file

  Create a configuration file ~/.myossutilconfig that contains the following settings.

  [default]
  accessKeyID = LTAI4Fw2NbDUCV8z********
  accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
  region=cn-hangzhou

  Run the following command to list objects in the example-bucket bucket.

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

• By using environment variables

  export OSS_ACCESS_KEY_ID=LTAI4Fw2NbDUCV8z********
  export OSS_ACCESS_KEY_SECRET=67DLVBkH7EamOjy2W5RVAH********
  ossutil ls oss://example-bucket

• By using command line options (not recommended)

  Run the following command to list objects in the example-bucket bucket.

  ossutil ls oss://example-bucket -i LTAI4Fw2NbDUCV8z******** -k 67DLVBkH7EamOjy2W5RVAH********

Access credentials for a RAM user

By using a configuration file

Create a configuration file ~/.myossutilconfig that contains the following settings.

[default]
accessKeyID = LTAI4Fw2NbDUCV8z********
accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=cn-hangzhou

Run the following command to list objects in the example-bucket bucket.

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

Access credentials for a RAM role for ECS instances

• By using a configuration file

  Create a configuration file ~/.myossutilconfig that contains the following settings.

  [default]
  mode = EcsRamRole
  # The ecsRoleName parameter is optional. If you do not set this parameter, the value is automatically obtained. 
  ecsRoleName = EcsRamRoleOss 
  region=cn-hangzhou

  Run the following command to list objects in the example-bucket bucket.

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

• By using command line options

  Run the following command to list objects in the example-bucket bucket.

  ossutil ls oss://example-bucket --mode EcsRamRole

OIDC access credentials

For more information about OIDC role-based SSO, see Overview of OIDC-based SSO.

By using a configuration file

Create a configuration file ~/.myossutilconfig that contains the following settings.

[default]
mode = oidcRoleArn
# Provide the ARN of the OIDC IdP in the format of acs:ram::account-id:oidc-provider/provider-name. 
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Specify the path to the OIDC token.
OIDCTokenFilePath=OIDCTokenFilePath
# Specify the ARN of the role, that is, the ID of the role. The ARN is in the acs:ram::113511544585****:oidc-provider/TestOidcProvider format.
roleArn=acs:ram::113511544585****:role/testoidc
# Specify the session name, which is used to differentiate tokens. 
roleSessionName= TestOidcAssumedRoleSession
region=cn-hangzhou

Run the following command to list objects in the example-bucket bucket.

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

External processes

ossutil uses an external command to start an external process, which is separate from the ossutil process. An external process returns the output to ossutil by using the standard output. You can obtain access credentials by using an external process.

An external command can return long-term and temporary access credentials.

• Long-term credentials

  {
  	"AccessKeyId" : "ak",
  	"AccessKeySecret" : "sk",
  }

• Temporary credentials

  {
  	"AccessKeyId" : "ak",
  	"AccessKeySecret" : "sk",
  	"Expiration" : "2023-12-29T07:45:02Z",
  	"SecurityToken" : "token",
  }

By using a configuration file

Create a configuration file ~/.myossutilconfig that contains the following settings.

[default]
mode = Process
credentialProcess = user-cmd
region=cn-hangzhou

Run the following command to list objects in the example-bucket bucket.

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