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

Upgrade to ossutil 2.0

We recommend that you upgrade to ossutil 2.0. To quickly install and use the tool, see Install ossutil.

The following are the key features of ossutil 2.0:

New command structure: ossutil 2.0 supports multi-level commands, including API-level commands such asossutil api put-bucket-acl and high-level commands such asossutil config.
Improved configuration management: The initial configuration process is simplified. You can complete the basic configuration after installation by providing only an AccessKey ID, an AccessKey secret, and a region. You can also specify multiple configuration files by using the--profile parameter for enhanced flexibility.
Rich filtering parameters: For batch processing commands such asls,cp, andrm, support for multiple filter conditions is added. You can filter by path, file size, modification time, or object metadata. This improves operational precision and efficiency.
Flexible output formats: The new--output-format parameter lets you set the output format to JSON, YAML, or XML to suit different data processing needs. The--output-query option is also introduced to let you filter the output and retrieve specific information.
Enhanced security: To improve security, ossutil 2.0 lets you set sensitive parameters by using environment variables. This practice prevents your keys from being exposed in the command line and reduces the risk of leaks. In addition, the new--dry-run option lets you verify a command's behavior before you run it, ensuring the operation is correct.

Quick configuration with the config command

In most cases, you can 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.

Run the configuration command.
```
ossutil config
```

Set the path for the configuration file as prompted.

You can set the path for the configuration file based on your requirements. By default, the configuration file is saved to~/.ossutilconfig. Press Enter to accept the default.

Please enter the config file name, the file name can be with a path (default is: /home/user/.ossutilconfig, press enter to use the default path. If you set it to another path, you should specify the path with --config-file option when you use other commands):

Set the language for the tool as prompted.

Enter CH for Chinese or EN for English. By default, the tool uses your operating system's language. This setting takes effect after the config command completes.

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

The following table describes the parameters.

Parameter	Required	Description
endpoint	Yes	The endpoint of the bucket's region. For example, to use the public endpoint for the Singapore region, set the value to `https://oss-ap-southeast-1.aliyuncs.com`. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For example, set the value 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	The AccessKey pair for your account. For more information about how to create an AccessKey pair, see Create an AccessKey pair. You can use a Resource Orchestration Service (ROS) script to quickly create an AccessKey pair for a RAM user with OSS management permissions. On the Create Stack page of the ROS console, select the confirmation checkbox under Security Confirmation, and then click Create. After the Stack is created, go to the Outputs tab and copy the AccessKey pair.
accessKeySecret	Yes
stsToken	No	This parameter is required only if you use a temporary token from STS to access OSS. Otherwise, leave it blank. For more information about how to generate an stsToken, see AssumeRole.

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 to/home/config, use the following format when you run thels command:
```
ossutil -c /home/config ls oss://examplebucket
```

Configuration file

You can save frequently used credentials and configuration information to a configuration file for convenience. The configuration file uses the INI format and consists of sections and key-value pairs. Configuration parameters are saved in specific sections. The following table describes common configuration parameters.

Parameter	Description	Sample code
language	The language of the ossutil tool. Valid values: CH: Chinese EN: English	`[Credentials] language = CH`
endpoint	The endpoint 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	The part of the AccessKey pair that identifies the user for request authentication.	`[Credentials] accessKeyID = your_accesskey_id`
accessKeySecret	The part of the AccessKey pair that signs and authenticates command requests.	`[Credentials] accessKeySecret = your_accesskey_secret`
stsToken	The temporary token obtained from STS for authentication.	`[Credentials] stsToken = your_sts_token`
mode	The authentication mode. Valid values: AK, StsToken, RamRoleArn, and EcsRamRole.	`[Credentials] mode = RamRoleArn`
ramRoleArn	The Alibaba Cloud Resource Name (ARN) of the RAM role to assume when using the RamRoleArn authentication mode.	`[Credentials] ramRoleArn = your_ram_role_arn`
roleSessionName	The session name used in RamRoleArn mode. If this parameter is not set, a random value is generated.	`[Credentials] roleSessionName = your_ram_role_session_name`
tokenTimeout	The expiration time of the temporary token in seconds. This parameter is used in RamRoleArn mode. Default value: 3600.	`[Credentials] tokenTimeout = your_token_timeout`
ecsRoleName	The role name for the EcsRamRole authentication mode.	`[Credentials] ecsRoleName = your_ecs_role_name`

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

Command-line options

You can also specify settings by using command-line options, which take precedence over settings in the configuration file.

Option	Description	Sample code
--loglevel	The log level. By default, this parameter is empty, and no log file is generated. Valid values: info: outputs informational logs. debug: outputs detailed logs, including HTTP request and response information.	`ossutil64 commandname options --loglevel debug`
--connect-timeout	The connection timeout in seconds. Default value: 120.	`ossutil64 commandname options --connect-timeout 60`
--read-timeout	The read timeout in seconds. Default value: 1200.	`ossutil64 commandname options --read-timeout 60`
--retry-times	The number of retry attempts on error. Default value: 10.	`ossutil64 commandname options --retry-times 20`
-e, --endpoint	The request endpoint.	`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 credentials used to access OSS.	`ossutil64 commandname options -i your_access_key_id`
-k, --access-key-secret	The access credentials used to access OSS.	`ossutil64 commandname options -k your_access_key_secret`
-t, --sts-token	The STS token 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: AK, StsToken, RamRoleArn, and EcsRamRole. By default, this parameter is empty.	The following sample code shows 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 to use for authentication.	`ossutil64 commandname options --ram-role-arn your_ram_role_arn`
--role-session-name	The session name to use for authentication.	`ossutil64 commandname options --role-session-name your_ram_session_name`
--token-timeout	The token's validity duration in seconds. Default value: 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 configuration options, see Common options.

Configure access credentials

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

Using an AccessKey pair

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

Using a configuration file

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

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

Run the following command to list the objects in the bucket:

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

Using command-line options

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

Using a temporary token

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

Using a configuration file

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

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

Run the following command to list the objects in the bucket:

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

Using command-line options

You can also pass the temporary access credentials as command-line parameters. The following sample code 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 access credentials as command-line parameters poses a security risk because they may be recorded in shell history or system logs. Use this method with caution.

Using a RAM role

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

Using a configuration file

Create the following configuration file and save it to~/.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 list the objects in the bucket:

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

Using command-line options

You can also pass the access credentials as command-line parameters. The following sample code 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 access credentials as command-line parameters poses a security risk because they may be recorded in shell history or system logs. Use this method with caution.

Using an instance RAM role

On an ECS instance, you can use an instance RAM role to configure access credentials for ossutil. An instance RAM role lets you associate a role with an ECS instance and use temporary credentials from STS to run ossutil within the instance. These temporary credentials are automatically generated and rotated by the system. Your application retrieves them from a specific instance metadata URL, which eliminates the need to manage long-term keys. This method secures your AccessKey pair and enables fine-grained permission control.

Before you start, 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 an instance RAM role named EcsRamRoleOss as an example.

Using a configuration file

Create the following configuration file and save it to~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss
```
Run the following command to list the objects in the bucket:
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
```
Using command-line options

You can also pass the configuration as command-line parameters. The following sample code shows how to do this:
```
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 to manage multiple buckets in different regions, you must configure a separate endpoint for each bucket. You can do this in two ways:

Using 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 to~/.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 list the objects in the buckets:
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-jp
```
Using 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 by 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 by using a custom domain name. Before using this feature, you must map the bucket to the custom domain name in the configuration file.

In the configuration file, add a[Bucket-Cname] section to map a bucket to a custom domain name. 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 to~/.myossutilconfig.

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

Run the following command to list the objects in the bucket:

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