All Products
Search
Document Center

Object Storage Service:View options

Last Updated:Oct 11, 2023

This topic describes how to run the -h command to view all options supported by ossutil.

Note

This topic provides sample command lines that are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. For more information, see ossutil.

Command syntax

./ossutil64 -h

To view the options supported by a command, run the ./ossutil64 help [command] command, such as ./ossutil64 help cp.

Common options

The following table describes the common options that can be added to most commands supported by ossutil.

Option

Description

-c, --config-file

Specifies the path of the configuration file of ossutil. When ossutil is started, it reads the configuration file. When you manage buckets that belong to different Alibaba Cloud accounts, you can generate multiple configuration files and specify one of the configuration files as the default configuration file. When you manage a bucket that belongs to another Alibaba Cloud account, you can use the -c option to specify the configuration file.

-e, --endpoint

Specifies the endpoint of the region in which the bucket is located. When you manage buckets across regions, you can use this option to specify the endpoints of the regions. For more information about the endpoints of each region, see Regions and endpoints.

-i, --access-key-id

Specifies the AccessKey ID that is used to access Object Storage Service (OSS). When you manage buckets that belong to different Alibaba Cloud accounts, you can use this option to specify the AccessKey IDs.

-k, --access-key-secret

Specifies the AccessKey secret that is used to access OSS. When you manage buckets that belong to different Alibaba Cloud accounts, you can use this option to specify the AccessKey secrets.

-p, --password

Specifies the AccessKey secret that is used to access OSS. When you use this option in a command, ossutil reads the AccessKey secret that is entered by using the keyboard and ignores the AccessKey secret that is configured by using other methods.

--loglevel

Generates the ossutil.log file in the current working directory. This option is empty by default, which specifies that no log files are generated.

Valid values:

  • info: ossutil displays operations logs.

    ./ossutil64 [command] --loglevel=info
  • debug: ossutil displays logs that contain HTTP requests and responses and the original signature strings, which can be used to locate problems.

    ./ossutil64 [command] --loglevel=debug

--proxy-host, --proxy-user, and --proxy-pwd

If your environment requires a proxy server to access the service, you must use the three options to specify the information of the proxy server.

  • --proxy-host: specifies the URL of the proxy server. This option supports HTTP, HTTPS, and SOCKS5.

  • --proxy-user: specifies the username that is used to access the proxy server. This option is empty by default.

  • --proxy-pwd: specifies the password that is used to access the proxy server. This option is empty by default.

After you specify the information of the proxy server by using the three options, ossutil uses the proxy server to access OSS.

./ossutil64 ls oss://bucket1 --proxy-host http://47.88.**.**:3128 --proxy-user test --proxy-pwd test

--mode

Specifies the type of your credentials. Valid values:

  • AK: The AccessKey ID and AccessKey secret are used for authentication.

  • StsToken: A Security Token Service (STS) token is used for authentication.

  • RamRoleArn: The AssumeRole method of Resource Access Management (RAM) is used for authentication.

  • EcsRamRole: The EcsRamRole method in an Elastic Compute Service (ECS) instance is used for password-free authentication.

If you do not configure this option, the default authentication logic is used.

--ecs-role-name

Specifies the role name in EcsRamRole mode for authentication.

--token-timeout

Specifies the validity period of the token obtained by using AssumeRole in RamRoleArn mode for authentication. Default value: 3600. Unit: seconds.

--ram-role-arn

Specifies the Alibaba Cloud Resource Name (ARN) of the RAM role in RamRoleArn mode for authentication.

--role-session-name

Specifies the session name in RamRoleArn mode for authentication.

--read-timeout

Specifies the timeout period for the client to read data. Default value: 1200. Unit: seconds.

--connect-timeout

Specifies the timeout period for the client to connect to the server. Default value: 120. Unit: seconds.

--sts-region

Specifies the region where STS is connected. Example: cn-hangzhou. For more information about all access regions supported by STS, see Access regions.

If you do not configure this option, the default value of this option in RamRoleArn mode for authentication is sts.aliyuncs.com.

--skip-verify-cert

Specifies that the digital certificate of the server is not verified.

--ua

Specifies the value of the User-Agent header. If you specify a value for this option, the value is automatically added to the end of the User-Agent value that is specified by ossutil. If you want to view the complete value of User-Agent in logs, use the --loglevel debug option together with this option.

Other options

The following table describes the options included in ossutil commands other than the preceding common options.

Option

Description

-s, --short-format

Displays items in the short format. If you do not specify this option, the long format is used.

--bigfile-threshold

Specifies the size threshold over which a large object starts resumable upload. Default value: 104857600 (100 MB). Valid values: 0 to 9223372036854775807. Unit: bytes.

--acl

Specifies the access control list (ACL) of the object.

--range

Specifies the byte range of the object to download. Bytes are numbered starting from 0.

  • You can specify a range. For example, 3-9 specifies a range from byte 3 (inclusive) to byte 9 (inclusive).

  • You can specify the field from which the download starts. For example, 3- specifies a range from byte 3 (inclusive) to the end of the object (inclusive).

  • You can specify the field at which the download ends. For example, -9 specifies a range from byte 0 (inclusive) to byte 9 (inclusive).

--all-versions

Specifies all versions of an object.

--type

Specifies the algorithm that is used for data verification. Valid values:

  • crc64 (default)

  • md5

-v, --version

Displays the ossutil version and exits.

-u, --update

Specifies an update operation.

--origin

Specifies the value of the Origin header in an HTTP request.

--upmode

Specifies the upload method that is used in the probe command. Valid values:

  • normal (default): The object is uploaded by using simple upload.

  • append: The object is uploaded by using append upload.

  • multipart: The object is uploaded by using multipart upload.

--sse-algorithm

Specifies the encryption method for the bucket. Valid values:

  • KMS: The keys managed by Key Management Service (KMS) are used for encryption and decryption (SSE-KMS).

  • AES256: The keys managed by OSS are used for encryption and decryption (SSE-OSS).

--include

Specifies that objects that meet the specified conditions are listed. For example, a value of *.jpg specifies that all objects in the JPG format are listed.

For more information, see Options --include and --exclude section of this topic.

--exclude

Specifies that objects that do not meet the specified conditions are listed. For example, a value of *.txt specifies that all objects that are not in the TXT format are listed.

For more information, see the Options --include and --exclude section of this topic.

-r, --recursive

Specifies recursive operations. If you configure this option, the operation is performed on all condition-matched objects in a bucket. If you do not configure this option, the operation is performed only on the object specified in the URL.

--addr

Specifies the address of the network whose connectivity you want to check. ossutil runs the ping command to check the network connectivity between your local computer and the specified address.

Default value: www.aliyun.com.

--kms-masterkey-id

Specifies the customer master key (CMK) ID used for encryption in KMS.

--version-id

The version ID of the object.

--version-id-marker

Specifies the position from which the list operation starts. Object versions whose IDs are alphabetically after the value of marker are listed. You can configure this option only after versioning is enabled for the bucket.

-m, --multipart

Specifies that the operation is performed on the incomplete multipart upload tasks in a bucket.

-d, --directory

Specifies that only objects and subdirectories in the current directory are returned.

--payer

Specifies the payer of the request. If you set this option to requester, the pay-by-requester mode is enabled.

--maxupspeed

Specifies the maximum upload speed. Default value: 0 (unlimited). Unit: KB/s.

--maxdownspeed

Specifies the maximum download speed. Default value: 0 (unlimited). Unit: KB/s.

--retry-times

Specifies the number of retries after an error occurs when the command is run. Default value: 10. Valid values: 1 to 500.

--download

Specifies that ossutil checks the network connectivity between your local computer and a bucket by using the URL of an object to download the object from the bucket.

-j, --jobs

Specifies the number of concurrent tasks performed across multiple objects. Valid values: 1 to 10000. Default value: 3.

-a, --all-type

Specifies that the operation is performed on the objects and incomplete multipart upload tasks in a bucket.

--disable-empty-referer

Specifies that the Referer field cannot be empty.

--method

Specifies the HTTP request method. Valid values: PUT, GET, and DELETE.

--output-dir

Specifies the directory in which the output objects are located. Output objects include the report objects that are generated due to errors that occur when you run the cp command to copy multiple objects at the same time.

By default, the directory for output objects is ossutil_output in the current directory.

--meta

Specifies the metadata of an object in the [header:value#header:value...] format. Example: Cache-Control:no-cache#Content-Encoding:gzip.

--object

Specifies an object name in the probe command.

--end-time

Specifies the timestamp in Linux or UNIX. If you configure this option, objects whose last modified time is later than the timestamp are ignored.

--limited-num

Specifies the maximum number of returned results.

-L, --language

Specifies the language that ossutil uses. Default value: CH. Valid values:

  • CH: Chinese. If you want to set this option to CH, make sure that your system supports UTF-8 encoding.

  • EN: English.

--delete

Deletes buckets, objects, or parts.

-b, --bucket

Specifies that the command is run to delete a bucket. This option applies only when you delete a bucket.

--disable-crc64

Disables CRC-64 in data transmission. By default, CRC-64 is enabled when you use ossutil to transfer data.

--upload

Checks the network connectivity between your local computer and the bucket by uploading a local file to the bucket.

--part-size

Specifies the part size in bytes. By default, ossutil calculates an appropriate part size based on the object size. You can configure this option to optimize performance or meet special requirements. Valid values: 1 to 9223372036854775807.

--timeout

Specifies a timeout period for a signed URL. Valid values: 0 to 9223372036854775807. Default value: 60. Unit: seconds.

--checkpoint-dir

Specifies the directory in which the log information of resumable upload tasks is stored. If a resumable upload task fails, ossutil automatically creates a directory named .ossutil_checkpoint and saves the checkpoint information in the directory. After the resumable upload task is successful, ossutil deletes the directory. If you want to configure this option, make sure that you have the required permissions to delete the specified directory.

--url

Specifies the URL of an object.

--marker

Specifies the position from which the list operation starts. Buckets, objects, and parts whose names are alphabetically after the value of marker are listed.

-f, --force

Specifies the operation to forcefully perform. The operation is performed without a prompt for confirmation.

--snapshot-path

Specifies the directory in which the snapshots of uploaded objects and downloaded objects are stored. If you configure this option, ossutil reads the snapshot information from the specified directory and performs an incremental upload or download when objects are uploaded or downloaded.

  • The --snapshot-path option is used to accelerate the incremental upload or download of multiple objects. This option cannot be used to copy objects. This option can be used when a large number of objects are uploaded and no other users modify the objects in OSS between the two uploads.

  • The --snapshot-path option records the last modified time of uploaded or downloaded objects in your local computer. Then, the recorded time is used to determine which objects can be skipped next time the objects are uploaded or downloaded. Therefore, when you use this option, make sure that the involved objects in OSS are not modified between the two uploads or downloads. In other scenarios in which objects are updated in OSS between the two uploads or downloads, use the --update option to perform incremental upload or to download multiple objects at the same time.

  • ossutil does not automatically delete snapshot information from the directory specified by snapshot-path. You can delete snapshot information that you no longer use.

  • Additional overheads are required to read and write snapshot information. We recommend that you do not use this option in scenarios in which the number of objects to upload or download is small, network conditions are good, or other users need to perform operations on the objects. In these scenarios, you can use the --update option instead to perform an incremental upload or download.

  • You can configure the --update and --snapshot-path parameters at the same time in a command. ossutil determines whether to skip an object in an upload task or a download task based on the snapshots stored in the directory specified by the --snapshot-path parameter. If no snapshots are generated for the object, ossutil determines whether to skip the object based on the --update parameter.

--start-time

Specifies the timestamp in Linux or UNIX. If you configure this option, objects whose last modified time is earlier than the timestamp are ignored.

--storage-class

Specifies the storage class of an object. Valid values:

  • Standard (default): This storage class is suitable for objects that are frequently accessed.

  • IA: This storage class is suitable for data that is infrequently accessed, such as data accessed once or twice a month. Infrequent Access (IA) objects have a minimum storage period of 30 days and a minimum billable size of 64 KB. You can access IA objects in real time. You are charged for data retrieval fees when you access IA objects.

  • Archive: This storage class is suitable for data that needs to be stored for a long period of time. Archive objects have a minimum storage period of 60 days and a minimum billable size of 64 KB. You must restore an Archive object before you can access the object. The restoration takes approximately 1 minute. You are charged data retrieval fees when you restore Archive objects.

  • ColdArchive: This storage class is suitable for long-term storage of data that is barely accessed. Archive objects have a minimum storage period of 180 days and a minimum billable size of 64 KB. You must restore a Cold Archive object before you can access the object. The amount of time required to restore a Cold Archive object varies based on the object size and the restoration mode. You are charged data retrieval fees when you restore Cold Archive objects.

-t, --sts-token

Specifies the STS token that is used to access OSS. This option is required only when you use STS to allow temporary access to OSS. The value of this option overwrites the configurations in the configuration file. For more information about how to generate an STS token, see Authorized third-party upload.

--parallel

Specifies the number of concurrent operations performed on a single object. Valid values: 1 to 10000. ossutil automatically sets a value for this option based on the operation type and object size.

--partition-download

Specifies the partition that you want to download. The value of this option is in the partition number:the total number of partitions format. A value of 1:5 specifies that the object is split into 5 partitions and partition 1 is downloaded. Partitions are numbered starting from 1. Partitioning rules for objects are determined by ossutil. This option splits an object into multiple partitions that can be concurrently downloaded by multiple ossutil commands. Each ossutil command downloads the corresponding partition.

--bucketname

The name of the bucket.

--encoding-type

Specifies the encoding type that is used to encode the key that follows oss://bucket_name. Valid value: url. If you do not configure this option, the key is not encoded.

--origin

Specifies the value of the Origin header in an HTTP request. The value of this option specifies the source domain from which a cross-origin request is sent.

--acr-method

Specifies the value of the Access-Control-Request-Method header in an HTTP request. Valid values: GET, PUT, POST, DELETE, and HEAD.

--acr-headers

Specifies the value of the Access-Control-Request-Headers header in an HTTP request. The value of this option specifies the headers that you need to add to the request. The headers do not include common request headers. To specify multiple headers, separate the headers with commas (,) and enclose the headers with double quotation marks (" "). Example: --acr-headers "header1,header2,header3".

--upload-id-marker

Specifies the position from which the list operation starts. Parts whose upload IDs are alphabetically after the value of marker are listed.

-h, --help

Displays help information for a specified command.

--trafic-limit

Specifies the access speed over HTTP in sign commands. Unit: bit/s.

Default value: 0. A value of 0 specifies that the access speed is unlimited.

Valid values: 819200 to 838860800 (100 KB/s to 100 MB/s).

--local-host

Specifies the local IP address of ossutil in the cp command. After you configure this option, ossutil accesses OSS by using the specified IP address.

--enable-symlink-dir

Specifies that the subdirectory to which the symbolic link points is uploaded. By default, subdirectories are not uploaded. The probe command can be used to check whether an object or a directory to which the symbolic link points is also a symbolic link.

--only-current-dir

Specifies that only objects in the current directory are uploaded, downloaded, or copied. Subdirectories and objects in the subdirectories in the current directory are ignored.

--disable-dir-object

Specifies that no OSS object is generated for the directory to upload, but the directory is maintained in the directory structure in the OSS console. If you delete all objects in the directory, the directory is also deleted.

--probe-item

Specifies the items to be checked by using the probe command. Valid values:

  • upload-speed: ossutil checks the upload bandwidth.

  • download-speed: ossutil checks the download bandwidth.

  • cycle-symlink: ossutil checks whether a symbolic link in the local file directory points to itself.

--redundancy-type

Specifies the redundancy type of a bucket. Valid values:

  • LRS (default): If you set the redundancy type of a bucket to locally redundant storage (LRS), OSS stores the copies of each object across different devices within the same zone. This way, OSS ensures data reliability and availability even if two storage devices are damaged at the same time.

  • ZRS: ZRS stores multiple copies of your data across multiple zones in the same region. Your data is still accessible even if a zone becomes unavailable.

--disable-encode-slash

Specifies that forward slashes (/) in a URL are not encoded.

--disable-all-symlink

Specifies that all objects in the subdirectory to which the symbolic link points and the subdirectory to which the symbolic link points are ignored during object upload.

--tagging

Specifies the object tag when you upload or copy an object. Example: "abc=1&bcd=2&……".

--disable-ignore-error

Specifies that errors are not ignored during batch operations.

--block-size

Specifies the unit of the obtained total size of objects within the specified bucket or directory. Valid values: KB, MB, GB, and TB. If you do not configure this option, the total size of obtained objects is measured in bytes by default.

Important

This option is available for ossutil version 1.7.3 and later.

Options --include and --exclude

Left-to-right application of conditions

A rule can contain multiple conditions specified by --include and --exclude. After these conditions are configured, ossutil evaluates the conditions from left to right to obtain the final results. If the test.txt object exists in a directory for which the operation takes effect, whether the object is one of the final matches varies based on rule configurations.

  • Rule 1: --include "*test*" --exclude "*.txt". ossutil first evaluates the --include "*test*" condition and includes test.txt in the results because it is a match for the condition. Then, ossutil evaluates the --exclude "*.txt" condition and excludes the test.txt object from the results because the object name contains ".txt" and is therefore a match for the condition. The test.txt object is excluded from the final results.

  • Rule 2: --exclude "*.txt" --include "*test*". ossutil first evaluates the --exclude "*.txt" condition and excludes the test.txt object from the results because the object is a miss for the condition. Then, ossutil evaluates --include "*test*", finds that test.txt is a match for the condition because the object name contains "test", and includes the object in the results. The test.txt object is included in the final results.

  • Rule 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" . ossutil first evaluates --include "*test*", finds that the test.txt object is a match, and includes the object in the results. Then, ossutil evaluates --exclude "*.txt", finds that the test.txt object is a match because the object name contains "test", and excludes the object from the results. Finally, ossutil evaluates --include "te?t.txt", finds that test.txt is a match, and includes the object in the results. The test.txt object is included in the final results.

Usage notes

  • Asterisk (*): matches any number of characters. For example, *.txt matches all TXT files.

  • Question mark (?): matches a single character. For example, abc?.jpg matches all JPG objects whose names are "abc" followed by a single character, as in abc1.jpg.

  • [sequence]: matches characters in a sequence. For example, abc[1-5].jpg match JPG objects whose names are "abc" followed by a number in sequence [1-5]. The objects include abc1.jpg, abc2.jpg, abc3.jpg, abc4.jpg, and abc5.jpg.

  • [!sequence]: matches characters outside a sequence. For example, abc[!0-7].jpg matches objects other than abc0.jpg, abc1.jpg, abc2.jpg, abc3.jpg, abc4.jpg, and abc5.jpg, abc6.jpg, and abc7.jpg.

Limits

A directory cannot be specified in the --include or --exclude option. For example, ./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --include dir/ triggers the --include or --exclude does not support format containing dir info error.