All Products
Search
Document Center

Object Storage Service:Configure ossutil

Last Updated:Apr 24, 2025

This topic describes how to configure ossutil. You will learn how to use ossutil more effectively through this topic.

Version upgrade

We recommend that you use the newly upgraded ossutil 2.0 for quick installation and use. For more information, see Install ossutil.

Key features of ossutil 2.0:

  • Brand new command organization structure: Introduces multi-level command support, including API-level commands (such as ossutil api put-bucket-acl) and advanced commands (such as ossutil config).

  • Improved configuration management mechanism: Simplifies the initial configuration process. Users only need to provide AccessKey ID, AccessKey Secret, and region ID to complete the basic configuration after installation. It also supports specifying multiple configuration files through the --profile parameter, enhancing flexibility.

  • Rich filtering parameters: For batch processing commands (such as ls, cp, rm, etc.), it adds support for various filtering conditions based on path, file size, modification time, and object metadata, greatly improving the precision and efficiency of operations.

  • Flexible output format adjustment: Adds the --output-format parameter, allowing users to set the output format to JSON, YAML, or XML to better adapt to different data processing needs. It also introduces the --output-query option, enabling users to filter output content and obtain the required information.

  • Enhanced security: To improve security, ossutil 2.0 supports setting sensitive parameters through environment variables, avoiding direct exposure of keys in the command line and reducing the risk of leakage. In addition, the new --dry-run option allows users to verify the behavior of commands before actual execution, ensuring 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.

  1. Enter the configuration command.

    ossutil config
  2. Set the path of the configuration file as prompted.

    You can specify the path of the configuration file based on your business requirements. By default, the configuration file is saved to the ~/.ossutilconfig file. Press Enter to use the default configuration.

    Please enter the configuration file name, which can include a path (default: /home/user/.ossutilconfig, press Enter to use the default path. If you set it to another path, you need to set the --config-file option to this path when using commands):
  3. Set the language of the tool as prompted.

    Enter CH or EN for the language. By default, ossutil is displayed in the language that is used by the operating system. The configuration takes effect after the config command is successfully run.

  4. Set the Endpoint, AccessKey ID, AccessKey Secret, and STSToken parameters as prompted. 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 list describes the involved parameters:

    Parameter

    Required

    Description

    endpoint

    Yes

    Specify the endpoint of the region in which the bucket is located. For example, in this example, the public endpoint of China (Hangzhou) is used, which is set to https://oss-cn-hangzhou.aliyuncs.com.

    If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use the internal endpoint, which is set to https://oss-cn-hangzhou-internal.aliyuncs.com.

    For more information about the endpoints of each region, see OSS regions and endpoints.

    accessKeyID

    Yes

    Enter the AccessKey of your account. For more information about how to obtain an AccessKey pair, see Create an AccessKey pair.

    Use a Resource Orchestration Service (ROS) script to quickly create an AccessKey pair for a RAM user that has the permissions to manage OSS

    On the Create Stack page of the Resource Orchestration Service console, select the confirmation under Security Confirmation, and then click Create.

    1.png

    After the creation is complete, copy the created AccessKey from Outputs.

    image

    accessKeySecret

    Yes

    stsToken

    Optional

    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 an stsToken, see AssumeRole - Obtain temporary identity credentials for a role.

  5. If you set the path of 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, when you use ls, the command format is as follows:

    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:

Configuration 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-hangzhou.aliyuncs.com

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 = your_accesskey_secret

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 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 more command configuration parameters, see Edit 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-hangzhou.aliyuncs.com

-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

Specifies the role name in EcsRamRole mode for authentication.

ossutil64 commandname options --ecs-role-name your_ecs_role_name

For more option configurations, 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

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

    [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 AccessKey pair:

    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 AccessKey pair, the AccessKey pair 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

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

    [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

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

    [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 AccessKey pair:

    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 AccessKey pair, the AccessKey pair 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 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 ensures the security of your AccessKey pair and facilitates fine-grained permission control and management.

Create an instance RAM role before you use it. For more information, see Create an instance RAM role.

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

  • Specify the parameters in the configuration file

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

    [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 AccessKey pair:

    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.

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

    [Credentials]
    endpoint = oss-cn-hangzhou.aliyuncs.com
    accessKeyID = yourAccessKeyID
    accessKeySecret = yourAccessKeySecret
    [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.

    Configure the account information in ~/.myossutilconfig.

    [Credentials]
    endpoint = oss-cn-hangzhou.aliyuncs.com
    accessKeyID = yourAccessKeyID
    accessKeySecret = yourAccessKeySecret

    Specify the endpoint by using 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

Configure 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 an endpoint 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.

Generate 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 query the objects in the bucket.

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