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

This topic describes how to configure ossutil.

Prerequisites

ossutil is installed.
Object Storage Service (OSS) is activated.

Basic configurations (required)

Important

To prevent operation failures caused by unspecified parameters when you use ossutil, we recommend that you perform the following steps to configure the AccessKey ID, AccessKey secret, and region ID.

Linux

Run the following command to specify parameters:

ossutil config

Configure the path of the configuration file. You can press the Enter key to use the default path of the configuration file.

Please enter the config file name,the file name can include path(default /root/.ossutilconfig, carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

By default, ossutil uses /root/.ossutilconfig as the configuration file.

Specify the AccessKey ID, AccessKey secret, and region ID based on the on-screen instructions.
Enter the AccessKey ID that you created.
```
Please enter Access Key ID [****************id]:LTAI****************
```
Enter the AccessKey secret that you created.
```
Please enter Access Key Secret [****************sk]:R6vg*********************
```
Enter the ID of the region in which the bucket that stores your data is located. Default value: cn-hangzhou.
```
Please enter Region [cn-hangzhou]:cn-hangzhou
```
In this example, the ID of the China (Hangzhou) region is used. For more information about the IDs of other regions, see OSS regions and endpoints.

Windows

Run the following command to specify parameters:

ossutil config

Configure the path of the configuration file. You can press the Enter key to use the default path of the configuration file.

Please enter the config file name,the file name can include path(default "C:\Users\issuser\.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

By default, ossutil uses C:\Users\issuser\.ossutilconfig as the configuration file.

Specify the AccessKey ID, AccessKey secret, and region ID based on the on-screen instructions.
Enter the AccessKey ID that you created.
```
Please enter Access Key ID [****************id]:LTAI****************
```
Enter the AccessKey secret that you created.
```
Please enter Access Key Secret [****************sk]:R6vg*********************
```
Enter the ID of the region in which the bucket that stores your data is located. Default value: cn-hangzhou.
```
Please enter Region [cn-hangzhou]:cn-hangzhou
```
In this example, the ID of the China (Hangzhou) region is used. For more information about the IDs of other regions, see OSS regions and endpoints.

macOS

Run the following command to specify parameters:
```
ossutil config
```

Configure the path of the configuration file. You can press the Enter key to use the default path of the configuration file.

Please enter the config file name,the file name can include path(default "/Users/user/.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

By default, ossutil uses /Users/user/.ossutilconfig as the configuration file.

Specify the AccessKey ID, AccessKey secret, and region ID based on the on-screen instructions.
Enter the AccessKey ID that you created.
```
Please enter Access Key ID [****************id]:LTAI****************
```
Enter the AccessKey secret that you created.
```
Please enter Access Key Secret [****************sk]:R6vg*********************
```
Enter the ID of the region in which the bucket that stores your data is located. Default value: cn-hangzhou.
```
Please enter Region [cn-hangzhou]:cn-hangzhou
```
In this example, the ID of the China (Hangzhou) region is used. For more information about the IDs of other regions, see OSS regions and endpoints.

Configuration methods

You can configure ossutil by using multiple methods, including configuration files, environment variables, and command-line options.

Configuration files: Configuration files are in the INI file format, in which you can specify parameters.
Command-line options: ossutil provides multiple command-line options to configure ossutil. Command-line options take the highest precedence and overwrite the settings in configuration files and environment variables.
Important
If you specify the command-line options to import 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.
Environment variables: ossutil supports multiple environment variables that take precedence over configuration files. You can configure ossutil by using these variables.

Configuration files

You can configure ossutil by using a configuration file. The default path of the configuration file is ~/.myossutilconfig. You can specify a custom path for the configuration file by using the -c option. To use the default path of the configuration file, you do not need to specify any parameters. Instead, run the following command:

ossutil ls oss://examplebucket

To specify a custom path for the configuration file, such as /path/yourconfig, use the -c option. Example:

ossutil -c /path/yourconfig ls oss://examplebucket

Configuration file format

A configuration file is in the INI file format. An INI configuration file consists of sections. The settings in a configuration file are categorized into sections. You can use the --profile option to specify a specific section for ossutil to use. By default, ossutil uses settings in the [default] section of a configuration file. You can create and reference other settings.

Sections and key-value pairs

Each section in a configuration file is identified by a name enclosed in square brackets ([]), and parameters in a section are in the key=value format. Example:

[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"

The parameters in sections are in the key=value format.
Section names and key names are case-insensitive.
Keys can be in lowercase and small camel case. Words in a key can be separated by a hyphen character (-) or an underscore character (_). For example, you can set an AccessKey ID in a configuration file by using accesskeyid, accessKeyId, access-key-id, or access_key_id.
Comments start with a number sign (#).

Supported section types

Section	Description	Additional information
[default]	Contains default settings. If you do not specify the --profile option in a command, ossutil uses the settings in the default section.	The full form of the [default] section is [profile default].
[profile name]	Contains custom settings. You can use the settings in the section by specifying the --profile option in a command.	You can use source_profile to reference the configuration settings in a specific profile section.
[buckets name]	Contains bucket-specific settings, including the region, endpoint, and addressing style.	This section type supports inline arrangement of key-value pairs.

Note

You can use the config command to query and configure the settings in a configuration file. For more information, see config.

Section type: profile

A profile section can be used to configure access credential-related parameters and global options. A profile section can contain the following information:

Access credential-related parameters

Parameter	Alias	Description
mode	/	The authentication mode. Valid values: AK, StsToken, RamRoleArn, EcsRamRole, and Anonymous.
access-key-id	accessKeyId access_key_id	The AccessKey ID.
access-key-secret	accessKeySecret access_key_secret	The AccessKey secret.
sts-token	stsToken sts_token	The token issued by Security Token Service (STS).
role-arn	roleArn role_arn	The Alibaba Cloud Resource Name (ARN) of the RAM role. This parameter is used in the RamRoleArn authentication mode.
role-session-name	roleSessionName role_session_name	The session name. This parameter is used in the RamRoleArn authentication mode.
ecs-role-name	ecsRoleName ecs_role_name	The role name. This parameter is used in the EcsRamRole authentication mode.
credential-process	credentialProcess credential_process	Specifies an external command.
credential-uri	credentialUri credential_uri	The URI from which ossutil obtains access credentials.
oidc-provider-arn	oidcProviderArn oidc_provider_arn	The ARN of the OpenID Connect (OIDC) identity provider (IdP). The ARN is in the `acs:ram::account-id:oidc-provider/provider-name` format.
oidc-token-file-path	oidcTokenFilePath oidc_token_file_path	The path of the OIDC token.
credential-process-timeout	credentialProcessTimeout credential_process_timeout	Specifies the timeout period of requests initiated by using external credentials. Unit: seconds. The default value is 15, which indicates that the timeout period is 15 seconds. The maximum value is 600(10 mins), which indicates that the timeout period is 10 minutes. `credential-process-timeout = 60` indicates that the timeout period of a request initiated by using external credentials is 60 seconds.

Global parameters

Parameter	Alias	Description
region	/	The ID of the region. This parameter is required.
loglevel	/	The log severity level. Valid values: off (default) info debug
read-timeout	readTimeout read_timeout	The timeout period in seconds for client read and write requests. Default value: 20.
connect-timeout	connectTimeout connect_timeout	The timeout period in seconds for client connections. Default value: 10.
retry-times	retryTimes retry_times	The number of retries when an error occurs. Default value: 10.
skip-verify-cert	skipVerifyCert skip_verify_cert	Specifies that the digital certificate of the server is not verified.
sign-version	signVersion sign_version	The version of the signature algorithm. Valid values: v1 v4 (default)
output-format	outputFormat output_format	The format of the output. Valid values: raw (default) json xml yaml
addressing-style	addressingStyle addressing_style	The type of the address. Valid values: virtual (default) path cname
language	/	The display language.
endpoint	/	The endpoint of the region. This parameter is optional.

Other parameters

Parameter

Alias

Description

source-profile

sourceProfile

source_profile

References parameters in the specified profile section. Example:

[profile cred]
access-key-id=ak
access-key-secret=sk

[profile dev]
region=cn-hangzhou
source-profile=cred

buckets

References parameters in the specified buckets section.

[profile dev]
region=cn-hangzhou
access-key-id=ak
access-key-secret=sk
buckets=dev-bucket

[bucktes dev-bucket]
bucket-name-hz =
 endpoint=oss-cn-hangzhou-internal.aliyuncs.com
bucket-name-bj =
 region=cn-beijing

Section type: buckets

A buckets section stores mappings between buckets and endpoints. A buckets section contains key=value pairs nested within a key that represents a bucket name:

[buckets name]
bucket-name = 
  key=value

The name is the name of the buckets section, bucket-name is the name of the bucket, and key=value is a configuration item. You can specify bucket-specific parameters in a buckets section. The following table describes the parameters.

Parameter	Alias	Description
region	/	The region in which the data center is located. If you leave this parameter empty, ossutil uses the region parameter in a referenced profile section of the configuration file.
endpoint	/	The endpoint of the region. This parameter is optional.
addressing-style	addressingStyle addressing_style	The type of the address. Valid values: virtual (default): uses the virtual bucket domain. path: uses the path-style address. cname: uses CNAME.

The following lines provide an example of a buckets section:

[buckets dev-bucket]
bucket-hz-01 = 
  region=cn-hangzhou
bucket-hz-02 = 
  region=cn-hangzhou
  endpoint=test.com
  addressing-style=cname
bucket-bj-01 = 
  region=cn-beijing

Command-line options

When you run ossutil commands, you can directly pass configurations by using command-line options. This method is suitable for temporary configuration requirements. Example:

ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret"

The following command-line options are supported:

Parameter	Type	Description
-i, --access-key-id	string	The AccessKey ID.
-k, --access-key-secret	string	The AccessKey secret.
--addressing-style	string	The type of the address. Valid values: virtual (default): the virtual hosting mode. path: the path mode. cname: the custom domain name mode.
-c, --config-file	string	The path of the configuration file. Default value: `~\.ossutilconfig`.
--connect-timeout	int	The timeout period in seconds for client connections. Default value: 10. Unit: seconds.
-n, --dry-run	/	Performs a trial run without making changes.
-e, --endpoint	string	The endpoint of the region.
-h, --help	/	Displays help information of a specific command.
--language	string	The display language.
--loglevel	string	The log level. Valid values: off (default) info debug
--mode	string	The authentication mode. Valid values: AK: the AccessKey pair. StsToken: the temporary access credentials. EcsRamRole: the RAM role attached to the Elastic Compute Service (ECS) instance. Anonymous: anonymous access.
--output-format	string	The output format. Default value: raw.
--output-query	string	The JMESPath query condition.
--profile	string	Specifies the profile in the configuration file.
-q, --quiet	/	Enables the quiet mode to print the least information.
--read-timeout	int	The timeout period in seconds for client read and write requests. Unit: seconds. Default value: 20.
--region	string	The region in which the data center is located. Example: cn-hangzhou.
--retry-times	int	The number of retries when an error occurs. Default value: 10.
--sign-version	string	The version of the signature algorithm. Valid values: v1 v4 (default)
--skip-verify-cert	/	Specifies that the digital certificate provided by the server is not verified.
-t, --sts-token	string	The token issued by STS.
--proxy	string	The proxy server. Configuration methods: Direct configuration: You can directly specify the proxy server. Examples: `http://proxy.example.com:8080` `https://proxy.example.com:8443` `env`: use the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to obtain the proxy server information. You need to configure these environment variables in the operating system. Examples: `HTTP_PROXY=http://proxy.example.com:8080` `HTTPS_PROXY=https://proxy.example.com:8443` After you configure these environment variables, you can set the value of the proxy server option to `env`. Then, the system automatically uses the proxy settings specified by these environment variables.
--log-file	string	The log output file. Valid values: `-`: Logs are exported to stdout. `File path`: After you specify a specific file path, logs are exported to the file. If you do not specify a specific file path, logs are exported to the default configuration file.

Environment variables

You can perform the following steps to configure environment variables.

Linux

Run the following command:

export OSS_ACCESS_KEY_ID="your-access-key-id"
export OSS_ACCESS_KEY_SECRET="your-access-key-secret"

Run the following command to check whether the environment variables take effect:
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS

Run the following command:

export OSS_ACCESS_KEY_ID="your-access-key-id"
export OSS_ACCESS_KEY_SECRET="your-access-key-secret"

Run the following command to check whether the environment variables take effect:
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

Windows

Run the following command in CMD:

set OSS_ACCESS_KEY_ID "your-access-key-id"
set OSS_ACCESS_KEY_SECRET "your-access-key-secret"

Open a new window.
Run the following command to check whether the environment variable takes effect in the new window:
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

The following table describes the environment variables supported by ossutil.

Environment variable	Corresponding parameter name
OSS_ACCESS_KEY_ID	access-key-id
OSS_ACCESS_KEY_SECRET	access-key-secret
OSS_SESSION_TOKEN	sts-token
OSS_ROLE_ARN	ram-role-arn
OSS_ROLE_SESSION_NAME	role-session-name
OSS_REGION	region
OSS_ENDPOINT	endpoint
OSSUTIL_CONFIG_FILE	config-file
OSSUTIL_PROFILE	profile

Examples

You can configure different types of access credentials and query objects in the examplebucket bucket by using configuration files, environment variables, or command-line options.

Long-term access credentials

By using a configuration file

Create a configuration file named ~/.myossutilconfig and store the following settings in the configuration file:

[default]
accessKeyID = LTAI4Fw2NbDUCV8z********
accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
region=cn-hangzhou

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig

By using environment variables

export OSS_ACCESS_KEY_ID=LTAI4Fw2NbDUCV8z********
export OSS_ACCESS_KEY_SECRET=67DLVBkH7EamOjy2W5RVAH********
ossutil ls oss://examplebucket

By using command line options

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

ossutil ls oss://examplebucket -i LTAI4Fw2NbDUCV8z******** -k 67DLVBkH7EamOjy2W5RVAH********

Temporary access credentials

By using a configuration file

Create a configuration file named ~/.myossutilconfig and store the following settings in the configuration file:

[default]
accessKeyID = STS.LTAI4Fw2NbDUCV8z********
accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
stsToken = yourSecurityToken
region=cn-hangzhou

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig

By using environment variables

export OSS_ACCESS_KEY_ID=STS.LTAI4Fw2NbDUCV8z********
export OSS_ACCESS_KEY_SECRET=67DLVBkH7EamOjy2W5RVAH********
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

By using command line options

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

ossutil ls oss://examplebucket -i STS.LTAI4Fw2NbDUCV8z******** -k 67DLVBkH7EamOjy2W5RVAH******** -t yourSecurityToken

Access credentials for a RAM user

Note

You cannot configure this type of access credentials by using environment variables or command-line options.

By using a configuration file

Create a configuration file named ~/.myossutilconfig and store the following settings in the configuration file:

[default]
accessKeyID = LTAI4Fw2NbDUCV8z********
accessKeySecret = 67DLVBkH7EamOjy2W5RVAH********
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=cn-hangzhou

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig

Access credentials for a RAM role of an ECS instance

Note

You cannot configure this type of access credentials by using environment variables.

By using a configuration file

Create a configuration file named ~/.myossutilconfig and store the following settings in the configuration file:

[default]
mode = EcsRamRole
# The ecsRoleName parameter is optional. If you do not set this parameter, the value is automatically obtained. 
ecsRoleName = EcsRamRoleOss 
region=cn-hangzhou

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig

By using command-line options (not recommended)

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

ossutil ls oss://examplebucket --mode EcsRamRole

OIDC access credentials

Note

You cannot configure this type of access credentials by using environment variables or command-line options.

For more information about OIDC role-based SSO, see Overview of OIDC-based SSO.

By using a configuration file

Create a configuration file named ~/.myossutilconfig and store the following settings in the configuration file:

[default]
mode = oidcRoleArn
# Provide the ARN of the OIDC IdP in the acs:ram::account-id:oidc-provider/provider-name format. 
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Specify the path of the OIDC token.
OIDCTokenFilePath=OIDCTokenFilePath
# Specify the ARN of the role, that is, the ID of the role. Format: acs:ram::113511544585****:oidc-provider/TestOidcProvider.
roleArn=acs:ram::113511544585****:role/testoidc
# Specify the session name, which is used to differentiate tokens. 
roleSessionName= TestOidcAssumedRoleSession
region=cn-hangzhou

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig

Obtain access credentials by using external processes

ossutil uses an external command to start an external process, which is separate from the ossutil process. An external process returns the output to ossutil by using the standard output. You can obtain access credentials by using an external process.

Note

To mitigate security risks, you must authorize only intended processes or users to run the command to generate access credentials.
The command for generating access credentials does not write confidential information to stdrr or stdout to prevent the information from being captured or recorded. Captured or recorded information may be exposed to unauthorized users.

An external command can return long-term and temporary access credentials.

Long-term access credentials

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
}

Temporary access credentials

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2023-12-29T07:45:02Z",
  "SecurityToken" : "token",
}

Note

You cannot configure this type of access credentials by using environment variables or command-line options.

By using a configuration file

Create a configuration file named ~/.myossutilconfig and store the following settings in the configuration file:

[default]
mode = Process
credentialProcess = user-cmd
region=cn-hangzhou

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

ossutil ls oss://examplebucket -c ~/.myossutilconfig