SMB/shares: POST

Creates a new SMB share.

Availability

Available on all IBM Storage Scale editions.

Description

The POST smb/shares request creates a new SMB share. For more information about the fields in the data structures that are returned, see mmsmb command.

Request URL

https://<IP address or host name of API server>:<port>/scalemgmt/v2/smb/shares/shareName/scalemgmt/v2/smb/shares

where

smb/shares: Specifies SMB share as the target. Required.

Request headers

Accept: application/json

Request data

The following list of attributes are available in the response data:


{        "shareName": "ShareName"
         "path": "Path",      
         "smbOptions"
          {
         "browseable":""Browseable"
         "serversmbEncrypt": "{auto | default | mandatory | disabled}"
         "adminUsers": "Users"
         "comment": "Comments"
         "cscPolicy": "Client-side caching policy"
         "fileIdAlgorithm": "fsname | hostname | fsnamenodirs | 
    fsnamenorootdir"
         "gpfsLeases": "{yes | no}"
         "gpfsRecalls": "{yes | no}"
         "gpfsShareModes,": "{yes | no}"
         "gpfsSyncIo": "{yes | no}"
         "hideUnreadable": "{yes | no}"
         "opLocks": "{yes | no}"
         "posixLocking": "{yes | no}"
         "readOnly": "{yes | no}"
         "syncOpsOnClose": "{yes | no}"
         "hideDotFiles": "yes | no"
         "forceUser": " User name "
         "forceGroup": " Group name "
         "hostsAllow": " Client system name "
         "hostsDeny": " Client system name" }
}

The details of the parameters are given in the following list:

config":

Configuration details of SMB share.

"shareName": "String": Name of the SMB share.
"filesystemName": "String": The file system to which the SMB share belongs.
"filesetName": "String": The fileset to which the SMB share belongs.
"path": "String": The path for which SMB share is created.

"smbOptions":

An array of information about SMB shares addresses. The array contains elements that describe the SMB shares. For more information about the fields in this structure, see the links at the end of this topic.

"smbOptions":

"browseable":""Browseable": If the value is set as yes, the export is shown in the Windows Explorer browser while browsing the file server.
"serversmbEncrypt": "{auto | default | mandatory | disabled}": This option controls whether the remote client is allowed or required to use server SMB encryption. This option controls whether the remote client is allowed or required to use server SMB encryption.
"adminUsers": "Users": Using this option, administrative users can be defined in the format of admin users=user1;user2, ..usern. The users must be domain users.
"comment": "Comments": User-defined text.
"cscPolicy": "{manual | disable | documents | programs}": The client-side caching policy specifies how the clients that are capable of offline caching caches the files in the share.
"fileIdAlgorithm": "{fsname | hostname | fsnamenodirs | fsnamenorootdir}": This option allows to control the level of enforced data integrity. If the data integrity is ensured on the application level, it can be beneficial in cluster environments to reduce the level of enforced integrity for performance reasons.
"gpfsLeases": "yes | no": These are cross protocol oplocks (opportunistic locks). That is, an SMB client can lock a file that provides the user improved performance while reading or writing to the file because no other user read or write to this file. If the value is set as yes, clients accessing the file over the other protocols can break the lock of an SMB client and the user gets informed when another user is accessing the same file at the same time.
"gpfsRecalls": "{yes | no}": If the value is set as yes, files that are migrated from disk recalled on access. If recalls = no, files are not recalled on access and the client receives.
"gpfsShareModes": "{yes | no}": An application can set share modes. If you set gpfs:sharemodes = yes, the share modes that are specified by the application is respected by all protocols and not only by the SMB protocol. If you set gpfs:sharemodes = no, then the share modes that are specified by the application is only respected by the SMB protocol.
"gpfsSyncIo": "{yes | no}": If the value is set as yes, the files in an export for which the setting is enabled, are opened with the OSYNC flag. Accessing a file is faster if gpfs:syncio is set to yes. Performance for certain workloads can be improved when SMB accesses the file with the OSYNC flag set. For example, updating only small blocks in a large file as observed with database applications. The underlying GPFS behavior is then changed to not read a complete block, if there is only a small update to it.
"hideUnreadable": "{yes | no}": If the value is set as yes, all files and directories that the user has no permission to read is hidden from directory listings in the export. The hideunreadable=yes option is also known as access-based enumeration. When users are listing (enumerating) the directories and files within the export, they see only the files and directories that they have read access to.
"opLocks": "{yes | no}": If the value is set as yes, a client might request an opportunistic lock (oplock) from an SMB server when it opens a file. If the server grants the request, the client can cache large chunks of the file without informing the server what it is doing with the cached chunks until the task is completed. Caching large chunks of a file saves a lot of network I/O round-trip time and enhances performance.
"posixLocking": "{yes | no}": If the value is set as yes, it is tested if a byte−range (fcntl) lock is already present on the requested portion of the file before granting a byte−range lock to an SMB client. For improved performance on SMB−only shares this option can be disabled. Disabling locking on cross−protocol shares can result in data integrity issues when clients concurrently set locks on a file through multiple protocols, for example, SMB and NFS.
"readOnly": "{yes | no}": If the value is set as yes, files cannot be modified or created on this export independent of the ACLs.
"syncOpsOnClose": "{yes | no}": This option ensures that the file system synchronizes data to the disk each time a file is closed after writing. The written data is flushed to the disk.
"hideDotFiles": "{yes | no}": If the value is set to yes, files starting with "." are hidden.
"forceUser": "User name": The UNIX user name that is assigned as the default user for all users connecting to this SMB share service. This option is useful for sharing files. You must use this option carefully as using it incorrectly might cause security problems.
"forceGroup": "Group name": The UNIX group name that is assigned as the default primary group for all the users connecting to this SMB share service. This is useful for sharing files by ensuring that all access to files on the service uses the named group for their permissions check.
"hostsAllow" :"Client system name": The names of the client systems that have permission to access shares on the Samba server. The names are written as a comma (-) or space (-) separated list of system host names or their IP addresses.
"hostsDeny" :"Client system name": The names of the client systems that do not have permission to access shares on the Samba server. The names are written as a comma (-) or space (-) separated list of system host names or their IP addresses.

Response data

{
    "status": {
      "code":ReturnCode",
      "message":"ReturnMessage"
   },
   jobs: [
      {
         "result":"", 
           { 
             "commands":"String",
             "progress":"String,
             "exitCode":"Exit code",
             "stderr":"Error",
             "stdout":"String",
           },
         "request":" ",
           {
             "type":"{GET | POST | PUT | DELETE}",
             "url":"URL",
             "data":""",
           }
         "jobId":"ID",
         "submitted":"Time",
         "completed":Time",
         "status":"Job status",
         }   
        ],
   }

For more information about the fields in the following data structures, see the links at the end of this topic.

"status":

Return status.

"message": "ReturnMessage",: The return message.
"code": ReturnCode: The return code.

"jobs":

An array of elements that describe jobs. Each element describes one job.

"result"

"commands":"String': Array of commands that are run in this job.
"progress":"String': Progress information for the request.
"exitCode":"Exit code": Exit code of command. Zero is success, nonzero denotes failure.
"stderr":"Error": CLI messages from stderr.
"stdout":"String": CLI messages from stdout.

"request"

"type":"{GET | POST | PUT | DELETE}": HTTP request type.
"url":"URL": The URL through which the job is submitted.
"data":" ": Optional.

"jobId":"ID",: The unique ID of the job.
"submitted":"Time": The time at which the job was submitted.
"completed":Time": The time at which the job was completed.
"status":"RUNNING | COMPLETED | FAILED": Status of the job.

Examples

The following example creates a new SMB share.

Request data:

curl -k -u admin:admin001 -X POST --header 'content-type:application/json' --header 'accept:application/json' 
-d '{
  "shareName": "smbShare",
  "path": "/mnt/gpfs0/fset1",
  "smbOptions": {
    "browseable": "yes",
    "serversmbEncrypt": "auto",
    "adminUsers": "admin",
    "comment": "This is a comment",
    "cscPolicy": "manual",
    "fileIdAlgorithm": "fsname",
    "gpfsLeases": "yes",
    "gpfsRecalls": "yes",
    "gpfsShareModes": "yes",
    "gpfsSyncIo": "yes",
    "hideUnreadable": "yes",
    "opLocks": "yes",
    "posixLocking": "yes",
    "readOnly": "yes",
    "syncOpsOnClose": "yes",
    "hideDotFiles": "yes"
    "forceUser": "smbuser2"
    "forceGroup": "smbgroup2"
    "hostsAllow": "127.0.0.1"
    "hostsDeny": "192.0.0.6"
 }
}' "https://198.51.100.1:443/scalemgmt/v2/smb/shares"

Response data:

Note: In the JSON data that is returned, the return code indicates whether the command is successful. The response code 200 indicates that the command successfully retrieved the information. Error code 400 represents an invalid request and 500 represents internal server error.

{
  "status": {
    "code": "200",
    "message": "..."
  },
  "job": [
    {
      "result": {},
      "request": {
        "type": "POST",
        "url": "/scalemgmt/v2/smb/shares",
        "data": "{
            "shareName": "smbShare",
            "path": "/mnt/gpfs0/fset1",
            "smbOptions": {
            "browseable": "yes",
            "serversmbEncrypt": "auto",
            "adminUsers": "admin",
            "comment": "This is a comment",
            "cscPolicy": "manual",
            "fileIdAlgorithm": "fsname",
            "gpfsLeases": "yes",
            "gpfsRecalls": "yes",
            "gpfsShareModes": "yes",
            "gpfsSyncIo": "yes",
            "hideUnreadable": "yes",
            "opLocks": "yes",
            "posixLocking": "yes",
            "readOnly": "yes",
            "syncOpsOnClose": "yes",
            "hideDotFiles": "yes"
            "forceUser": "smbuser2"
            "forceGroup": "smbgroup2"
            "hostsAllow": "127.0.0.1"
            "hostsDeny": "192.0.0.6"
        },
      "jobId": "12345",
      "submitted": "2016-11-14 10.35.56",
      "completed": "2016-11-14 10.35.56",
      "status": "COMPLETED"
    }
  ]
}