CreateGatewayFileShare - Cloud Storage Gateway - Alibaba Cloud Documentation Center

Creates a file share for a file gateway.

Operation description

Before you call this operation, ensure that the following requirements are met:

You have created and deployed a file gateway that has an unused cache disk.
You have an Object Storage Service (OSS) bucket.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

hcs-sgw:CreateGatewayFileShare

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
GatewayId	string	Yes	The gateway ID.	gw-000eg44nmxbsfwbvq***
Name	string	Yes	The name of the file share. The name must be 1 to 255 characters in length. It can contain uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).	alex***
ShareProtocol	string	Yes	The file sharing protocol. Valid values: NFS: Network File System (NFS) SMB: Server Message Block (SMB)	NFS
RemoteSync	boolean	No	Indicates whether to enable remote sync for the file share. Valid values: false (default): disables remote sync. true: enables remote sync.	false
PollingInterval	integer	No	The remote sync interval, in seconds. The value must be an integer from 15 to 36,000. Note If you use replication mode and enable both remote sync and file data download, the value must be an integer from 3,600 to 36,000.	4500
IgnoreDelete	boolean	No	Indicates whether to ignore deletions. If this feature is enabled, deleting a file on the gateway does not delete the corresponding file in the OSS bucket. false (default): does not ignore deletions. true: ignores deletions. Note This feature is supported by gateway versions 1.0.40 and later.	false
FrontendLimit	integer	No	The maximum write speed of the file share, in MB/s. Valid values are 0 to 1,280. A value of 0 indicates no limit. The default value is 0.	1234
BackendLimit	integer	No	The maximum upload speed of the file share, in MB/s. Valid values are 0 to 1,280. A value of 0 indicates no limit. The default value is 0. Note If you set a maximum write speed, the maximum upload speed cannot be less than the maximum write speed.	1234
InPlace	boolean	No	This parameter is deprecated. Do not set this parameter.	false
CacheMode	string	No	The cache mode of the file share. Valid values: Cache: cache mode Sync: replication mode	Cache
Browsable	boolean	No	For a file share that uses the SMB protocol, this parameter indicates whether the share is discoverable in Network Neighborhood. Valid values: true (default): The file share is discoverable. false: The file share is not discoverable. Note This parameter is not valid for the NFS protocol.	true
Squash	string	No	The user mapping for the file share that uses the NFS protocol. Valid values: none (default) root_squash all_squash all_anonymous	none
ReadWriteUserList	string	No	A list of users with read and write permissions for the SMB file share. Separate multiple users with a comma (,). Note This parameter is not valid for the NFS protocol.	user1，user2
ReadOnlyUserList	string	No	A list of users with read-only permissions for the SMB file share. Separate multiple users with a comma (,). Note This parameter is not valid for the NFS protocol.	userA，userB
ReadWriteClientList	string	No	A list of clients with read and write permissions for the NFS file share. The list can contain IP addresses or IP address ranges. Separate multiple clients with a comma (,).	12.12.12.12
ReadOnlyClientList	string	No	A list of clients with read-only permissions for the NFS file share. The list can contain IP addresses or IP address ranges. Separate multiple clients with a comma (,).	12.12.12.12
OssBucketName	string	Yes	The name of the OSS bucket that the file share uses. Note File shares do not support OSS buckets of the Cold Archive storage class or buckets that have the origin fetch feature enabled. If you enable multi-bucket aggregation, separate multiple OSS bucket names with a comma (,).	testbucket
OssEndpoint	string	Yes	The endpoint of the region where the OSS bucket is located. Note Use an internal endpoint if the OSS bucket and the gateway are in the same region. For example, `oss-cn-hangzhou-internal.aliyuncs.com`. Otherwise, use a public endpoint.	oss-cn-hangzhou-internal.aliyuncs.com
OssBucketSsl	boolean	No	Indicates whether to use Secure Sockets Layer (SSL) to access the OSS bucket. Valid values: true (default): enables SSL. false: disables SSL.	true
LagPeriod	integer	No	The synchronization latency in seconds. This is the delay when synchronizing the local cache of the gateway to the OSS bucket. Valid values are 5 to 120. The default value is 5. Note This feature is supported by gateway versions 1.0.40 and later.	5
DirectIO	boolean	No	Deprecated.	false
LocalFilePath	string	Yes	The internal device name of the cache disk that the file share uses. To get this name, call the `DescribeGatewayCaches` operation.	/dev/vdb
ServerSideEncryption	boolean	No	Deprecated.	false
ServerSideCmk	string	No	Deprecated.	xxxxx
ClientSideEncryption	boolean	No	Deprecated.	false
ClientSideCmk	string	No	Deprecated.	xxxxx
KmsRotatePeriod	integer	No	Deprecated.	0
PathPrefix	string	No	The path of the subdirectory in the OSS bucket that the file share uses. If you leave this parameter empty, the file share uses the root directory of the bucket.	test1
FastReclaim	boolean	No	Indicates whether to enable upload optimization for the file share. This is suitable for scenarios where you only back up data to the cloud. Valid values: false (default): disables upload optimization. true: enables upload optimization. Note This feature is supported by gateway versions 1.0.39 and later.	false
SupportArchive	boolean	No	This parameter is deprecated. Do not set this parameter.	false
WindowsAcl	boolean	No	For the SMB protocol, indicates whether to enable access control with Windows Access Control Lists (ACLs). This requires an Active Directory (AD) domain. Valid values: false (default): disables Windows ACLs. true: enables Windows ACLs. Note This feature is supported by gateway versions 1.0.45 and later.	false
AccessBasedEnumeration	boolean	No	For the SMB protocol, indicates whether to enable Windows access-based enumeration (ABE). This parameter takes effect only if `WindowsAcl` is set to `true`. Valid values: false (default): disables Windows ABE. true: enables Windows ABE. Note This feature is supported by gateway versions 1.0.45 and later.	false
NfsV4Optimization	boolean	No	For the NFS protocol, indicates whether to enable NFSv4 optimization to improve mount and upload efficiency. Valid values: false (default): disables NFSv4 optimization. true: enables NFSv4 optimization. Note If you enable this feature, you cannot mount the share with NFSv3. This feature is supported by gateway versions 1.2.0 and later.	false
TransferAcceleration	boolean	No	Indicates whether to enable transfer acceleration for the file share. The corresponding OSS bucket must also have transfer acceleration enabled. Note This feature is supported by gateway versions 1.3.0 and later.	false
RemoteSyncDownload	boolean	No	In replication mode, indicates whether to download file data. Valid values: false (default): does not download file data. true: downloads file data. Note This parameter takes effect only if remote sync is enabled for the share or the share is added to an express synchronization group.	false
DownloadLimit	integer	No	The maximum download speed for the file share in MB/s. Valid values range from 0 to 1280. A value of 0 indicates an unlimited speed. Note This parameter can be set only when the file share is in replication mode and file data download is enabled. It takes effect only if remote sync is enabled for the share or the share is added to an express synchronization group. This parameter is supported in gateway versions 1.3.0 and later.	0
PartialSyncPaths	string	No	In replication mode, lets you specify a collection of directory paths. Only these directories use replication mode. Note Before you can configure this setting, contact us to add your account to the whitelist.	test1
ServerSideAlgorithm	string	No	Deprecated.	AES256
BypassCacheRead	boolean	No	Indicates whether to read directly from OSS. Valid values: true: reads directly from OSS. false (default): does not read directly from OSS.	false
BindIPAddr	string	No	The virtual mount IP address to attach to the share. This parameter is used only for high availability (HA) gateways.	192.168.0.10
OssBucketRegionId	string	No	The region where the OSS bucket is located. Note If the gateway version is 2.0.0 or later and you pass this parameter correctly, the gateway uses the OSS v4 signature algorithm to access data in the OSS bucket. If the gateway version is earlier than 2.0.0 or you do not pass this parameter correctly, the gateway uses the OSS v1 signature algorithm to access data in the OSS bucket.	cn-hangzhou
BucketInfos	array<object>	No	Deprecated.
	object	No
Name	string	No	Deprecated.	test-aliyun
Endpoint	string	No	Deprecated.	oss-cn-hangzhou.aliyuncs.com
PathPrefix	string	No	Deprecated.	test1
BucketStub	boolean	No

Response elements

Element	Type	Description	Example
	object
Code	string	The status code. A value of `200` indicates that the request was successful.	200
Message	string	The returned message.	successful
RequestId	string	The request ID.	F8B59F29-453D-49BF-8673-EEB8F9F2D5C6
Success	boolean	Indicates whether the request was successful.	true
TaskId	string	The task ID.	t-000eg44nmxbsh3qk***

Examples

Success response

JSON format

{
  "Code": "200",
  "Message": "successful",
  "RequestId": "F8B59F29-453D-49BF-8673-EEB8F9F2D5C6",
  "Success": true,
  "TaskId": "t-000eg44nmxbsh3qk***"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter.FileShare.%s	The specified field %s for file share is invalid. Please check it again.	The specified file sharing parameter for the gateway is invalid. You must specify a valid parameter.
400	VersionNotSupported.FileShare.%s	The specified field %s for file share is not supported by current gateway version. Please check it again.	The specified file sharing parameter for the gateway does not match the gateway version. You must specify a valid parameter.
400	FileShareArchiveSupportConflict	You can configure the ArchiveSupport parameter only with NFS protocol and when the user mapping value is "none".

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.