This topic describes how to configure ossutil.
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:
./ossutil64 config
- Follow the on-screen instructions to specify 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 file is generated in the default path. If you want to store the file in another path, set the --config-file option to the path.
- Follow the on-screen instructions to specify the display language of ossutil.
Enter CH or EN. By default, ossutil is displayed in the language that is used by the operating system. The configuration takes effect after you run the config command.
- Follow the on-screen instructions to specify the following parameters: endpoint, accessKeyID, accessKeySecret, and stsToken. The following table describes the parameters.
Parameter Description endpoint Specify the endpoint of the region in which the bucket is located. For more information about the relationship between regions and endpoints, see Regions and endpoints. You can also add
http://
orhttps://
to specify the protocol that you want ossutil to use to access Object Storage Service (OSS). The default protocol is HTTP. For example, if you want to access a bucket in the China (Hangzhou) region by using HTTPS, set the endpoint tohttps://oss-cn-hangzhou.aliyuncs.com
.accessKeyID Specify the AccessKey pair of the Alibaba Cloud account or the RAM user that you want to use to access OSS. - For more information about how to obtain the AccessKey pair of an Alibaba Cloud account or a RAM user, see Obtain an AccessKey pair.
- For more information about how to obtain the AccessKey pair provided by Security Token Service (STS) that you can use as temporary credentials to access OSS, see Use temporary credentials provided by STS to access OSS.
accessKeySecret stsToken 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 Authorized third-party upload. Note For more information about the configuration file, see config. - 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:
./ossutil64 -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:
|
|
endpoint | The endpoint of the region in which the bucket is located. |
|
accessKeyID | The AccessKey ID that uniquely identifies a user. |
|
accessKeySecret | The AccessKey secret that authenticates the identity of the user. |
|
stsToken | The security token that is used to authenticate the request. |
|
mode | The mode used for authentication. Valid values: AK, StsToken, RamRoleArn, and EcsRamRole. |
|
ramRoleArn | The Alibaba Cloud Resource Name (ARN) of the RAM role in RamRoleArn mode for authentication. |
|
roleSessionName | The name of the session in RamRoleArn mode for authentication. If you do not specify this parameter, a random value is generated. |
|
tokenTimeout | The validity period of the security token. This parameter is used in RamRoleArn mode. Unit: seconds. Default value: 3600. |
|
ecsRoleName | The role name in EcsRamRole mode for authentication. |
|
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:
|
|
--connect-timeout | The timeout period for the client to connect to the server. Default value: 120. Unit: seconds. |
|
--read-timeout | The timeout period for the client to read data from the server. Default value: 1200. Unit: seconds. |
|
--retry-times | The number of times an operation is retried if the operation fails. Default value: 10. |
|
-e, --endpoint | The domain name to which the request is sent. |
|
-i, --access-key-id | The Accesskey ID that you want to use to access OSS. |
|
-k, --access-key-secret | The Accesskey secret that you want to use to access OSS. |
|
-t, --sts-token | The security token that you want to use to access OSS. |
|
--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:
|
--ram-role-arn | The ARN of the RAM role in RamRoleArn mode for authentication. |
|
--role-session-name | The name of the session in authentication mode. |
|
--token-timeout | The validity period of the security token. Unit: seconds. Default value: 3600. |
|
--ecs-role-name | The role name in EcsRamRole mode for authentication. |
|
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
The following configuration file is generated and saved as ~/.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
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 LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** 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
The following configuration file is generated and saved as ~/.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
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 STS.LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** -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
The following configuration file is generated and saved as ~/.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
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 LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H**** --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 ossutil access credentials on Elastic Compute Service (ECS) instances. You can attach a RAM role to an ECS instance to access OSS from the instance by using temporary access credentials that are obtained from STS. STS temporary access credentials are automatically generated and updated. Applications can obtain 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 on the ECS instance before you use it. For more information, see Overview.
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
The following configuration file is generated and saved as ~/.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 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.
The following configuration file is generated and saved as ~/.myossutilconfig.
[Credentials] endpoint = oss-cn-hangzhou.aliyuncs.com accessKeyID = LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = LTAI4Fw2NbDUCV8zYUzA**** [Bucket-Endpoint] 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 = LTAI4Fw2NbDUCV8zYUzA**** accessKeySecret = 67DLVBkH7EamOjy2W5RVAHUY9H****
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.
The following configuration file is generated, and the configuration file is saved as ~/.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