All Products
Search

This Product

    Cloud Storage Gateway:CreateGatewayFileShare

    Document Center

    Cloud Storage Gateway:CreateGatewayFileShare

    Last Updated:Oct 12, 2025

    Creates a file share for a file gateway.

    Operation description

    Before you call this operation, make sure 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

    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 and can contain lowercase letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a lowercase letter.

    alex***

    ShareProtocol

    string

    Yes

    The file sharing protocol. Valid values:

    • NFS

    • SMB

    NFS

    RemoteSync

    boolean

    No

    Specifies 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 interval for remote sync. 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

    Specifies whether to ignore deletions. If you enable this feature, 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. Unit: MB/s. The value must be an integer from 0 to 1,280. The default value is 0, which indicates no limit.

    1234

    BackendLimit

    integer

    No

    The maximum upload speed of the file share. Unit: MB/s. The value must be an integer from 0 to 1,280. The default value is 0, which indicates no limit.

    Note

    If you set a maximum write speed, the maximum upload speed cannot be lower 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

    Specifies whether the file share is browsable in a Server Message Block (SMB) protocol environment. This means whether it can be discovered in Network Neighborhood. Valid values:

    • true (default): The file share is browsable.

    • false: The file share is not browsable.

    Note

    • This parameter is not valid for the Network File System (NFS) protocol.

    true

    Squash

    string

    No

    The user mapping for the file share under the NFS protocol. Valid values:

    • none (default)

    • root_squash

    • all_squash

    • all_anonymous

    none

    ReadWriteUserList

    string

    No

    The list of users with read and write permissions for the file share under the SMB protocol. Separate multiple users with commas (,).

    Note

    • This parameter is not valid for the NFS protocol.

    user1，user2

    ReadOnlyUserList

    string

    No

    The list of users with read-only permissions for the file share under the SMB protocol. Separate multiple users with commas (,).

    Note

    • This parameter is not valid for the NFS protocol.

    userA，userB

    ReadWriteClientList

    string

    No

    The list of clients with read and write permissions for the file share under the NFS protocol. The list can contain IP addresses or IP address ranges. Separate multiple clients with commas (,).

    12.12.12.12

    ReadOnlyClientList

    string

    No

    The list of clients with read-only permissions for the file share under the NFS protocol. The list can contain IP addresses or IP address ranges. Separate multiple clients with commas (,).

    12.12.12.12

    OssBucketName

    string

    Yes

    The name of the OSS bucket that corresponds to the file share.

    Note

    File shares do not support OSS buckets that have the origin fetch feature enabled.

    testbucket

    OssEndpoint

    string

    Yes

    The endpoint of the region where the OSS bucket is located.

    Note

    Differentiate between internal and public endpoints. If the OSS bucket and the gateway are in the same region, use an internal endpoint, such as oss-cn-hangzhou-internal.aliyuncs.com.

    oss-cn-hangzhou-internal.aliyuncs.com

    OssBucketSsl

    boolean

    No

    Specifies whether to enable 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. This is the delay for synchronizing the local cache of the gateway to the cloud OSS bucket. Unit: seconds. The value must be an integer from 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

    Specifies whether to enable Direct I/O (DirectIO) for data transfer. Valid values:

    • false (default): disables DirectIO.

    • true: enables DirectIO.

    false

    LocalFilePath

    string

    Yes

    The internal device name of the cache disk used by the file share. You can get this name by calling 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 corresponds to the file share. If this parameter is empty, it corresponds to the root directory of the bucket.

    test1

    FastReclaim

    boolean

    No

    Specifies whether to enable upload optimization for the file share. This is suitable for scenarios where data is purely backed up 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, specifies whether to enable access control using 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, specifies whether to enable Windows access-based enumeration (ABE). This parameter takes effect only when the WindowsAcl parameter 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, specifies whether to enable NFS v4 optimization to improve mount and upload efficiency. Valid values:

    • false (default): disables NFS v4 optimization.

    • true: enables NFS v4 optimization.

    Note

    After you enable this feature, mounting with NFS v3 is not supported. This feature is supported by gateway versions 1.2.0 and later.

    false

    TransferAcceleration

    boolean

    No

    Specifies whether to enable transfer acceleration for the file share. The corresponding OSS bucket must have transfer acceleration enabled.

    Note

    This feature is supported by gateway versions 1.3.0 and later.

    false

    RemoteSyncDownload

    boolean

    No

    In replication mode, specifies whether to download file data. Valid values:

    • false (default): does not download file data.

    • true: downloads file data.

    Note

    This parameter takes effect only when 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 of the file share. Unit: MB/s. The value must be an integer from 0 to 1,280. A value of 0 indicates no limit.

    Note

    • This parameter can be set only in replication mode when file data download is enabled. This parameter takes effect only when remote sync is enabled for the share or the share is added to an express synchronization group. This feature is supported by gateway versions 1.3.0 and later.

    0

    PartialSyncPaths

    string

    No

    In replication mode, you can set a collection of directory paths to specify that only these directories use replication mode.

    Note

    Contact us to add your account to the whitelist before you can configure this setting.

    test1

    ServerSideAlgorithm

    string

    No

    Deprecated.

    AES256

    BypassCacheRead

    boolean

    No

    Specifies 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

    Used only for high availability (HA) gateways. Sets the virtual mount IP address that is attached to the share.

    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 this parameter is correctly passed, 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 this parameter is not correctly passed, the gateway uses the OSS v1 signature algorithm to access data in the OSS bucket.

    cn-hangzhou

    BucketInfos

    array<object>

    No

    The list of bucket information.

    Note

    • This parameter is available only to whitelisted users.

    object

    No

    Name

    string

    No

    The name of the OSS bucket.

    test-aliyun

    Endpoint

    string

    No

    The endpoint of the OSS bucket.

    oss-cn-hangzhou.aliyuncs.com

    PathPrefix

    string

    No

    Deprecated.

    test1

    BucketStub

    boolean

    No

    Specifies whether to enable multi-bucket aggregation. Valid values:

    • true: enables multi-bucket aggregation.

    • false: disables multi-bucket aggregation.

    Note

    • This parameter is available only to whitelisted users.

    true

    Response elements

    Element

    Type

    Description

    Example

    object

    Code

    string

    The status code. A status code of 200 indicates that the request was successful.

    200

    Message

    string

    The message returned.

    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.