Object Storage Service:Configure ossutil

Version upgrade

We recommend using the newly upgraded ossutil 2.0. For quick installation and usage, see Install ossutil.

Key features of ossutil 2.0 include the following:

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

• An improved configuration management mechanism that simplifies the initial configuration process. After installation, users only need to provide the AccessKey ID, AccessKey Secret, and region ID to complete the basic configuration. 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.), with new support for multiple filter conditions based on path, file size, modification time, and object metadata to greatly improve the precision and efficiency of operations.

• Flexible output format adjustment by adding 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 the output content to obtain the required information.

• Security enhancement by supporting the setting of sensitive parameters through environment variables to avoid directly exposing keys in the command line, reducing the risk of leaks. Additionally, the new --dry-run option allows users to verify the behavior of commands before actual execution, ensuring correct operations.

Quick configuration using the config command

In most cases, you can quickly set up your ossutil tool using the config command, which provides an interactive way to generate configuration files.

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

1. Enter the configuration command.

   ossutil config

2. Set the configuration file path 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.

   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 it to another path, you need to set the --config-file option to that path when using commands):

3. Set the tool's language as prompted.

   Enter the language CH or EN. By default, the interface of ossutil is 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 only required if you access OSS using temporary access credentials provided by the Security Token Service (STS). Otherwise, you can leave this parameter empty.

   The following table describes the parameters:

   Parameter	Required	Description
   endpoint	Yes	Specify the endpoint of the region in which the bucket is located. For example, to use the public endpoint in the China (Hangzhou) region in this example, set it to https://oss-cn-hangzhou.aliyuncs.com. If you want to access OSS through other Alibaba Cloud products in the same region, use the internal endpoint and set it to https://oss-cn-hangzhou-internal.aliyuncs.com. For more information about endpoints in each region, see OSS regions and endpoints.
   accessKeyID	Yes	Specify the AccessKey of the account. For more information about how to obtain the AccessKey, see Create an AccessKey. 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 in the Resource Orchestration Service (ROS) console, select the confirmation checkbox under Security Confirmation and click Create. After the creation is complete, copy the created AccessKey in Outputs.
   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 an stsToken, see AssumeRole - Obtain temporary identity credentials for role assumption.

5. If you set the configuration file path in Step 2, you must add the -c option to specify the configuration file each time you use a command.

   For example, if the configuration file is saved as /home/config, the command format for using ls is as follows:

   ossutil -c /home/config ls oss://examplebucket

Command configuration file

You can save common credentials and configurations to the configuration file for easy use. The configuration file is in 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:

[Credentials]
language = CH

[Credentials]
accessKeyID = your_accesskey_id

[Credentials]
accessKeySecret = your_accesskey_secret

[Credentials]
stsToken = your_sts_token

[Credentials]
mode = RamRoleArn

[Credentials]
ramRoleArn = your_ram_role_arn

[Credentials]
roleSessionName = your_ram_role_seesion_name

[Credentials]
tokenTimeout = your_token_timetout

[Credentials]
ecsRoleName = your_ecs_role_name

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

Command-line options

In addition to specifying parameters in the configuration file, you can also use 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:

ossutil64 commandname options --loglevel debug

ossutil64 commandname options --connect-timeout 60

ossutil64 commandname options --read-timeout 60

ossutil64 commandname options --retry-times 20

ossutil64 commandname options -i your_access_key

ossutil64 commandname options -k your_access_key_secrect

ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token

ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK

ossutil64 commandname options --ram-role-arn your_ram_role_arn

ossutil64 commandname options --role-session-name your_ram_session_name

ossutil64 commandname options --token-timeout 1800

ossutil64 commandname options --ecs-role-name your_ecs_role_name

For more information about option configuration, see Common options.

Configure access credentials

You can configure access credentials by specifying 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 = LTAI4Fw2NbDUCV8zYUzA****
  accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****

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

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

• Specify the command-line options

  You can also specify command-line options to import the AccessKey pair. The following code provides an example:

  ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** ls oss://example-bucket

  Important

  If you specify command-line options to import the AccessKey pair, the AccessKey pair may be recorded by the log system and 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 = STS.LTAI4Fw2NbDUCV8zYUzA****
  accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
  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

  You can also specify command-line options to import the temporary access credentials. The following code provides an example:

  ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i STS.LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** -t yourSecurityToken ls oss://example-bucket

  Note

  If you specify command-line options to import the temporary access credentials, they may be recorded by the log system and are 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 = LTAI4Fw2NbDUCV8zYUzA****
  accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
  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

  You can specify command-line options to import the AccessKey pair as well. Below is an example:

  ossutil64 -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket

  Note

  If you specify command-line options to import an AccessKey pair, be aware that the AccessKey pair may be logged by the system. AccessKey pairs are highly susceptible to leakage, so proceed with caution.

Use instance RAM roles

You can attach a RAM role to an ECS instance, which allows you to access ossutil using temporary access credentials obtained from STS. These credentials are automatically generated and updated, and applications can retrieve them using the instance metadata URL. The RAM role enhances the security of your AccessKey pair and facilitates fine-grained permission control and management.

Create an instance RAM role on the ECS instance before using 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 attached to 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

  You can also specify command-line options to import the instance RAM role. The following code provides an example:

  ossutil64 -e oss-cn-hangzhou.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket

Specify endpoints for the buckets

When managing multiple buckets with ossutil, you must 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] 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: example-bucket-hz in the China (Hangzhou) region, example-bucket-bj in the China (Beijing) region, and 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 = LTAI4Fw2NbDUCV8zYUzA****
  accessKeySecret = LTAI4Fw2NbDUCV8zYUzA****
  [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: example-bucket-hz in the China (Hangzhou) region, example-bucket-bj in the China (Beijing) region, and example-bucket-sh in the China (Shanghai) region.

  Specify the account information in ~/.myossutilconfig.

  [Credentials]
  endpoint = oss-cn-hangzhou.aliyuncs.com
  accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
  accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****

  Specify the endpoint 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 custom Domain Names

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

Add a [Bucket-Cname] section in the configuration file 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.

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

[Credentials]
accessKeyID = LTAI4Fw2NbDUCV8zYUzA****
accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
[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