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

Command syntax

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

Common options

The following table describes some 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. ossutil reads the configuration file after this command-line tool is enabled. When you manage buckets that belong to different Alibaba Cloud accounts, you can generate multiple configuration files, and specify one of these 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 corresponding configuration file.
-e, --endpoint Specifies the endpoints of buckets. When you manage buckets across regions, you can use this option to specify the corresponding endpoints of the buckets. For more information about endpoints of different regions, see Regions and endpoints.
-i, --access-key-id Specifies the AccessKey ID 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 corresponding AccessKey IDs.
-k, --access-key-secret Specifies the AccessKey secret used to access OSS. When you manage buckets that belong to different Alibaba Cloud accounts, you can use this option to specify the corresponding AccessKey secrets.
-p, --password Specifies the AccessKey secret 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 configured by using other methods.
--loglevel Generates the ossutil.log file in the current working directory. The default value is null, which indicates that no log files are generated.
Valid values:
  • info: ossutil displays operations logs.
    ./ossutil [command] --loglevel=info
  • debug: ossutil displays logs that contain HTTP requests and responses and original signature strings to locate problems.
    ./ossutil [command] --loglevel=debug
--proxy-host, --proxy-user, and --proxy-pwd If your environment requires a proxy server to access websites, you must use these three options to specify the information of the proxy server.
  • --proxy-host: indicates the URL of the proxy server. This option supports HTTP, HTTPS, and SOCKS5.
  • --proxy-user: indicates the username of the proxy server. The default value is null.
  • --proxy-pwd: indicates the password of the proxy server. The default value is null.
After you specify the information of the proxy server by using these three options, ossutil uses the specified information and the proxy server to access OSS.
./ossutil ls oss://bucket1 --proxy-host http://47.88.**.**:3128 --proxy-user test --proxy-pwd test
--mode Specifies the type of your access credential. Valid values:
  • AK: The AccessKey ID and AccessKey secret are used for authentication.
  • StsToken: An 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 ECS instance is used to implement password-free authentication.

If you do not specify 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 temporary access credential token specified in the AssumeRole parameter in RamRoleArn mode for authentication. Unit: seconds. Default value: 3600.
--ram-role-arn Specifies the Aliyun resource names (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. Unit: seconds. Default value: 1200.
--connect-timeout Specifies the timeout period for the client to connect to the server. Unit: seconds. Default value: 120.
--sts-region Specifies the region where STS is connected. Format: cn-hangzhou. For more information about the regions supported by STS, see Endpoints.

If you do not specify 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.

Other options

The following table describes other options included in ossutil commands other than the preceding common options.
Option Description
-s, --short-format Lists items in the short format. The long format is displayed if this option is not specified.
--bigfile-threshold Specifies the size threshold for which a large object starts resumable data transfer. Unit: bytes. Valid values: 0 to 9223372036854775807. Default value: 104857600 (100 MB).
--acl Sets the access control list (ACL) for the object.
--range Specifies the byte range of the object to download. Bytes are numbered from 0.
  • You can specify a range. For example, 3-9 indicates a range from byte 3 to byte 9, which includes byte 3 and byte 9.
  • You can specify the field from which the download starts. For example, 3- indicates a range from byte 3 to the end of the object, which includes byte 3.
  • You can specify the field at which the download ends. For example, -9 indicates a range from byte 0 to byte 9, which includes byte 9.
--all-versions Specifies all versions of an object.
--type Specifies the algorithm that is used for calculation. Default value: crc64. Valid values:
  • crc64
  • md5: specifies the MD5 verification.
-v, --version Displays the ossutil version and exits.
-u, --update Specifies an update operation.
--origin Specifies the value of the Origin field in an HTTP request header.
--upmode probe: specifies the upload method in the command. Default value: normal. Valid values:
  • normal: 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 indicates that all objects in the JPG format are listed.
--exclude Specifies that objects that do not meet the specified conditions are listed. For example, a value of *.txt indicates that all objects that are not in the TXT format are listed.
-r, --recursive Specifies recursive operations. If this option is specified, commands that support this option are run to perform operations on all objects in a bucket that meet the specified conditions. If this option is not specified, commands that support this option are run to perform operations only on the object specified in the URL.
--addr Specifies the address of the network that you want to check. ossutil runs the ping command to check the network connectivity between the local client 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 Specifies the version ID of the object.
--version-id-marke Specifies the position from which the list operation starts. Object versions whose IDs are alphabetically after the value of marker are listed. You can specify this parameter only when versioning is enabled for the bucket.
-m, --multipart Specifies the command to delete incomplete multipart upload tasks of objects in the 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. Unit: KB/s. Default value: 0 (unlimited).
--retry-times Specifies the number of retries after the command fails to be run. Default value: 10. Valid value: 1 to 500.
--download Specifies that ossutil checks the network between the local client 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 operations are to be performed on both 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, which can be PUT, GET, or DELETE.
--output-dir Specifies the directory in which the output objects are located. Output objects include report objects generated due to errors that occur when you run the cp command to copy multiple objects.

Default value: the ossutil_output directory 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 the object name in the probe command
--end-time Specifies the timestamp in Linux or UNIX. If you specify this option, objects whose last update 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: If you plan to set this option to CH, make sure that your system supports UTF-8 encoding.
  • EN
--delete Specifies operations to delete buckets, objects, or parts.
-b, --bucket Specifies the operations performed only when you delete buckets.
--disable-crc64 Disables CRC-64 in data transmission. By default, CRC-64 is enabled when you use ossutil to transfer data.
--upload Specifies that the connection between the local client and the destination bucket is checked by uploading a local file to the destination bucket.
--part-size Specifies the part size in bytes. By default, ossutil calculates the appropriate part size based on the object size. You can set this option to optimize performance or meet special requirements. Valid values: 1 to 9223372036854775807.
--timeout Specifies the timeout period of a signed URL request. Unit: seconds. Valid values: 0 to 9223372036854775807. Default value: 60.
--checkpoint-dir Specifies the directory in which the log information of resumable upload or download tasks is stored. When a resumable upload or download task fails, ossutil automatically creates the ossutil_checkpoint directory and records the checkpoint information in the directory. After the resumable upload or download task is completed, ossutil deletes this directory. If this option is specified, make sure that you have permissions to delete the specified directory.
--url Specifies the URL of the file.
--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 command to forcibly run without prompting the user for confirmation.
--snapshot-path Specifies the directory in which the snapshots of uploaded objects and downloaded objects are stored. Next time the objects are uploaded or downloaded while this option is specified, ossutil reads the snapshot information from the specified directory and performs an incremental upload or download.
  • 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 the number of objects is large and no other users modify the corresponding objects in OSS between the two uploads.
  • The --snapshot-path option records the local lastModifiedTime of uploaded or downloaded objects, and then compares that recorded lastModifiedTime with that of objects to be uploaded or downloaded next time to determine which objects can be skipped. Therefore, when you use this option, make sure that the corresponding objects in OSS are not modified between the two uploads or downloads. In other scenarios where objects are updated in OSS between the two uploads or downloads, use the --update option to perform incremental upload or download on objects.
  • ossutil does not automatically delete snapshot information from the directory specified by snapshot-path. You can remove the directory if you no longer use the snapshot information.
  • Additional overheads are required to read and write snapshot information. We recommend that you do not use this option in the following scenarios: The number of objects to upload or download is small. The network is properly connected. Other users need to perform operations on those objects. In this case, you can use the --update option to perform incremental upload or download.
  • You can specify both the --update and --snapshot-path parameters at the same time in a command. ossutil determines whether to skip an object in uploads or downloads first based on the snapshots stored in the directory specified by --snapshot-path. If no snapshots are generated for the object, ossutil determines whether to skip the object based on the --update option.
--start-time Specifies the timestamp in Linux or UNIX. If you specify this option, objects whose last update time is earlier than the timestamp are ignored.
--storage-class Specifies the storage class of an object. Default value: Standard. Valid values:
  • Standard: This storage class can handle frequent data access.
  • IA: This storage class is suitable for long-term storage of data that is infrequently accessed (once or twice each month). Objects of the IA storage class have a minimum storage period of 30 days and a minimum billable size of 64 KB. You can access objects of the IA storage class in real time. You are charged for data retrieval fees when you access IA objects.
  • Archive: This storage class applies to scenarios that store data for a long period of time. Objects of the Archive storage class 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 it. The restoration takes about a minute, and you are charged for data retrieval fees.
  • ColdArchive: This storage class is suitable for long-term storage of data that is barely accessed. Objects of the Cold Archive storage class have a minimum storage period of 180 days and a minimum billable size of 64 KB. You must restore an object of the Cold Archive storage class before you can access it. The time required to restore a Cold Archive object depends on the object size and the restore mode. You are charged for data retrieval fees when you restore Cold Archive objects.
-t, --sts-token Specifies the STS token used to access OSS. This option is required only when you use a temporary STS token to access OSS. This option value overwrites the corresponding configurations in the configuration file. For more information about how to generate an STS token, see Temporary access credential.
--parallel Specifies the number of concurrent operations performed on a single object. Valid values: 1 to 10000. By default, ossutil automatically sets the value of this option based on the operation type and object size.
--partition-download Specifies the partition to download. The value of this option is in the partition number: the total number of partitions format. This option splits an object to download into multiple partitions that can be downloaded by multiple ossutil commands. Each ossutil command downloads its own partition. You can run multiple ossutil commands on different machines at the same time. A value of 1:5 indicates that ossutil downloads partition 1 out of the five partitions. Partitions are numbered 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 its own partition.
--bucketname Specifies the name of the bucket.
--encoding-type Specifies the encoding type used to encode the key that follows oss://bucket_name. Valid value: url. If this option is not specified in the command, the key is not encoded.
--origin Specifies the value of the Origin header in an HTTP request. This option value indicates the source domain of a cross-origin request.
--acr-method Specifies the value of the Access-Control-Request-Method request header. Valid values: GET, PUT, POST, DELETE, and HEAD.
--acr-headers Specifies the value of the Access-Control-Request-Headers request header. The value of this option does not include common request headers. To specify multiple headers, separate different 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 the sign command. Unit: bit/s.

Default value: 0. A value of 0 indicates 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 specify 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 these subdirectories in the current directory are ignored.
--disable-dir-object Specifies that no OSS object is generated for the directory during object upload, but you can still view the corresponding 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 the bucket. Default value: LRS. Valid values:
  • LRS: 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 when hardware failures occur.
  • ZRS: If you set the redundancy type of a bucket to zone-redundant storage (ZRS), OSS uses the multi-zone mechanism to distribute user data across three zones within the same region. This way, the data can be accessed even if one zone becomes unavailable due to failures such as power outages and fires.
--disable-encode-slash Specifies that forward slashes (/) in the 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 in the "abc=1&bcd=2&……" format.
--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. By default, if you do not specify this option in the command, the obtained total size of objects is measured in bytes.
Notice This option applies to ossutil 1.7.3 and later versions.