How to configure ossutil - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to configure ossutil.

Upgrade to ossutil 2.0

Use the upgraded ossutil 2.0. For more information about how to quickly install and use it, see Install ossutil.

The following are the key features of ossutil 2.0:

New command structure: ossutil 2.0 supports multi-level commands. These include API-level commands, such as ossutil api put-bucket-acl, and high-level commands, such as ossutil config.
Improved configuration management: The initial configuration process is simplified. You can provide an AccessKey ID, AccessKey secret, and region ID to complete the basic configuration after installation. You can also specify multiple configuration files using the --profile parameter for enhanced flexibility.
Advanced filtering: ossutil 2.0 supports multiple filter conditions for batch processing commands, such as ls, cp, and rm. You can filter by path, file size, modification time, or object metadata. This feature improves the precision and efficiency of batch operations.
Flexible output formatting: The new --output-format parameter lets you set the output format to JSON, YAML, or XML to better suit different data processing needs. The new --output-query option lets you filter the output to obtain the information you need.
Enhanced security: To improve security, ossutil 2.0 lets you set sensitive parameters using environment variables. This prevents keys from being exposed in the command line, reducing the risk of information leaks. In addition, the new --dry-run option lets you verify the behavior of a command before you run the command to ensure that the operation is correct.

Interactive configuration

In most cases, use the config command to quickly set up ossutil. This command interactively generates a configuration file.

The following steps use a Linux environment as an example.

Enter the configuration command.
```
ossutil config
```

Set the configuration file path as prompted.

Set the path for the configuration file as prompted. By default, the configuration file is saved to ~/.ossutilconfig. Press Enter to use the default configuration.

Enter the configuration file name. The file name can include a path (Default: /home/user/.ossutilconfig. Press Enter to use the default path. If you set a different path, you must set the --config-file option to that path when you use commands.):

Set the language for the tool as prompted.
Enter CH for Chinese or EN for English. By default, the language of the tool is the same as the language of your operating system. This configuration item takes effect after the config command is successfully run.

Set the Endpoint, AccessKey ID, AccessKey secret, and stsToken parameters as prompted. If you use a temporary access credential from Security Token Service (STS) to access OSS, you must configure the stsToken parameter. Otherwise, leave it empty.

The following table describes the parameters.

Parameter	Required	Description
endpoint	Yes	Enter the endpoint of the region where the bucket is located. For example, this example uses the public endpoint for the Singapore region. Set it to `https://oss-ap-southeast-1.aliyuncs.com`. If you want to access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. Set it to `https://oss-ap-southeast-1-internal.aliyuncs.com`. For more information about regions and endpoints, see Regions and endpoints. Important Due to a policy change to improve compliance and security, starting March 20, 2025, new OSS users must use a custom domain name (CNAME) to perform data API operations on OSS buckets located in Chinese mainland regions. Default public endpoints are restricted for these operations. Refer to the official announcement for a complete list of the affected operations. If you access your data via HTTPS, you must bind a valid SSL Certificate to your custom domain. This is mandatory for OSS Console access, as the console enforces HTTPS.
accessKeyID	Yes	Enter the AccessKey pair for your account. To obtain an AccessKey pair, see Create an AccessKey pair. Quickly create an AccessKey pair for a RAM user with OSS management permissions using a ROS script On the Create Stack page in the Resource Orchestration Service (ROS) console, select the confirmation checkbox under Security Confirmation, and then click Create. After the stack is created, copy the created AccessKey pair from the Outputs tab.
accessKeySecret	Yes
stsToken	No	This parameter is required only when you use a temporary access credential from STS to access OSS. Otherwise, leave it empty and skip this step. For information about how to generate an stsToken, see AssumeRole - Obtain temporary identity credentials for a RAM role.

If you specified a custom path for the configuration file in step 2, you must add the -c option to specify the configuration file each time you run a command.
For example, if the configuration file is saved as /home/config, use the following command format when you run the ls command:
```
ossutil -c /home/config ls oss://examplebucket
```

Configuration file

For convenience, save frequently used credentials and configuration information to a configuration file. The configuration file uses the INI format, which consists of sections and keys. Configuration parameters are saved in the specified sections. The following table describes common configuration parameters:

Configuration parameter	Description	Sample code
language	Sets the language of the ossutil tool. Valid values: CH: Chinese. EN: English.	`[Credentials] language = CH`
endpoint	Sets the domain name information for the region where the bucket is located.	`[Credentials] endpoint = oss-ap-southeast-1.aliyuncs.com` `[Credentials] endpoint = https://oss-ap-southeast-1.aliyuncs.com`
accessKeyID	A part of the AccessKey pair used to identify the user and authenticate command requests.	`[Credentials] accessKeyID = your_accesskey_id`
accessKeySecret	A part of the AccessKey pair used to authenticate the user's key for command requests.	`[Credentials] accessKeySecret = your_accesskey_secret`
stsToken	The token for the temporary key, used to authenticate command requests.	`[Credentials] stsToken = your_sts_token`
mode	The authentication mode to use. Valid values can be AK, stsToken, RamRoleArn, or EcsRamRole.	`[Credentials] mode = RamRoleArn`
ramRoleArn	The ARN of the RAM role for the authentication mode.	`[Credentials] ramRoleArn = your_ram_role_arn`
roleSessionName	The session name for the RamRoleArn authentication mode. If this is not set, a random value is generated.	`[Credentials] roleSessionName = your_ram_role_seesion_name`
tokenTimeout	The validity period of the token in seconds. This is used for the RamRoleArn mode. The default value is 3600.	`[Credentials] tokenTimeout = your_token_timetout`
ecsRoleName	The role name for the EcsRamRole authentication mode.	`[Credentials] ecsRoleName = your_ecs_role_name`

For more information about command configuration parameters, see Edit the configuration file.

Command-line options

In addition to using a configuration file, use command-line options to specify configurations. Command-line options have a higher priority than the settings in the configuration file. The following table describes common command-line options:

Option	Description	Sample code
--loglevel	The log level. The default value is empty, which means no log file is output. Valid values: info: Outputs informational logs. debug: Outputs detailed logs, including HTTP request and response information.	`ossutil64 commandname options --loglevel debug`
--connect-timeout	The client connection timeout period in seconds. The default value is 120.	`ossutil64 commandname options --connect-timeout 60`
--read-timeout	The client read timeout period in seconds. The default value is 1200.	`ossutil64 commandname options --read-timeout 60`
--retry-times	The number of retries when an error occurs. The default value is 10.	`ossutil64 commandname options --retry-times 20`
-e, --endpoint	The requested domain name.	`ossutil64 commandname options -e oss-ap-southeast-1.aliyuncs.com` `ossutil64 commandname options -e https://oss-ap-southeast-1.aliyuncs.com`
-i, --access-key-id	The access credential used to access OSS.	`ossutil64 commandname options -i your_access_key`
-k, --access-key-secret	The access credential used to access OSS.	`ossutil64 commandname options -k your_access_key_secrect`
-t, --sts-token	The stsToken used to access OSS.	`ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token`
--mode	The authentication mode. Valid values can be AK, stsToken, RamRoleArn, or EcsRamRole. The default value is empty.	The following is a sample command on how to access OSS in AK mode: `ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK`
--ram-role-arn	The ARN of the RAM role for the authentication mode.	`ossutil64 commandname options --ram-role-arn your_ram_role_arn`
--role-session-name	The session name for the authentication mode.	`ossutil64 commandname options --role-session-name your_ram_session_name`
--token-timeout	The validity period of the token in seconds. The default value is 3600.	`ossutil64 commandname options --token-timeout 1800`
--ecs-role-name	The role name for the EcsRamRole authentication mode.	`ossutil64 commandname options --ecs-role-name your_ecs_role_name`

For more information about option configurations, see Common options.

Configure access credentials

You can configure access credentials in multiple ways, such as using a configuration file or command-line options.

Access using an AccessKey pair

This section uses a bucket named example-bucket in the Singapore region as an example.

Through a configuration file

Create the following configuration file and save it as ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret

Run the following command to query the objects in the bucket.

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

Through command-line options
Pass the AccessKey pair as command-line parameters. The following sample command shows how to do this:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret ls oss://example-bucket
```
Important
Passing credentials as command-line parameters poses a security risk, as they may be recorded in shell history or system logs. Use this method with caution.

Access using a temporary token

This section uses a bucket named example-bucket in the Singapore region as an example.

Through a configuration file

Create the following configuration file and save it as ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
stsToken = yourSecurityToken

Run the following command to query the objects in the bucket.

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

Through command-line options
Pass the access credentials as command-line parameters. The following sample command shows how to do this:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret -t yourSecurityToken ls oss://example-bucket
```
Note
Passing credentials as command-line parameters poses a security risk, as they may be recorded in shell history or system logs. Use this method with caution.

Access using a RAM role

This section uses a bucket named example-bucket in the Singapore region and a RAM role to be assumed named ramRoleArnExample as an example.

Through a configuration file

Create the following configuration file and save it as ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
ramRoleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example (Optional)
tokenTimeout = 1800 (Optional)

Run the following command to query the objects in the bucket.

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

Through command-line options
Pass the access credentials as command-line parameters. The following sample command shows how to do this:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
```
Note
Passing credentials as command-line parameters poses a security risk, as they may be recorded in shell history or system logs. Use this method with caution.

Access using an instance RAM role

On an Elastic Compute Service (ECS) instance, you can use an instance RAM role to configure access credentials for ossutil. An instance RAM role lets you associate a RAM role with an ECS instance and use temporary credentials from STS to run ossutil on the instance. The system automatically generates and updates the temporary credentials. Applications can obtain the temporary credentials from a specific instance metadata URL without requiring special management. Using a RAM role helps secure your AccessKey pair and allows for fine-grained permission control and management.

Before you start, you must create an instance RAM role on the ECS instance. For more information, see Create an instance RAM role.

This section uses a bucket named example-bucket in the Singapore region and a RAM role named EcsRamRoleOss that is created on an ECS instance as an example.

Through a configuration file
Create the following configuration file and save it as ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss
```
Run the following command to query the objects in the bucket.
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
```
Through command-line options
Pass the access credentials as command-line parameters. The following is a sample command:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket
```

Configure a separate endpoint for a bucket

When you use ossutil, you may need to manage multiple buckets. In this case, you must configure a separate endpoint for each bucket. Use one of the following two methods for configuration:

Through a configuration file
In the configuration file, add a [Bucket-Endpoint] section to configure a separate endpoint for each specified bucket. The format is as follows:
```
[Bucket-Endpoint]
bucket1 = endpoint1
bucket2 = endpoint2
...
```
The following example shows how to configure endpoints for a bucket in the Singapore region (example-bucket-sg) and a bucket in the Japan (Tokyo) region (example-bucket-jp).
Create the following configuration file and save it as ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Endpoint]
example-bucket-sg=oss-ap-southeast-1.aliyuncs.com
example-bucket-jp=oss-ap-northeast-1.aliyuncs.com
```
Run the following commands to query the objects in the buckets.
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-jp
```
Through command-line options
The following example shows how to configure endpoints for a bucket in the Singapore region (example-bucket-sg) and a bucket in the Japan (Tokyo) region (example-bucket-jp).
Configure the account information in ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
```
Specify the endpoint using the -e parameter.
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig -e oss-ap-northeast-1.aliyuncs.com ls oss://example-bucket-jp
```

Configure a custom domain name

ossutil lets you access OSS resources using a custom domain name. Before using this feature, you must configure the mapping between the bucket and the custom domain name in the configuration file.

In the configuration file, add a [Bucket-Cname] section to configure a separate endpoint for each specified bucket. The format is as follows:

[Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...

The following example shows how to access a bucket named example-bucket in the Singapore region using the custom domain name cname.example-***.com.

Create the following configuration file and save it as ~/.myossutilconfig.

[Credentials]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Cname]
example-bucket=cname.example-***.com

Run the following command to query the objects in the bucket.

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