Use the config command to create a configuration file for ossutil - Object Storage Service

Use the config command to create a configuration file that stores your OSS access credentials. Once configured, ossutil reads credentials from this file automatically—no need to pass them on every command.

Important

ossutil 1.6.16 and later use ossutil as the binary name on all operating systems. For earlier versions, update the binary name based on your OS. For details, see ossutil command reference.

Prerequisites

Before you begin, ensure that you have:

ossutil installed on your machine
An Alibaba Cloud account with OSS access
Your credentials ready (AccessKey pair, Security Token Service (STS) token, or RAM role ARN—depending on your authentication method)

How it works

Running ossutil config generates a configuration file with sections for credentials, per-bucket endpoints, and advanced defaults. When you run other ossutil commands, ossutil reads from this file unless you override settings with command-line options.

Endpoint configuration takes effect in this priority order (highest to lowest):

--endpoint option passed directly in a command
[Bucket-Cname] section in the configuration file
[Bucket-Endpoint] section in the configuration file
[Credentials] section in the configuration file

Choose your authentication method

Identify which credentials you have before running config:

Authentication method	When to use	Required parameters
AccessKey pair	Standard access using your Alibaba Cloud account or RAM user	`-i` (AccessKey ID), `-k` (AccessKey secret)
STS temporary credentials	Short-lived access granted by STS	`-i`, `-k`, `-t` (STS token)
RAM role ARN	Access as a RAM user by assuming a role via AssumeRole	`--ram-role-arn`
ECS instance RAM role	Access from an Elastic Compute Service (ECS) instance with an attached RAM role	Configure `[AkService]` in the file directly—no AccessKey needed

Command syntax

ossutil config
[-e, --endpoint <value>]
[-i, --access-key-id <value>]
[-k, --access-key-secret <value>]
[-t, --sts-token <value>]
[--ram-role-arn <value>]
[-L language <value>]
[--output-dir <value>]
[-c, --config-file <value>]

ossutil supports two modes:

Interactive mode — Run ossutil config with no parameters. ossutil prompts you for each value. Compared with the non-interactive mode, the interactive mode provides higher security.
Non-interactive mode — Pass all parameters directly in the command. If you specify any parameter other than -L or -c, ossutil uses non-interactive mode and requires all parameters to be provided.

Options

Option	Description
`-e, --endpoint`	Endpoint of the region where your bucket is located. Prefix with `http://` or `https://` to specify the protocol. Default protocol: HTTP. For region endpoints, see Regions and endpoints.
`-i, --access-key-id`	AccessKey ID stored in the `[Credentials]` section. See Obtain an AccessKey pair.
`-k, --access-key-secret`	AccessKey secret stored in the `[Credentials]` section. See Obtain an AccessKey pair.
`-t, --sts-token`	STS token for temporary access credentials. Required only when using STS. See Use temporary access credentials provided by STS to access OSS.
`--ram-role-arn`	Alibaba Cloud Resource Name (ARN) of the RAM role in RamRoleArn mode. Required only when calling AssumeRole as a RAM user.
`-L language`	Display language for ossutil. `CH` for Chinese (requires UTF-8 encoding); `EN` for English.
`--output-dir`	Directory for output files, including error reports generated by the `cp` command. Default: `ossutil_output` in the current directory.
`-c, --config-file`	Path to the ossutil configuration file. Default: `/home/user/.ossutilconfig`.

Examples

Interactive mode

Run ossutil config and follow the prompts:

ossutil config
Specify the name of the configuration file. The file name can contain the file path. The default file name is /home/user/.ossutilconfig. If you press the Enter key without specifying a file path, the configuration file is generated in the default path.
If you want to store the configuration file in another path, set the --config-file option to the file path.
If you do not specify the path of the configuration file, the default configuration file named /home/user/.ossutilconfig is used.
If you press the Enter key without specifying the following parameters, these parameters are ignored. For more information about the parameters, run the help config command.
Enter the endpoint: https://oss-cn-shenzhen.aliyuncs.com
Enter the AccessKey ID: yourAccessKeyID
Enter the AccessKey secret: yourAccessKeySecret
Enter the STS token: yourStsToken

Non-interactive mode

Pass all options in a single command:

ossutil config -e oss-cn-beijing.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret -L CH -c /myconfig

Modify the configuration file

Edit the configuration file directly to update credentials or add per-bucket settings.

[Credentials]
        language = CH
        endpoint = oss.aliyuncs.com
        accessKeyID = your_accesskey_id
        accessKeySecret = your_accesskey_secret
        stsToken = your_sts_token
        outputDir = your_output_dir
        ramRoleArn = your_ram_role_arn
[Bucket-Endpoint]
        bucket1 = endpoint1
        bucket2 = endpoint2
        ...
[Bucket-Cname]
        bucket1 = cname1
        bucket2 = cname2
        ...
[AkService]
        ecsAk=http://100.100.100.200/latest/meta-data/ram/security-credentials/EcsRamRoleTesting
[Default]
        userAgent = user_agent
        loglevel = log_level
        proxyHost = proxy_host
        proxyUser = proxy_user
        proxyPwd = proxy_pwd
        readTimeOut = read_time_out
        connectTimeOut = connect_time_out
        retryTimes = retry_times

Configuration sections

`[Bucket-Endpoint]`

Assign a specific endpoint to individual buckets.

`[Bucket-Cname]`

Assign a custom domain name (CNAME) to individual buckets. For details, see Map custom domain names.

In ossutil V1.7.15 and later, you do not need to specify [Bucket-Endpoint] or [Bucket-Cname] in interactive mode. You can specify an endpoint or a CNAME for each bucket in the configuration file.

`[AkService]`

Use an ECS instance RAM role instead of an AccessKey pair. Set EcsRamRoleTesting to the name of the RAM role attached to the instance. After configuring this section, you do not need to specify the AccessKey ID, AccessKey secret, or STS token.

Important

If you also specify an AccessKey ID in [Credentials], the [AkService] configuration does not take effect. The AccessKey ID, AccessKey Secret, and STSToken configurations are used to verify your identity. For details on attaching a RAM role to an ECS instance, see Instance RAM roles.

`[Default]`

Override default values for common parameters such as proxy settings, timeouts, and retry behavior. Supported in ossutil V1.7.15 and later. For available parameters, see View options.