All Products
Search

This Product

    Object Storage Service:probe

    Document Center

    Object Storage Service:probe

    Last Updated:Jun 08, 2026

    The probe command detects network connectivity issues between your local client and OSS, measures upload and download bandwidth, and checks the status of local symbolic links.

    Usage notes

    Upload bandwidth checks require the oss:GetObject, oss:PutObject, and oss:DeleteObject permissions. Download bandwidth checks require the oss:GetObject permission. For more information, see Grant a custom policy.

    Overview

    The probe command detects network issues between your local client and OSS, measures upload and download bandwidth, and checks symbolic link status before upload.

    • Detect network exceptions

      ossutil tests the network by uploading or downloading objects. Specify object names to keep the transferred objects at the specified path. Without object names, ossutil creates temporary objects for detection and deletes them afterward.

    • Check upload and download bandwidths

      ossutil recommends a concurrency level based on your CPU cores and network bandwidth to maximize throughput.

    • Check the status of local symbolic links

      Uploading is interrupted if a symbolic link is abnormal. Check symbolic link status before uploading and fix any issues first.

    After running the probe command, you can view the detection procedure and results.

    • Detect network exceptions by uploading or downloading objects

      • √ indicates success. × indicates failure.

      • On success, ossutil returns the object size, time consumed, and the upload or download path.

      • On failure, ossutil returns error causes or error codes for troubleshooting.

        Error codes are listed in Overview.

      • After detection, ossutil creates a log file named logOssProbe+DetectionCompletionTime.log in the installation directory with detailed probe results.

    • Check a specific item

      When checking bandwidth or symbolic link status, ossutil returns results and recommendations.

    Check network connectivity by uploading an object

    ossutil checks network connectivity between your local client and a bucket by uploading an object.

    • Command syntax

      ossutil probe {--upload [file_name]} {--bucket bucket_name} [--object object_name] [--addr domain_name] [--upmode]

      The following table describes the parameters in the preceding command.

      Parameter

      Type

      Required

      Description

      --upload

      /

      Yes

      Performs network detection by uploading an object.

      file_name

      string

      No

      Full path of the local file to upload. If not specified, ossutil generates and uploads a temporary file.

      --bucket

      string

      No

      The name of the bucket.

      --object

      string

      No

      Object name for the upload. If specified, the object is stored in the bucket under this name. If not specified, ossutil deletes the uploaded object after detection.

      --addr

      string

      No

      Network address to ping for connectivity checks.

      Default value: www.aliyun.com.

      --upmode

      string

      No

      The method used to upload the object.

      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.

    • Sample commands

      • Check the network by uploading a random object and specifying the network address

        Upload a random object to examplebucket and ping aliyun.com:

        ossutil probe --upload --bucket examplebucket --addr aliyun.com

        Sample output:

        begin parse parameters and prepare file...[√]
begin network detection...[√]
begin upload file(normal)...[√]

*************************  upload result  *************************
upload file:success
upload file size:143360(byte)
upload time consuming:456(ms)
(only the time consumed by probe command)

upload object is oss-test-probe-1716280906324488100-quky8a902r

************************* report log info*************************
report log file:E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\logOssProbe20240521164146.log

      • Upload example.txt from D:\localpath to examplebucket using simple upload

        The uploaded object is deleted after detection. Sample command:

        ossutil probe --upload D:\localpath\example.txt --bucket examplebucket

        Sample output:

        begin parse parameters and prepare file...[√]
begin network detection...[√]
begin upload file(normal)...[√]

*************************  upload result  *************************
upload file:success
upload file size:9(byte)
upload time consuming:366(ms)
(only the time consumed by probe command)

upload object is oss-test-probe-1716281191298397500-hi8237d15e

************************* report log info*************************
report log file:E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\logOssProbe20240521164631.log

    Check network connectivity by downloading from an object URL

    ossutil checks network connectivity between your local client and a bucket by downloading an object from its URL.

    • Command syntax

      ossutil probe {--download} {--url http_url} [--addr=domain_name] [file_name]

      The following table describes the parameters in the preceding command.

      Parameter

      Type

      Required

      Description

      --download

      /

      Yes

      Performs network detection by downloading an object.

      --url

      string

      Yes

      The URL of the object to download.

      • If the object ACL is public-read, use the object URL. Example: https://examplebucket.oss-cn-beijing.aliyuncs.com/example.jpg.

      • If the object ACL is private, use a signed URL enclosed in double quotation marks (""). Example: "https://examplebucket.oss-cn-beijing.aliyuncs.com/example.jpg?Expires=1552015472&OSSAccessKeyId=TMP.******5r9f1FV12y8_Qis6LUVmvoSCUSs7aboCCHtydQ0axN32Sn-UvyY3AAAwLAIUarYNLcO87AKMEcE5O3A******oCFAQuRdZYyVFyqOW8QkGAN-bamUiQ&Signature=bIa4llbMbldrl7rwckr%2FXXvTtxw%3D".

      --addr

      string

      No

      Network address to ping for connectivity checks.

      Default value: www.aliyun.com.

      file_name

      string

      No

      The local path to which the object is downloaded.

      • If you specify only the object name but do not specify a directory, the object is stored by using the specified name in the installation directory of ossutil.

      • If you specify only a directory but do not specify the object name, the object is stored by using its original name in the specified directory.

      • If you do not specify this parameter, the object is stored by using its original name in the installation directory of ossutil.

    • Sample commands

      • Download a public-read object and save it with a new name

        Download example.txt from https://examplebucket.oss-cn-beijing.aliyuncs.com/example.txt and save it as /localfile/test.txt:

        ossutil probe --download --url https://examplebucket.oss-cn-beijing.aliyuncs.com/example.txt  /localfile/test.txt

        Sample output:

        begin parse parameters and prepare object...[√]
begin network detection...[√]
begin download file...[√]

*************************  download result  *************************
download file:success
download file size:9(byte)
download time consuming:278(ms)
(only the time consumed by probe command)

download file is E:\localfile\test.txt

************************* report log info*************************
report log file:E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\logOssProbe20240521173050.log

      • Download a public-read object and specify a ping address

        Download example.txt from https://examplebucket.oss-cn-beijing.aliyuncs.com/example.txt and ping aliyun.com:

        ossutil probe --download --url https://examplebucket.oss-cn-beijing.aliyuncs.com/example.txt --addr aliyun.com

        Sample output:

        begin parse parameters and prepare object...[√]
begin network detection...[√]
begin download file...[√]

*************************  download result  *************************
download file:success
download file size:9(byte)
download time consuming:316(ms)
(only the time consumed by probe command)

download file is E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\example.txt

************************* report log info*************************
report log file:E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\logOssProbe20240521173448.log

    Check network connectivity by downloading from a bucket

    ossutil checks network connectivity between your local client and a bucket by downloading an object from the bucket.

    • Command syntax

      ossutil probe {--download} {--bucket bucket_name} [--object object_name] [--addr domain_name] [file_name]

      The following table describes the parameters in the preceding command.

      Parameter

      Type

      Required

      Description

      --download

      /

      Yes

      Performs network detection by downloading an object.

      --bucket

      string

      Yes

      The name of the bucket.

      --object

      string

      No

      Object name to download. If specified, ossutil downloads this object. If not specified, ossutil creates a temporary object, uploads it to the bucket, downloads it, and then deletes it after detection.

      --addr

      string

      No

      Network address to ping for connectivity checks.

      Default value: www.aliyun.com.

      file_name

      string

      No

      The local path to download the object to.

      • If you specify only the object name but do not specify a directory, the object is stored by using the specified name in the installation directory of ossutil.

      • If you specify only a directory but do not specify the object name, the object is stored by using its original name in the specified directory.

      • If you do not specify this parameter, the object is stored by using its original name in the installation directory of ossutil.

    • Sample commands

      • Download an object and save it with a new name

        Download ossfolder/example.txt from examplebucket and save it as /localfolder/text.txt: 

        ossutil probe --download --bucket examplebucket --object ossfolder/example.txt /localfolder/text.txt

        Sample output:

        begin parse parameters and prepare object...[√]
begin network detection...[√]
begin download file...[√]

*************************  download result  *************************
download file:success
download file size:9(byte)
download time consuming:416(ms)
(only the time consumed by probe command)

download file is E:\localfolder\text.txt

************************* report log info*************************
report log file:E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\logOssProbe20240521180217.log

      • Download a temporary object and specify a ping address

        Download a temporary object from examplebucket and ping aliyun.com:

        ossutil probe --download --bucket examplebucket --addr aliyun.com

        Sample output:

        begin parse parameters and prepare object...[√]
begin network detection...[√]
begin download file...[√]

*************************  download result  *************************
download file:success
download file size:143360(byte)
download time consuming:865(ms)
(only the time consumed by probe command)

download file is E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\oss-test-probe-1716286063484973300-rrmrfgtv8w

************************* report log info*************************
report log file:E:\00-OSS\01-ossutil\05-v2\ossutil-2.0.0-beta.24041600-windows-amd64\logOssProbe20240521180533.log

    Check a specific item

    Run the probe command to check symbolic link status, upload bandwidth, or download bandwidth. ossutil returns the names of abnormal symbolic links and a recommended concurrency level based on the results.

    • Command syntax

      ossutil probe {--probe-item item_value} {--bucket bucket-name} [--object object_name][--parallel <value>][--part-size <value>][--runtime <value>]

      The following table describes the parameters in the preceding command.

      Parameter

      Type

      Required

      Description

      --probe-item

      string

      Yes

      The item to check.

      Valid values:

      • cycle-symlink: checks for abnormal symbolic links in the local path.

      • upload-speed: checks the upload bandwidth.

      • download-speed: checks the download bandwidth.

      • download-time: checks the time required to download an object.

      --bucket

      string

      Yes when the value of --probe-item is not cycle-symlink

      The name of the bucket.

      --object

      string

      Yes when --probe-item is set to download-speed

      Path of the object. The object must exist and should be larger than 5 MB. Example: ossfolder/example.txt.

      --parallel

      int

      No

      Number of concurrent tasks for a single object. Default value: 1.

      Note

      This parameter takes effect only when --probe-item is set to download-time.

      --part-size

      int

      No

      Part size in bytes. By default, ossutil determines the part size based on the object size.

      Valid values: 1 to 9223372036854775807.

      Note

      This parameter takes effect only when --probe-item is set to download-time.

      --runtime

      int

      No

      Maximum execution time. The command stops when this time is reached.

      Note

      This parameter takes effect only when --probe-item is set to upload-speed or download-speed.

    • Sample commands

      • Check for abnormal symbolic links in the localfolder directory:

        Sample command:

        ossutil probe --probe-item cycle-symlink  D:\localfolder

        Sample output:

         success

0.009583(s) elapsed

        The output indicates no abnormal symbolic links exist.

      • Check the upload bandwidth

        Upload a temporary object to examplebucket and get a recommended concurrency level:

        Sample command:

        ossutil probe --probe-item upload-speed --bucket examplebucket

        Sample output:

        cpu core count:8
parallel:8,average speed:1956.41(KB/s),current speed:2976.00(KB/s),max speed:2976.00(KB/s)
parallel:9,average speed:1903.45(KB/s),current speed:1216.00(KB/s),max speed:2720.00(KB/s)
parallel:10,average speed:1945.38(KB/s),current speed:1184.00(KB/s),max speed:3168.00(KB/s)
parallel:11,average speed:2102.07(KB/s),current speed:7840.00(KB/s),max speed:7840.00(KB/s)
parallel:12,average speed:1899.03(KB/s),current speed:1568.00(KB/s),max speed:3168.00(KB/s)
parallel:13,average speed:1934.34(KB/s),current speed:1760.00(KB/s),max speed:8544.00(KB/s)
parallel:14,average speed:1765.52(KB/s),current speed:1984.00(KB/s),max speed:2880.00(KB/s)
parallel:15,average speed:2284.14(KB/s),current speed:2016.00(KB/s),max speed:6688.00(KB/s)
parallel:16,average speed:2544.55(KB/s),current speed:4032.00(KB/s),max speed:9344.00(KB/s)

suggest parallel is 16, max average speed is 2544.55(KB/s)

        The output shows an 8-core CPU, a maximum average upload bandwidth of 2544.55 KB/s, and a recommended concurrency of 16.

      • Check the download bandwidth

        Download example.txt from examplebucket and get a recommended concurrency level:

        Sample command:

        ossutil probe --probe-item download-speed --bucket examplebucket --object example.txt

        Sample output:

        cpu core count:8
parallel:8,average speed:1.41(KB/s),current speed:1.69(KB/s),max speed:1.78(KB/s)
parallel:9,average speed:1.48(KB/s),current speed:1.02(KB/s),max speed:1.95(KB/s)
parallel:10,average speed:1.52(KB/s),current speed:1.60(KB/s),max speed:2.11(KB/s)
parallel:11,average speed:1.41(KB/s),current speed:2.17(KB/s),max speed:2.34(KB/s)
parallel:12,average speed:1.86(KB/s),current speed:1.71(KB/s),max speed:2.47(KB/s)
parallel:13,average speed:1.90(KB/s),current speed:0.58(KB/s),max speed:2.65(KB/s)
parallel:14,average speed:1.17(KB/s),current speed:0.99(KB/s),max speed:2.29(KB/s)
parallel:15,average speed:1.86(KB/s),current speed:1.42(KB/s),max speed:2.84(KB/s)
parallel:16,average speed:1.93(KB/s),current speed:0.76(KB/s),max speed:2.56(KB/s)

suggest parallel is 16, max average speed is 1.93(KB/s)

        The output shows an 8-core CPU, a maximum average download bandwidth of 1.93 KB/s, and a recommended concurrency of 16.

      • Check the download bandwidth with a maximum execution time

        Download example.zip from examplebucket with a 2-second time limit: 

        ossutil probe --probe-item download-speed --bucket examplebucket --object  example.zip --runtime 2

        Sample output:

        cpu core count:8
parallel:8,average speed:937.76(KB/s),current speed:952.00(KB/s),max speed:1044.00(KB/s)))
parallel:9,average speed:935.59(KB/s),current speed:936.00(KB/s),max speed:1016.00(KB/s))
parallel:10,average speed:924.45(KB/s),current speed:940.00(KB/s),max speed:968.00(KB/s)
parallel:11,average speed:930.48(KB/s),current speed:828.00(KB/s),max speed:1104.00(KB/s))
parallel:12,average speed:908.21(KB/s),current speed:920.00(KB/s),max speed:1000.00(KB/s))
parallel:13,average speed:923.86(KB/s),current speed:992.00(KB/s),max speed:992.00(KB/s)
parallel:14,average speed:794.14(KB/s),current speed:776.00(KB/s),max speed:948.00(KB/s)
parallel:15,average speed:835.28(KB/s),current speed:936.00(KB/s),max speed:960.00(KB/s)
parallel:16,average speed:935.62(KB/s),current speed:932.00(KB/s),max speed:984.00(KB/s)

suggest parallel is 8, max average speed is 937.76(KB/s)

run download-speed  2 seconds with parallel 8
parallel:8,average speed:809.67(KB/s),current speed:651.08(KB/s),max speed:891.08(KB/s)
281.731035(s) elapsed

      • Check the download time

        Download example.txt from examplebucket and measure the time consumed: 

        ossutil probe --probe-item download-time --bucket examplebucket --object example.txt

        Sample output:

        download-speed part-size:-1, parallel:1 total bytes:9, cost:0.057 s, avg speed:NaN(kB/s)

0.539351(s) elapsed

      • Check the download time with a custom part size

        Download example.zip from examplebucket with a 10 MB part size: 

        ossutil probe --probe-item download-time --bucket examplebucket --object example.zip --part-size 10000000

        Sample output:

        downloading average speed:904.75(KB/s),current speed:1777.62(KB/s),max speed:1868.00(KB/s)
download-speed part-size:10000000, parallel:1 total bytes:11881599, cost:12.831 s, avg speed:966.92(kB/s)

13.188139(s) elapsed

      • Check the download time with a custom concurrency level

        Download example.zip from examplebucket with 3 concurrent tasks: 

        ossutil probe --probe-item download-time --bucket examplebucket --object example.zip --parallel 3

        Sample output:

        downloading average speed:910.58(KB/s),current speed:1740.00(KB/s),max speed:1876.00(KB/s)
download-speed part-size:-1, parallel:3 total bytes:11881599, cost:12.728 s, avg speed:966.92(kB/s)

12.984432(s) elapsed