Skip to main content
A newer release of this product is available.

Create a CIFS share

Contributors
PDFs

POST /protocols/cifs/shares

Introduced In: 9.6

Creates a CIFS share.

Required properties

  • svm.uuid or svm.name - Existing SVM in which to create the CIFS share.

  • name - Name of the CIFS share.

  • path - Path in the owning SVM namespace that is shared through this share.

  • comment - Optionally choose to add a text comment of up to 256 characters about the CIFS share.

  • acls - Optionally choose to add share permissions that users and groups have on the CIFS share.

Default property values

If not specified in POST, the following default property values are assigned:

  • home_directory - false

  • oplocks - true

  • access_based_enumeration - false

  • change_notify - true

  • encryption - false

  • unix_symlink - local

  • vserver cifs share create

  • vserver cifs share properties add

  • vserver cifs share access-control create

Learn more

Parameters

Name Type In Required Description

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

Request Body

Name Type Description

_links

_links

access_based_enumeration

boolean

If enabled, all folders inside this share are visible to a user based on that individual user access right; prevents the display of folders or other shared resources that the user does not have access to.

acls

array[acls]

allow_unencrypted_access

boolean

Specifies whether or not the SMB2 clients are allowed to access the encrypted share.

attribute_cache

boolean

Specifies that connections through this share cache attributes for a short time to improve performance.

browsable

boolean

Specifies whether or not the Windows clients can browse the share.

change_notify

boolean

Specifies whether CIFS clients can request for change notifications for directories on this share.

comment

string

Specify the CIFS share descriptions.

continuously_available

boolean

Specifies whether or not the clients connecting to this share can open files in a persistent manner. Files opened in this way are protected from disruptive events, such as, failover and giveback.

dir_umask

integer

Directory Mode Creation Mask to be viewed as an octal number.

encryption

boolean

Specifies that SMB encryption must be used when accessing this share. Clients that do not support encryption are not able to access this share.

file_umask

integer

File Mode Creation Mask to be viewed as an octal number.

force_group_for_create

string

Specifies that all files that CIFS users create in a specific share belong to the same group (also called the "force-group"). The "force-group" must be a predefined group in the UNIX group database. This setting has no effect unless the security style of the volume is UNIX or mixed security style.

home_directory

boolean

Specifies whether or not the share is a home directory share, where the share and path names are dynamic. ONTAP home directory functionality automatically offer each user a dynamic share to their home directory without creating an individual SMB share for each user. The ONTAP CIFS home directory feature enable us to configure a share that maps to different directories based on the user that connects to it. Instead of creating a separate shares for each user, a single share with a home directory parameters can be created. In a home directory share, ONTAP dynamically generates the share-name and share-path by substituting %w, %u, and %d variables with the corresponding Windows user name, UNIX user name, and domain name, respectively.

  • Default value: 1

  • Introduced in: 9.6

  • readCreate: 1

  • x-nullable: true

max_connections_per_share

integer

Maximum number of tree connections on share.

name

string

Specifies the name of the CIFS share that you want to create. If this is a home directory share then the share name includes the pattern as %w (Windows user name), %u (UNIX user name) and %d (Windows domain name) variables in any combination with this parameter to generate shares dynamically.

namespace_caching

boolean

Specifies whether or not the SMB clients connecting to this share can cache the directory enumeration results returned by the CIFS servers.

no_strict_security

boolean

Specifies whether or not CIFS clients can follow a unix symlinks outside the share boundaries.

offline_files

string

Offline Files The supported values are:

  • none - Clients are not permitted to cache files for offline access.

  • manual - Clients may cache files that are explicitly selected by the user for offline access.

  • documents - Clients may automatically cache files that are used by the user for offline access.

  • programs - Clients may automatically cache files that are used by the user for offline access and may use those files in an offline mode even if the share is available.

oplocks

boolean

Specify whether opportunistic locks are enabled on this share. "Oplocks" allow clients to lock files and cache content locally, which can increase performance for file operations.

path

string

The fully-qualified pathname in the owning SVM namespace that is shared through this share. If this is a home directory share then the path should be dynamic by specifying the pattern %w (Windows user name), %u (UNIX user name), or %d (domain name) variables in any combination. ONTAP generates the path dynamically for the connected user and this path is appended to each search path to find the full Home Directory path.

  • example: /volume_1/eng_vol/

  • maxLength: 256

  • minLength: 1

  • Introduced in: 9.6

  • x-nullable: true

show_previous_versions

boolean

Specifies that the previous version can be viewed and restored from the client.

show_snapshot

boolean

Specifies whether or not the Snapshot copies can be viewed and traversed by clients.

svm

svm

SVM, applies only to SVM-scoped objects.

unix_symlink

string

Controls the access of UNIX symbolic links to CIFS clients. The supported values are:

  • local - Enables only local symbolic links which is within the same CIFS share.

  • widelink - Enables both local symlinks and widelinks.

  • disable - Disables local symlinks and widelinks.

volume

volume

vscan_profile

string

Vscan File-Operations Profile The supported values are:

  • no_scan - Virus scans are never triggered for accesses to this share.

  • standard - Virus scans can be triggered by open, close, and rename operations.

  • strict - Virus scans can be triggered by open, read, close, and rename operations.

  • writes_only - Virus scans can be triggered only when a file that has been modified is closed.
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "acls": [
    {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "permission": "string",
      "type": "string",
      "user_or_group": "ENGDOMAIN\\ad_user"
    }
  ],
  "comment": "HR Department Share",
  "dir_umask": 18,
  "file_umask": 18,
  "force_group_for_create": "string",
  "name": "HR_SHARE",
  "offline_files": "string",
  "path": "/volume_1/eng_vol/",
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "unix_symlink": "string",
  "volume": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "volume1",
    "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
  },
  "vscan_profile": "string"
}

Response

Status: 201, Created

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

655628

CIFS Share Creation with property 'SMB_ENCRYPTION' failed because the CIFS server does not support SMB3.0

655551

CIFS Share Creation failed because the specified path does not exist

655577

The CIFS share name cannot be more than 80 characters long

655399

Failed to create CIFS share. The CIFS server does not exist for specified SVM

656422

Failed to create the home directory share because the directory shares must specify a path relative to one or more home directory search paths

656423

Failed to create CIFS share. The Shares must define an absolute share path

656424

Failed to create CIFS the administrator share 'c$' because you are not permitted to created any admin shares

655625

Failed to create CIFS share. The Shares path is not a valid file-type for CIFS share

656426

CIFS Share Creation failed because the share name is invalid

655655

no-strict-security should be set to true only if unix_symlink is configured as "local" or "widelink"

655394

Failed to create CIFS share because share cannot be made continuously available unless running SMB3 or later.

4849678

Failed to create CIFS share because the specified UNIX group does not exist

655622

Invalid value for parameter {max-connections-per-share}. Maximum connections on CIFS share {name} must be between 1 to 4294967295.

2621706

The specified SVM UUID is incorrect for the specified SVM name
Name Type Description

error

returned_error
Example error 
{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

self

href

acls

The permissions that users and groups have on a CIFS share.

Name Type Description

_links

_links

permission

string

Specifies the access rights that a user or group has on the defined CIFS Share. The following values are allowed:

  • no_access - User does not have CIFS share access

  • read - User has only read access

  • change - User has change access

  • full_control - User has full_control access

type

string

Specifies the type of the user or group to add to the access control list of a CIFS share. The following values are allowed:

  • windows - Windows user or group

  • unix_user - UNIX user

  • unix_group - UNIX group

user_or_group

string

Specifies the user or group name to add to the access control list of a CIFS share.

svm

SVM, applies only to SVM-scoped objects.

Name Type Description

_links

_links

name

string

The name of the SVM. This field cannot be specified in a PATCH method.

uuid

string

The unique identifier of the SVM. This field cannot be specified in a PATCH method.

volume

Name Type Description

_links

_links

name

string

The name of the volume. This field cannot be specified in a POST or PATCH method.

uuid

string

Unique identifier for the volume. This corresponds to the instance-uuid that is exposed in the CLI and ONTAPI. It does not change due to a volume move.

  • example: 028baa66-41bd-11e9-81d5-00a0986138f7

  • Introduced in: 9.6

  • x-nullable: true

cifs_share

CIFS share is a named access point in a volume. Before users and applications can access data on the CIFS server over SMB, a CIFS share must be created with sufficient share permission. CIFS shares are tied to the CIFS server on the SVM. When a CIFS share is created, ONTAP creates a default ACL for the share with Full Control permissions for Everyone.

Name Type Description

_links

_links

access_based_enumeration

boolean

If enabled, all folders inside this share are visible to a user based on that individual user access right; prevents the display of folders or other shared resources that the user does not have access to.

acls

array[acls]

allow_unencrypted_access

boolean

Specifies whether or not the SMB2 clients are allowed to access the encrypted share.

attribute_cache

boolean

Specifies that connections through this share cache attributes for a short time to improve performance.

browsable

boolean

Specifies whether or not the Windows clients can browse the share.

change_notify

boolean

Specifies whether CIFS clients can request for change notifications for directories on this share.

comment

string

Specify the CIFS share descriptions.

continuously_available

boolean

Specifies whether or not the clients connecting to this share can open files in a persistent manner. Files opened in this way are protected from disruptive events, such as, failover and giveback.

dir_umask

integer

Directory Mode Creation Mask to be viewed as an octal number.

encryption

boolean

Specifies that SMB encryption must be used when accessing this share. Clients that do not support encryption are not able to access this share.

file_umask

integer

File Mode Creation Mask to be viewed as an octal number.

force_group_for_create

string

Specifies that all files that CIFS users create in a specific share belong to the same group (also called the "force-group"). The "force-group" must be a predefined group in the UNIX group database. This setting has no effect unless the security style of the volume is UNIX or mixed security style.

home_directory

boolean

Specifies whether or not the share is a home directory share, where the share and path names are dynamic. ONTAP home directory functionality automatically offer each user a dynamic share to their home directory without creating an individual SMB share for each user. The ONTAP CIFS home directory feature enable us to configure a share that maps to different directories based on the user that connects to it. Instead of creating a separate shares for each user, a single share with a home directory parameters can be created. In a home directory share, ONTAP dynamically generates the share-name and share-path by substituting %w, %u, and %d variables with the corresponding Windows user name, UNIX user name, and domain name, respectively.

  • Default value: 1

  • Introduced in: 9.6

  • readCreate: 1

  • x-nullable: true

max_connections_per_share

integer

Maximum number of tree connections on share.

name

string

Specifies the name of the CIFS share that you want to create. If this is a home directory share then the share name includes the pattern as %w (Windows user name), %u (UNIX user name) and %d (Windows domain name) variables in any combination with this parameter to generate shares dynamically.

namespace_caching

boolean

Specifies whether or not the SMB clients connecting to this share can cache the directory enumeration results returned by the CIFS servers.

no_strict_security

boolean

Specifies whether or not CIFS clients can follow a unix symlinks outside the share boundaries.

offline_files

string

Offline Files The supported values are:

  • none - Clients are not permitted to cache files for offline access.

  • manual - Clients may cache files that are explicitly selected by the user for offline access.

  • documents - Clients may automatically cache files that are used by the user for offline access.

  • programs - Clients may automatically cache files that are used by the user for offline access and may use those files in an offline mode even if the share is available.

oplocks

boolean

Specify whether opportunistic locks are enabled on this share. "Oplocks" allow clients to lock files and cache content locally, which can increase performance for file operations.

path

string

The fully-qualified pathname in the owning SVM namespace that is shared through this share. If this is a home directory share then the path should be dynamic by specifying the pattern %w (Windows user name), %u (UNIX user name), or %d (domain name) variables in any combination. ONTAP generates the path dynamically for the connected user and this path is appended to each search path to find the full Home Directory path.

  • example: /volume_1/eng_vol/

  • maxLength: 256

  • minLength: 1

  • Introduced in: 9.6

  • x-nullable: true

show_previous_versions

boolean

Specifies that the previous version can be viewed and restored from the client.

show_snapshot

boolean

Specifies whether or not the Snapshot copies can be viewed and traversed by clients.

svm

svm

SVM, applies only to SVM-scoped objects.

unix_symlink

string

Controls the access of UNIX symbolic links to CIFS clients. The supported values are:

  • local - Enables only local symbolic links which is within the same CIFS share.

  • widelink - Enables both local symlinks and widelinks.

  • disable - Disables local symlinks and widelinks.

volume

volume

vscan_profile

string

Vscan File-Operations Profile The supported values are:

  • no_scan - Virus scans are never triggered for accesses to this share.

  • standard - Virus scans can be triggered by open, close, and rename operations.

  • strict - Virus scans can be triggered by open, read, close, and rename operations.

  • writes_only - Virus scans can be triggered only when a file that has been modified is closed.

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

returned_error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.