HUAWEI Tool Guide User Manual

Object Storage Service

Tool Guide (obsutil)

Issue	16
Date	2021-03-22

HUAWEI TECHNOLOGIES CO., LTD.

No part of this document may be reproduced or transmitted in any form or by any means without prior written consent of Huawei Technologies Co., Ltd.

Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.

All other trademarks and trade names mentioned in this document are the property of their respective holders.

Notice

The purchased products, services and features are stipulated by the contract made between Huawei and the customer. All or part of the products, services and features described in this document may not be within the purchase scope or the usage scope. Unless otherwise c fi in the contract, all statements, information, and recommendations in this document are provided "AS IS" without warranties, guarantees or representations of any kind, either express or implied.

The information in this document is subject to change without notice. Every ff has been made in the preparation of this document to ensure accuracy of the contents, but all statements, information, and recommendations in this document do not constitute a warranty of any kind, express or implied.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	Contents

Contents


1 Introduction to obsutil...........................................................................................................				1
2 Download and Installation....................................................................................................				4
3 Getting Started........................................................................................................................				6
3.1	Preparing the Environment..................................................................................................................................................			6
3.2	Performing Initial C nfig		n........................................................................................................................................	8
3.3	Quick Start.................................................................................................................................................................................			9
4 Bucket Commands................................................................................................................				12
4.1	Creating a Bucket..................................................................................................................................................................			12
4.2	Listing Buckets.......................................................................................................................................................................			14
4.3	Querying Bucket Properties...............................................................................................................................................			16
4.4	Setting Bucket Properties...................................................................................................................................................			18
4.5	Deleting a Bucket..................................................................................................................................................................			21
4.6	C nfig ng a Bucket Policy..............................................................................................................................................			22
4.7	Obtaining a Bucket Policy..................................................................................................................................................			23
4.8	Deleting a Bucket Policy.....................................................................................................................................................			24
5 Object Commands.................................................................................................................				26
5.1	Creating a Folder...................................................................................................................................................................			26
5.2	Uploading an Object............................................................................................................................................................			28
5.3	Querying Object Properties...............................................................................................................................................			40
5.4	Setting Object Properties...................................................................................................................................................			42
5.5	Listing Objects........................................................................................................................................................................			46
5.6	Copying an Object................................................................................................................................................................			49
5.7	Moving an Object.................................................................................................................................................................			59
5.8	Downloading an Object......................................................................................................................................................			68
5.9	Generating the Download Link of an Object..............................................................................................................			79
5.10		Deleting an Object.............................................................................................................................................................		83
5.11		Synchronously Uploading Incremental Objects.......................................................................................................		86
5.12		Synchronously Copying Incremental Objects............................................................................................................		94
5.13		Synchronously Downloading Incremental Objects...............................................................................................		104
5.14		Restoring Objects from OBS Archive.........................................................................................................................		112
5.15		Resuming a Failed Upload Task..................................................................................................................................		115
5.16		Resuming a Failed Copy Task......................................................................................................................................		123

Issue 16 (2021-03-22)			Copyright © Huawei Technologies Co., Ltd.	ii

Object Storage Service
Tool Guide (obsutil)				Contents
5.17 Resuming a Failed Download Task............................................................................................................................				132
5.18 Listing Multipart Upload Tasks...................................................................................................................................				139
5.19 Deleting a Multipart Upload Task..............................................................................................................................				141
5.20 Creating an Authorization Code for Directory Sharing.......................................................................................				144
5.21 Listing Objects by Using an Authorization Code..................................................................................................				146
5.22 Downloading Objects by Using an Authorization Code.....................................................................................				149
6 Auxiliary Commands..........................................................................................................				159
6.1	Updating a C nfig		n File.......................................................................................................................................	159
6.2	Deleting Part Records.......................................................................................................................................................			160
6.3	Viewing Command Help Information.........................................................................................................................			162
6.4	Querying the Version Number.......................................................................................................................................			164
6.5	Archiving Log Files.............................................................................................................................................................			164
6.6	Checking and Updating the Version............................................................................................................................			166
6.7	Listing Failure Result Files...............................................................................................................................................			167
7 Common Examples.............................................................................................................				169
7.1	Upload....................................................................................................................................................................................			169
7.2	Synchronous Upload..........................................................................................................................................................			171
7.3	Download..............................................................................................................................................................................			172
7.4	Synchronous Download....................................................................................................................................................			174
7.5	Copy........................................................................................................................................................................................			174
7.6	Synchronous Copy..............................................................................................................................................................			175
7.7	Listing.....................................................................................................................................................................................			176
7.8	Listing Multipart Upload Tasks......................................................................................................................................			177
7.9	Deleting All Multipart Upload Tasks in a Bucket....................................................................................................			177
8 Fault Locating......................................................................................................................				178
8.1	Overview................................................................................................................................................................................			178
8.2	Log Files.................................................................................................................................................................................			178
8.3	Result Lists............................................................................................................................................................................			179
8.4	Return Codes........................................................................................................................................................................			180
9 Best Practices.......................................................................................................................				182
9.1	Using the obsutil help Command to Search for Functions..................................................................................			182
9.2	C nfig	ng Scheduled Tasks Using the Crontab Command...............................................................................		183
9.3	Setting obsutil Commands as Built-in Commands.................................................................................................			184
9.4	C nfig	ng Auto Obtaining of Access Keys for obsutil........................................................................................		187
9.5	Fine-Tuning obsutil Performance..................................................................................................................................			188
9.6	Using obsutil for Resumable Data Transfer...............................................................................................................			189
9.7	Using obsutil to Upload a Symbolic Link...................................................................................................................			190
9.8	C nfig	ng an HTTP Proxy for obsutil.......................................................................................................................		190
9.9	Using obsutil to Share Directories................................................................................................................................			191
9.10 Using obsutil to Replicate Data Across Regions on the Client Side...............................................................				192
A Parameter Description.......................................................................................................				193

Issue 16 (2021-03-22)

iii

Object Storage Service
Tool Guide (obsutil)	Contents
B Change History....................................................................................................................	204

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	1 Introduction to obsutil

1Introduction to obsutil

obsutil is a command line tool for accessing and managing OBS on HUAWEI


CLOUD. You can use this tool to perform common c nfig		n on OBS, such as
creating buckets, uploading and downloading fi f		and deleting fi
f	If you are familiar with command line interface (CLI), obsutil is

recommended for batch processing and automated tasks.

obsutil is compatible with the Windows, Linux, and macOS operating systems (OSs). Table 1-1 lists the recommended OS versions. To obtain the obsutil download links and methods for ff n OSs, refer to Downloading obsutil.

Table 1-1 Recommended OS versions for using obsutil

OS	Recommended Version

Windows	●	Windows 7
	●	Windows 8
	●	Windows 10
	●	Windows Server 2016

Linux	●	SUSE 11
	●	EulerOS 2
	●	CentOS 7

macOS	macOS 10.13.4

Tool Advantages

obsutil features the following advantages:

1.Simple and easy to use

2.Lightweight and installation-free

3.Compatible with Windows, Linux, and macOS operating systems

v fi c nfig

n and excellent performance

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	1 Introduction to obsutil

Application Scenarios

●Automated backup and archiving, for example, periodically uploading local data to OBS.

●Scenarios that cannot be implemented using other tools such as OBS Browser +, for example, synchronously uploading, downloading, and copying objects.

Functions

Table 1-2 lists obsutil functions.

Table 1-2 obsutil functions

Function	Description

Basic operations on	Create buckets of		ff	n	storage classes in	c fic
buckets	regions, delete buckets, and obtain the bucket list and
	c nfig	n information.

Basic operations on	Manage objects, including uploading, downloading,
objects	deleting, and listing objects. Supported operations are
	detailed as follows:
	● Upload one or more fi				or folders.
	● Upload large fi		in multiple parts.
	● Synchronously upload, download, and copy
	incremental objects.
	● Copy a single object or copy multiple objects in
	batches by object name				fix
	● Move a single object or move objects in batches by
	object name		fix
	● Resume failed upload, download, or copy tasks.

Logging	Allows you to c nfig			logging on the client side to
	record operations on buckets and objects for statistics
	analysis later.

Advanced bucket and object management operations are being developed continuously, and will be available in later versions of obsutil. You can also go to OBS Console and explore more. For details, see OBS Console Operation Guide.

Command Line Structure

The obsutil command line structures are as follows:

●In Windows

obsutil command [parameters...] [options...]

●In Linux or macOS

./obsutil command [parameters...] [options...]

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	1 Introduction to obsutil

NOTE

●command indicates the command to be executed, for example, ls or cp.

●parameters indicates the basic parameters (mandatory) of the command, for example, bucket name when creating a bucket.

●options indicates the additional parameters (optional) of the command. Additional parameters must be preceded with a hyphen (-) when you run the command.

●The square brackets ([]) are not part of the command. Do not enclose parameter values with them when entering a command.

●If the command contains special characters including ampersands (&), angle brackets

(<) and (>), and spaces, they need to be escaped using quotation marks. Use single quotation marks for Linux or macOS and quotation marks for Windows.

●Additional parameters can be input in the -key=value or -key value format, for example,

-acl=private, or -acl private. There is no ff nc between the two formats. Select either one as you like.

●In Windows, you can directly execute obsutil.exe to enter an interactive command mode. In this mode, you can input command [parameters...] [options...] without obsutil to run a command. An example is provided as follows:

Enter "exit" or "quit" to logout

Enter "help" or "help command" to show help docs Input your command:

-->ls -limit=3 -s obs://bucket-001 obs://bucket-002 obs://bucket-003 Bucket number is: 3

Input your command: -->

●If you use SSH to remotely log in to the Linux or macOS for running obsutil commands, you are advised to set TMOUT=0 to prevent the program from exiting due to the expiration of the SSH session.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	2 Download and Installation

2Download and Installation

Download Links

Table 2-1 lists the download links of obsutil for			ff n operating systems.
Table 2-1 Download links of obsutil

Operatin	Download Link	How to Use		View Help
g System
Windows	obsutil_windows64	After the download		You can also
(64-bit)	obsutil_windows64_sha256	is complete, click		click here to
	obsutil_windows64_sha256	here to see how to		learn how


Linux	obsutil_linux_amd64	quickly get started		to use the
AMD	obsutil_linux_amd64_sha256	with obsutil.		help
(64-bit)	obsutil_linux_amd64_sha256			command
(64-bit)		Basic functions		command
		Basic functions		to get
Linux	obsutil_linux_arm64	●	Listing Buckets	to get
Linux	obsutil_linux_arm64	●	Listing Buckets	familiar
ARM		●	Uploading an	familiar
ARM	obsutil_linux_arm64_sha256	●	Uploading an	with more
(64-bit)			Object	functions of
macOS	obsutil_mac64	●	Listing Objects	obsutil.
(64-bit)	obsutil_mac64_sha256
	obsutil_mac64_sha256

NOTE

For details about the version revision records of obsutil, see ChangeLog.

Quick Installation

Methods of downloading obsutil vary according to ff n operating systems. obsutil is an installation-free tool and can be used after the package is downloaded and decompressed.

●In Windows

a.Directly download the obsutil package to your local PC using the corresponding download link.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	2 Download and Installation
b.	After the download completes, decompress the package to a	c fi
	folder.
c.	Double-click obsutil.exe in the decompressed folder and then you can
	use the tool.

NOTE

Alternatively, you can open the CLI to go to the upper-level directory of obsutil.exe and run obsutil commands. The command line structures of the two modes are ff n For details, see Command Line Structure.

●In Linux

a. Open the CLI and run the wget command to download the obsutil tool

package.

wget https://obs-community-intl.obs.ap-southeast-1.myhuaweicloud.com/obsutil/current/ obsutil_linux_amd64.tar.gz

NOTE

You can also download the obsutil package from a PC running the Windows operating system and then use a cross-platform transfer tool (such as WinSCP) to transfer the package to your host running the Linux operating system.

b.Run the following command in the directory where the tool package

resides:

tar -xzvf obsutil_linux_amd64.tar.gz

c.Go to the directory where obsutil resides and run the following command

to grant the execute permission to obsutil:

chmod 755 obsutil

●macOS

a.Directly download the obsutil package to your local PC using the corresponding download link.

b. After the download completes, decompress the package to a	c fi
folder.

c.Open the CLI, go to the directory where obsutil resides, and run the

following command to grant the execute permission to obsutil:

chmod 755 obsutil

NOTE

If you need to use obsutil on a HUAWEI CLOUD ECS, see the reference section below to c nfig access to OBS over intranet to save ffic costs.

● Accessing OBS over Intranet by Using obsutil on a Linux ECS

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	3 Getting Started

3Getting Started

3.1 Preparing the Environment

To use obsutil, you need to register a cloud service account, enable OBS, and obtain the access keys (AK and SK) fi

Step 1 Register a cloud service account.

Before using OBS, ensure that you have a cloud service account.

1.Open a browser.

2.Log in to the HUAWEI CLOUD website at huaweicloud.com/intl/en-us/.

3.In the upper right corner of the page, click Register.

4.Enter the registration information and click Register.

Step 2 Enable OBS.

Ensure that your account balance is ffic n before using OBS.

1.Log in to OBS Console.

2.Click Fees in the upper right corner of the page. The Billing Center page is displayed.

3.Then click Top Up.

4.Top up the account as prompted.

5.Go back to the management console page after the recharging is successful.

6.Click Service List on the top menu bar. Choose Storage > Object Storage Service to log in to OBS Console.

Step 3 (Optional) Create an IAM user.

For data security, it is recommended that you do not use the account directly to access OBS. Through the Identity and Access Management (IAM) service, you can create a user who has the permission to access OBS resources and manage buckets and objects on obsutil. If you do not need to use any IAM user, skip this step.

1.On the top navigation bar of the console, choose Service List > Management & Deployment > Identity and Access Management.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	3 Getting Started

2.On the displayed IAM console page, create a user group with OBS permissions c nfig

For details, see Creating a User Group. After the user group is created, locate

the row that displays Global service > OBS in the User Group Permissions, and click C nfig Policy in the row to set OBS permissions for the user group.

NOTE

For details about OBS policies, see Permissions Management

3.Create a user.

For details, see Creating a User. When creating a user, set the User Group to the one created in Step 3.2 with OBS permissions c nfig

NOTE

If the user group is not c nfig with OBS permissions, you can c nfig fin g n permissions on OBS Console through bucket policies or object policies. For details, see

Permission Control.

Step 4 Obtain access keys.
OBS uses AKs and SKs in user accounts for signature v fic		n to ensure that
only authorized accounts can access	c fi OBS resources. Detailed

explanations about AK and SK are as follows:

●Access key ID (AK): indicates the ID of the access key, which is a unique

n fi used together with a secret access key to sign requests cryptographically.

●Secret access key (SK): indicates the private key used together with its associated AK to cryptographically sign requests. The AK and SK are used together to identify a request sender to prevent the request from being m fi

NOTE

A user can create a maximum of two valid access keys.

Create access keys as follows:

1.In the upper right corner of the console page, select My Credential under the username.

2.On the My Credentials page, select Access Keys in the navigation pane on the left.

3.On the Access Keys page, click Add Access Key.

NOTE

A user can create a maximum of two valid access keys.

4.In the Add Access Key dialog box that is displayed, enter the password and

its v fic

n code.

NOTE

–If you have not bound an email address or mobile number, enter only the password.

–If you have bound an email address and a mobile number, you can select the

v fic

n by email or mobile phone.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	3 Getting Started

5.Click OK.

6.In the Download Access Key dialog box that is displayed, click OK to save the access keys to your browser's default download path.

NOTE

Keep the access keys properly to prevent information leakage. If you click Cancel in the dialog box, the access keys will not be downloaded, and you cannot download them later. Re-create access keys if required.

7. Open the downloaded credentials.csv fi to obtain the access keys (AK and SK).

NOTE

In the access key fi the value in the Access Key ID column is the AK, and the value in the Secret Access Key column is the SK.

----End

3.2 Performing Initial C nfig	n
Before using obsutil, you need to c nfig	the interconnection between obsutil

and OBS, including the endpoint and access keys (AK and SK) of OBS. You can use obsutil to perform operations on OBS buckets and objects only after obtaining the OBS authentication.

Prerequisites

●You have downloaded the software package of obsutil. For details, see

Download and Installation.

●You have obtained the enabled regions and endpoints of OBS. For details, see Regions and Endpoints. If you want to access OBS in the AP-Hong Kong region, the actual OBS service address is: https://obs.ap- southeast-3.myhuaweicloud.com.

●You have obtained the access keys (AK and SK). For details about how to obtain access keys, see Preparing the Environment. Click here to open the access key management page.

C nfig	n Method
	Method 1: Run the c nfig command to initialize obsutil. For details about the
	c	nfig command, see Updating a C nfig		n File. The following is an
	example:
	●	In Windows
			obsutil c nfig -i=ak -k=sk -e=endpoint

● In Linux or macOS

./obsutil c nfig -i=ak -k=sk -e=endpoint

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)								3 Getting Started
	NOTE
●	After running the preceding commands, a c				nfig	n fi	b	c nfig is
	automatically generated in the same home directory of the user who executes obsutil
	commands (the ~ directory in Linux or macOS, and the C:\Users\<Username> directory
	in Windows).		b	c nfig contains all the c nfig		n information of obsutil.
●	For details about the parameters in the b				c nfig fi		see Parameter Description.
●	The b	c	nfig fi	contains the AK and SK information of a user. Therefore, it is
	hidden by default to prevent key disclosure. To query the fi						run the following
	command in the home directory of the user who executes obsutil commands.

●In Windows dir

●In Linux or macOS ls -a

or ls -al

●	obsutil encrypts the AK and SK in the b	c	nfig fi	to ensure key security.
●	Note: You can use the -i, -k, and -e options to c		nfig	user information for

authentication. You can run the history command in the Linux OS to query the parameter values. Exercise caution when performing this operation.

Method 2: You can use C nfig to implement initial c nfig

ng Auto Obtaining of Access Keys for obsutil n

Checking the Connectivity

After the c nfig n is complete, you can check whether it is correct by running the following commands:

●In Windows

obsutil ls -s

●In Linux or macOS

	./obsutil ls -s
Check the c nfig		n result based on the command output:
● If the command output contains Bucket number is:, the c nfig			n is
correct.

●If the command output contains Http status [403], the access keys are incorrectly c nfig

●If the command output contains A connection attempt failed, then OBS cannot be accessed. In this case, check the network condition.

NOTE

If the command output contains Http status [403], you may not have the required permissions for obtaining the bucket list. In this case, further locate the root cause based on the c fic situation.

3.3 Quick Start

This section uses the Linux OS as an example to describe how to use obsutil to perform basic data operations in OBS. For details, see Figure 3-1.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	3 Getting Started

Figure 3-1 obsutil fl w for a quick start

Prerequisites

●	You have obtained obsutil and completed initial c nfig	n
●	The directory saving the tool is accessed.

Procedure

Step 1 Run the ./obsutil mb obs://bucket-test -location=cn-south-1 command to create a new bucket named bucket-test in the CN South-Guangzhou region.

./obsutil mb obs://bucket-test -location=cn-south-1

Create bucket [bucket-test] successfully!

NOTE

In the preceding command, parameter location indicates the region where a bucket is created. It is mandatory only when the endpoint set during initial c nfig n belongs to any other regions than the default one CN North-Beijing1 (cn-north-1). Click here to query currently valid regions.

Step 2 Run the ./obsutil cp /temp/test.txt obs://bucket-test/test.txt command to upload the test.txt fi to bucket bucket-test.

./obsutil cp /temp/test.txt obs://bucket-test/test.txt

Parallel:	5	Jobs:	5
Threshold:	52428800		PartSize:	5242880
Exclude:		Include:

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	3 Getting Started
VerifyLength: false	VerifyMd5: false

CheckpointDir: /temp/.obsutil_checkpoint

test.txt:[==============================================] 100.00% 48.47 KB/s 0s Upload successfully, 4.44KB, /temp/test.txt --> obs://bucket-test1/test.txt

Step 3 Run the ./obsutil cp obs://bucket-test/test.txt /temp/test1.txt command to download test.txt from bucket bucket-test to a local PC.

./obsutil cp obs://bucket-test/test.txt /temp/test1.txt

Parallel:	5	Jobs:	5
Threshold:	52428800		PartSize:	5242880
Exclude:		Include:
VerifyLength: false		VerifyMd5:		false
CheckpointDir: /temp/.obsutil_checkpoint

test.txt:[=============================================] 100.00% 775.52 KB/s 0s Download successfully, 4.44KB, obs://bucket-test1/test.txt --> /temp/test1.txt

Step 4 Run the ./obsutil rm obs://bucket-test/test.txt -f command to delete object test.txt from bucket bucket-test.

./obsutil rm obs://bucket-test/test.txt -f

Delete object [test.txt] in the bucket [bucket-test] successfully!

Step 5 Run the ./obsutil rm obs://bucket-test -f command to delete bucket bucket-test.

./obsutil rm obs://bucket-test -f

Delete bucket [bucket-test] successfully!

----End

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

4Bucket Commands

4.1 Creating a Bucket

Function

You can use this command to create a bucket. A bucket name must be unique in OBS. One account can create a maximum of 100 buckets.

NOTE

If you create a bucket and name it the same as an existing one in the same account and region, no error will be reported and status code 200 is returned. The bucket properties comply with those set in the fi creation request. In other cases, creating a bucket with the same name as an existing one will receive the status code 409, indicating that the bucket already exists.

NOTICE

If the c nfig endpoint is a global domain name, you may need to wait several minutes before uploading objects to the created bucket. Therefore, set the endpoint to a regional domain name according to Performing Initial

C nfig n if you want to upload objects instantly to the bucket.

Command Line Structure

●In Windows

obsutil mb obs://bucket [-acl=xxx] [-sc=xxx] [-location=xxx] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [- t=xxx]

●In Linux or macOS

./obsutil mb obs://bucket [-acl=xxx] [-sc=xxx] [-location=xxx] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil mb obs://bucket-test command to create a bucket. The creation is successful.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

	obsutil mb obs://bucket-test
	Create bucket [bucket-test] successfully, request id [0000016979E1D2EA860BB5E80A6B8FCC]

●Take the Windows OS as an example. Run the obsutil mb obs://bucket001

command to create a namesake bucket. The creation fails.

obsutil mb obs://bucket001

Create bucket [bucket001] failed, http status [409], error code [BucketAlreadyExists], error message [The requested bucket name is not available. The bucket namespace is shared by all users of the system. Please select a ff n name andtry again.], request id [04030000016757F31A0333281A6B1E92]

Parameter Description

Parame	Optional or	Description
ter	Mandatory

bucket	Mandatory	Bucket name
		NOTE
			A bucket name must comply with the following rules:
			● Contains 3 to 63 characters, including lowercase
			letters, digits, hyphens (-), and periods (.), and starts
			with a digit or letter.
			● Cannot be an IP address.
			● Cannot start or end with a hyphen (-) or period (.).
			● Cannot contain two consecutive periods (.), for
			example, my..bucket.
			● Cannot contain periods (.) and hyphens (-) adjacent
			to each other, for example, my-.bucket or my.-
			bucket.

acl	Optional	Access control policies that can be		c fi	when
	(additional	creating a bucket. Possible values are:
	parameter)	●	private
		●	private
		●	public-read
		● public-read-write
		NOTE
			The preceding three values indicate private read and
			write, public read, and public read and write.

sc	Optional	Default bucket storage class that can be			c fi
	(additional	when creating a bucket. Possible values are:
	parameter)	● standard: OBS Standard, which features low
		● standard: OBS Standard, which features low
			access latency and high throughput, and is
			applicable to storing frequently accessed data
			(multiple accesses per month) or data that is
			smaller than 1 MB
		● warm: OBS Infrequent Access. It is applicable to
			storing infrequently accessed (less than 12 times
			a year) data that requires quick response.
		● cold: OBS Archive. It is secure, durable, and
			inexpensive, and applicable to archiving rarely-
			accessed (once a year) data.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

Parame	Optional or	Description
ter	Mandatory

location	Mandatory	Region where the bucket resides.
	unless the	NOTE
	region where	This parameter indicates the region where a bucket will
	the OBS service	be created. It is mandatory only when the endpoint
	resides is not	belongs to any other regions than the default one CN
	the default	North-Beijing1 (cn-north-1). Click here to query currently
	the default	valid regions.
	region	valid regions.
	region
	(additional
	parameter)

c nfig	Optional	fin c nfig		n fi for executing a
	(additional	command. For details about parameters that can
	parameter)	be c nfig	see Parameter Description.

e	Optional	c fi	the endpoint.
	(additional
	parameter)

i	Optional	c fi	the user's AK.
	(additional
	parameter)

k	Optional	c fi	the user's SK.
	(additional
	parameter)

t	Optional	c fi	the user's security token.
	(additional
	parameter)

4.2 Listing Buckets

Function

You can use this command to obtain the bucket list. In the list, bucket names are displayed in lexicographical order.

Command Line Structure

●In Windows

obsutil ls [-s] [-sc] [-j=1] [-limit=1] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

●In Linux or macOS

./obsutil ls [-s] [-sc] [-j=1] [-limit=1] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil ls -limit=5 command

to obtain the bucket list.

obsutil ls -limit=5

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)					4 Bucket Commands
Bucket	CreationDate	Location		BucketType
obs://bucket001	2018-09-03T01:53:02Z		example		OBJECT
obs://bucket002	2018-11-01T01:40:01Z		example		OBJECT
obs://bucket003	2018-10-25T11:45:45Z		example		OBJECT
obs://bucket004	2018-10-26T02:33:09Z		example		OBJECT
obs://bucket005	2018-10-26T02:34:50Z		example		OBJECT

Bucket number is: 5

Parameter Description

Parameter	Optional or Mandatory	Description

s	Optional (additional	Displays	m		fi query result.
	parameter)	NOTE
		In the	m	fi	format, the returned
		result contains only the bucket name.

sc	Optional (additional	Queries the storage classes of the
	parameter)	buckets when listing buckets.

j	Optional (additional	Indicates the maximum number of
	parameter). It must be	concurrent tasks for querying the
	used together with sc.	bucket storage class. The default
		value is the value of defaultJobs in
		the c nfig			n fi
		NOTE
		The value is ensured to be greater than or
		equal to 1.

limit	Optional (additional	Maximum number of buckets that
	parameter)	can be queried. If the value is less
		than 0, all buckets are listed. If it is
		left blank, a maximum of 1000
		buckets can be listed by default.

c nfig	Optional (additional	fin		c	nfig	n fi for
	parameter)	executing a command. For details
		about parameters that can be
		c nfig	see Parameter
		Description.

e	Optional (additional	c fi	the endpoint.
	parameter)

i	Optional (additional	c fi	the user's AK.
	parameter)

k	Optional (additional	c fi	the user's SK.
	parameter)

t	Optional (additional	c fi	the user's security token.
	parameter)

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands
NOTE
In the bucket listing result, the BucketType fi	indicates the bucket type; OBJECT
indicates the bucket for object storage.

4.3 Querying Bucket Properties

Function

You can use this command to query the basic properties of a bucket, including its default storage class, region, version ID, storage usage, bucket quota, and the number of objects in the bucket.

Command Line Structure

●In Windows

obsutil stat obs://bucket [-acl] [-bf=xxx] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

●In Linux or macOS

./obsutil stat obs://bucket [-acl] [-bf=xxx] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil stat obs://bucket-test

command to query the basic properties of bucket bucket-test.

obsutil stat obs://bucket-test

Bucket:

obs://bucket-test

StorageClass:

standard

ObsVersion:

3.0

ObjectNumber:

8005

Size:

320076506

Quota:

Parameter Description

Parameter	Optional or	Description
	Mandatory

bucket	Mandatory	Bucket name

acl	Optional	Queries the access control policies of the
		bucket while querying bucket properties.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)							4 Bucket Commands

	Parameter	Optional or	Description
		Mandatory
	bf	Optional	Display format of the used bucket capacity
		(additional	(in bytes) Value options:
		parameter)	●	human-readable
			●	human-readable
			●	raw
			NOTE
				If this parameter is not c			nfig	the display
				format of the used bucket capacity (in bytes) is
				determined by the humanReadableFormat
				parameter in the c nfig			n fi

	c nfig	Optional			fin	c nfig	n fi	for executing
		(additional	a command. For details about parameters
		parameter)	that can be c			nfig	see Parameter
			Description.

	e	Optional		c fi	the endpoint.
		(additional
		parameter)

	i	Optional		c fi	the user's AK.
		(additional
		parameter)

	k	Optional		c fi	the user's SK.
		(additional
		parameter)

	t	Optional		c fi	the user's security token.
		(additional
		parameter)

	payer	Optional		c fi	that requester-pays is enabled on a
		(additional	bucket.
		parameter)

Response

Field	Description

Bucket	Bucket name

StorageClass	Default storage class of the bucket

Location	Region where the bucket resides

ObsVersion	Version of the bucket

BucketType	Type of a bucket. OBJECT indicates a bucket for object
	storage.

ObjectNumber	Number of objects in the bucket

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)		4 Bucket Commands

	Field	Description

	Size	Storage usage of the bucket, in bytes

	Quota	Bucket quota. Value 0 indicates that no upper limit is set for
		the bucket quota.

	Acl	Access control policy of the bucket

4.4 Setting Bucket Properties

Function

You can use this command to set the properties of a bucket, such as storage classes and access policies.

Command Line Structure

●In Windows

obsutil chattri obs://bucket [-sc=xxx] [-acl=xxx] [-aclXml=xxx] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

●In Linux or macOS

./obsutil chattri obs://bucket [-sc=xxx] [-acl=xxx] [-aclXml=xxx] c nfig xxx [-e=xxx] [-i=xxx] [- k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil chattri obs://buckettest -acl=private command to change the access control policy of the bucket

to private read and write.

obsutil chattri obs://bucket-test -acl=private

Set the acl of bucket [bucket-test] to [private] successfully, request id [04050000016836C5DA6FB21F14A2A0C0]

Parameter Description

Parameter	Optional or	Description
	Mandatory

bucket	Mandatory	Bucket name

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)				4 Bucket Commands

	Parameter	Optional or	Description
		Mandatory
	sc	Optional	Default storage class of the bucket. Possible
		(additional	values are:
		parameter)	● standard: OBS Standard, which features
			● standard: OBS Standard, which features
				low access latency and high throughput,
				and is applicable to storing frequently
				accessed data (multiple accesses per
				month) or data that is smaller than 1
				MB
			● warm: OBS Infrequent Access. It is
				applicable to storing infrequently
				accessed (less than 12 times a year) data
				that requires quick response.
			● cold: OBS Archive. It is secure, durable,
				and inexpensive, and applicable to
				archiving rarely-accessed (once a year)
				data.

	acl	Optional	Access control policies that can be		c fi
		(additional	for buckets. Possible values are:
		parameter)	●	private
			●	private
			●	public-read
			● public-read-write
			NOTE
				The preceding three values indicate private read
				and write, public read, and public read and write.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

Parameter	Optional or	Description
	Mandatory

aclXml	Optional	Access control policy of the bucket, in XML
	(additional	format.
	parameter)		<AccessControlPolicy>
			<Owner>
			<ID>ownerid</ID>
			</Owner>
			<AccessControlList>
			<Grant>
			<Grantee>
				<ID>userid</ID>
			</Grantee>
			<Permission>[WRITE\|WRITE_ACP\|READ\|
			READ_ACP\|FULL_CONTROL]</Permission>
			</Grant>
			<Grant>
			<Grantee>
				<Canned>Everyone</Canned>
			</Grantee>
			<Permission>[WRITE\|WRITE_ACP\|READ\|
			READ_ACP\|FULL_CONTROL]</Permission>
			</Grant>
			</AccessControlList>
			</AccessControlPolicy>
		NOTE
			● Owner: Optional. Specify the bucket owner's
			ID.
			● In AccessControlList, the Grant fi				contains
			the authorized users. Grantee				c fi	the
			IDs of authorized users. Canned				c fi	the
			authorized user group (currently, only
			Everyone is supported).
			● The following permissions can be granted:
			WRITE (write), WRITE_ACP (write ACL), READ
			(read), READ_ACP (read ACL), and
			FULL_CONTROL (full control).
		NOTICE
			Because angle brackets (<) and (>) are
			unavoidably included in the parameter value, you
			must use quotation marks to enclose them for
			escaping when running the command. Use single
			quotation marks for Linux or macOS and
			quotation marks for Windows.

c nfig	Optional			fin	c nfig	n fi for executing
	(additional	a command. For details about parameters
	parameter)	that can be c			nfig	see Parameter
		Description.

e	Optional		c fi	the endpoint.
	(additional
	parameter)

i	Optional		c fi	the user's AK.
	(additional
	parameter)

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)				4 Bucket Commands

	Parameter	Optional or	Description
		Mandatory
	k	Optional	c fi	the user's SK.
		(additional
		parameter)

	t	Optional	c fi	the user's security token.
		(additional
		parameter)

	payer	Optional	c fi	that requester-pays is enabled on a
		(additional	bucket.
		parameter)

NOTE

Only one from sc, acl, or aclXml can be set for each command.

4.5 Deleting a Bucket

Function

You can use this command to delete a bucket. The bucket to be deleted must be empty (containing no objects, historical versions, or fragments).

NOTE

To delete a non-empty bucket, run the commands in Deleting a Multipart Upload Task and Deleting an Object to clear the bucket, and then run the following command to delete the bucket.

Command Line Structure

●In Windows

obsutil rm obs://bucket [-f] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

●In Linux or macOS

./obsutil rm obs://bucket [-f] c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil rm obs://bucket-test

command to delete bucket bucket-test.

obsutil rm obs://bucket-test

Do you want delete bucket [bucket-test] ? Please input (y/n) to c nfi m y

Delete bucket [bucket-test] successfully!

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

Parameter Description

Parameter	Optional or	Description
	Mandatory

bucket	Mandatory	Bucket name

f	Optional (additional	Runs in force mode.
	parameter)

c nfig	Optional (additional		fin c nfig	n fi	for
	parameter)	executing a command. For details about
		parameters that can be c		nfig	see
		Parameter Description.

e	Optional (additional	c fi	the endpoint.
	parameter)

i	Optional (additional	c fi	the user's AK.
	parameter)

k	Optional (additional	c fi	the user's SK.
	parameter)

t	Optional (additional	c fi	the user's security token.
	parameter)

payer	Optional (additional	c fi	that requester-pays is enabled on
	parameter)	a bucket.

4.6 C nfig ng a Bucket Policy

Function

You can use this command to c nfig a bucket policy.

Command Line Structure

●In Windows

obsutil bucketpolicy obs://bucket -method=put c fi xxx c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

●In Linux or macOS

./obsutil bucketpolicy obs://bucket -method=put c fi xxx c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil bucketpolicy obs://

bucket -method=put	c fi	m	cy	n command to set a
bucket policy based on fi	policy.json.
obsutil bucketpolicy obs://bucket -method=put		c fi	m	cy n

Put bucketPolicy succeed, requestId is [04050000016836C5DA6FB21F14A2A0C0]

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

Parameter Description

Parameter	Optional or	Description
	Mandatory

bucket	Mandatory	Bucket name

method	Mandatory	c fi	the method. Set this parameter to put
		when c	nfig	ng a bucket policy.

c fi	Mandatory	Path of the local policy fi			to import

c nfig	Optional		fin	c nfig	n fi for executing a
	(additional	command. For details about parameters that can
	parameter)	be c nfig		see Parameter Description.

e	Optional	c fi	the endpoint.
	(additional
	parameter)

i	Optional	c fi	the user's AK.
	(additional
	parameter)

k	Optional	c fi	the user's SK.
	(additional
	parameter)

t	Optional	c fi	the user's security token.
	(additional
	parameter)

payer	Optional	c fi	that requester-pays is enabled on a
	(additional	bucket.
	parameter)

4.7 Obtaining a Bucket Policy

Function

You can use this command to obtain a bucket policy.

Command Line Structure

● In Windows

	obsutil bucketpolicy obs://bucket -method=get	c	fi	xxx	c nfig xxx	[-e=xxx] [-i=xxx] [-k=xxx]
	[-t=xxx]
●	In Linux or macOS
	./obsutil bucketpolicy obs://bucket -method=get	c	fi	xxx	c nfig xxx	[-e=xxx] [-i=xxx] [-
	k=xxx] [-t=xxx]

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

Examples

●Take the Windows OS as an example. Run the obsutil bucketpolicy obs://

bucket -method=get	c fi	m	cy	n command to export the
bucket policy to local fi	policy.json.
obsutil bucketpolicy obs://bucket -method=get		c fi	m	cy n

Export bucketPolicy to [d:\temp\policy.json] succeed, requestId is [04050000016836C5DA6FB21F14A2A0C0]

Parameter Description

Parameter	Optional or	Description
	Mandatory

bucket	Mandatory	Bucket name

method	Mandatory	c fi	the method. Set this parameter to gut
		when obtaining a bucket policy.

c fi	Optional	If this parameter is set, the policy is exported to a
	(additional	local fi	If not set, the policy is exported in a
	parameter)	standard manner by default.

c nfig	Optional	fin c nfig		n fi for executing a
	(additional	command. For details about parameters that can
	parameter)	be c nfig	see Parameter Description.

e	Optional	c fi	the endpoint.
	(additional
	parameter)

i	Optional	c fi	the user's AK.
	(additional
	parameter)

k	Optional	c fi	the user's SK.
	(additional
	parameter)

t	Optional	c fi	the user's security token.
	(additional
	parameter)

payer	Optional	c fi	that requester-pays is enabled on a
	(additional	bucket.
	parameter)

4.8 Deleting a Bucket Policy

Function

You can use this command to delete a bucket policy.

Issue 16 (2021-03-22)

Object Storage Service
Tool Guide (obsutil)	4 Bucket Commands

Command Line Structure

●In Windows

obsutil bucketpolicy obs://bucket -method=delete c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

●In Linux or macOS

./obsutil bucketpolicy obs://bucket -method=delete c nfig xxx [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

●Take the Windows OS as an example. Run the obsutil bucketpolicy obs://

bucket -method=delete command to delete a bucket policy.

obsutil bucketpolicy obs://bucket -method=delete

Delete bucketPolicy succeed, requestId is [04050000016836C5DA6FB21F14A2A0C0]

Parameter Description

Parameter	Optional or	Description
	Mandatory

bucket	Mandatory	Bucket name

method	Mandatory	c fi	the method. Set this parameter to delete
		when deleting a bucket policy.

c nfig	Optional	fin c nfig		n fi for executing a
	(additional	command. For details about parameters that can
	parameter)	be c nfig	see Parameter Description.

e	Optional	c fi	the endpoint.
	(additional
	parameter)

i	Optional	c fi	the user's AK.
	(additional
	parameter)

k	Optional	c fi	the user's SK.
	(additional
	parameter)

t	Optional	c fi	the user's security token.
	(additional
	parameter)

payer	Optional	c fi	that requester-pays is enabled on a
	(additional	bucket.
	parameter)

Issue 16 (2021-03-22)

+ 182 hidden pages

HUAWEI Tool Guide User Manual

Contents

1 Introduction to obsutil

2 Download and Installation

3 Getting Started

3.1 Preparing the Environment

3.3 Quick Start

4 Bucket Commands

4.1 Creating a Bucket

4.2 Listing Buckets

4.3 Querying Bucket Properties

4.4 Setting Bucket Properties

4.5 Deleting a Bucket

4.7 Obtaining a Bucket Policy

4.8 Deleting a Bucket Policy