mmsmb command

Administers SMB shares, export ACLs, and global configuration.

Synopsis

mmsmb export list [ListofSMBExports ][ -Y ][ --option Arg ][ --export-regex Arg ]
[ --header N ][ --all ][ --key-info Arg]

mmsmb export add SMBExport Path [--option SMBOption=Value | --key-info SMBOption]

mmsmb export change SMBExport [--option SMBOption=Value | --remove SMBOption | --key-info SMBOption]

mmsmb export remove SMBExport [--force]

mmsmb config list [ListofSMBOptions | -Y | --supported | --header N | --key-info SMBOption]

mmsmb config change [--option SMBOption=Value | --remove SMBOption | --key-info SMBOption]

mmsmb exportacl getid { Name | --user UserName | --group GroupName
| --system SystemName }

mmsmb exportacl list { [ExportName] | [ExportName --viewsddl] }

mmsmb exportacl add ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } --access Access --permissions Permissions [--force]

mmsmb exportacl change ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } --access Access --permissions Permissions

mmsmb exportacl remove ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID }  [--access Access ][--permissions Permissions ]

mmsmb exportacl replace ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } --access Access--permissions Permissions [--force]

mmsmb exportacl delete ExportName  [--force]

Note: For mmsmb export, you can specify −−option −−remove multiple times but you cannot specify both of these options simultaneously.

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher.

The protocol functions provided in this command, or any similar command, are generally referred to as CES (Cluster Export Services). For example, protocol node and CES node are functionally equivalent terms.

Description

Use the mmsmb command to administer SMB shares and global configuration.

Using the mmsmb export command, you can do the following tasks:

Create the specified SMB share. The mmsmb export add command creates the specified export for the specified path. Any supported SMB option can be specified by repeating --option. Also the substitution values %D for the domain, %U for session user name and %G for the primary group of %U are supported as part of the specified path. The % character is not allowed in any other context. If the export exists but the path does not exist or if it is not inside the GPFS™ file system, the command returns with an error. When one or more substitution variables are used, only the sub-path to the first substitution variable is checked. If authentication on the cluster is not enabled, this command will terminate with an error.
Change the specified SMB share using the mmsmb export change command.
Delete an SMB share using the mmsmb export remove command. Existing connections to the deleted SMB share will be disconnected. This can result in data loss for files being currently open on the affected connections.
List the SMB shares by using the mmsmb export list command. The command displays the configuration of options for each SMB share. If no specific options are specified, the command displays all SMB shares with the SMB options browseable; guest ok; smb encrypt as a table. Each row represents an SMB share and each column represents an SMB option.

Using the mmsmb config command, you can do the following tasks:

Change, add or remove the specified SMB option for the SMB configuration. Use the mmsmb config change command to change the global configuration.
List the global configuration of SMB shares. Use the mmsmb config list command to display the global configuration options of SMB shares. If no specific options are specified, the command displays all SMB option-value pairs.

Using the mmsmb exportacl command, you can do the following tasks:

Retrieve the ID of the specified user/group/system.
List, change, add, remove, replace and delete the ACL associated with an export.
The add option has two mandatory arguments: --access and --permissions.

Parameters

mmsmb export

list

Lists the SMB shares.

ListofSMBExports

Specifies the list of SMB shares that needs to be listed as blank separated strings.

--option arg

arg {key | all | unsupported}

key: Specifies only the supported SMB option to be listed.
all: Displays all used SMB options.
unsupported: Detects and displays all SMB shares with unsupported SMB options. The path of all unsupported options are listed for each SMB share.

--export-regexarg

arg is a regular expression against which the exportnames are matched. Only matching exports are shown. If this option is not specified and if ListofSMBExports are also not specified, all existing exports are displayed.

--all

Displays all defined SMB options. Similar to --option all.

add

Creates the specified SMB share on a GPFS file system with NFSv4 ACLs enforced. You can verify whether your GPFS files system has been configured correctly by using the mmlsfs command. For example, mmlsfs gpfs0 -k.

path: Specifies the path of the SMB share that needs to be added.
--option SMBoption=value: Specifies the SMB option for the SMB protocol. If it is not a supported SMB option or the value is not allowable for this SMB option, the command terminates with an error. If this option is not specified, the default options: guest ok = no and smb encrypt = auto are set.

change

Modifies the specified SMB share.

--option SMBOption=value: Specifies the SMB option for the SMB protocol. If the SMB option is not configured for the specified export, it will be added with the specified value. If the SMB option is not supported or the value is not allowable for this SMB option the command terminates with an error. If no value is specified, the specified SMB option is set to default by removing the current setting from the configuration.
--remove SMBOption: Specifies the SMB option that is to be removed. If the SMB option is supported it will be removed from the specified export. The default value becomes active. If the SMB option is not supported, the command terminates with an error.

remove

Deletes the specified SMB share.

--force: Suppresses confirmation questions.

SMBExport

Specifies the SMB share that needs to be listed.

List of supported SMB options for the mmsmb export {list | add | change | remove} command:

admin users: Using this option, administrative users can be defined in the format of admin users=user1;user2;..;usern. The users must be domain users. Use of the parameter is not recommended for permanent use, files/directories created by the defined admin user will be owned by root and not by the user that had connected.
browseable: If the value is set as yes, the export is shown in the Windows Explorer browser when browsing the file server. By default, this option is enabled.
comment: Description of the export.
csc policy: csc policy stands for client−side caching policy, and specifies how clients that are capable of offline caching cache the files in the share. The valid values are: manual and disable. Setting csc profile = disable disables offline caching. For example, this can be used for shares containing roaming profiles. By default, this option is set to the value manual.
fileid:algorithm: 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.; fsname is the default option and ensures data integrity in the entire cluster by managing concurrent access to files and directories cluster-wide.; The fsname_norootdir value disables synchronization of directory locks for the root directory of the specified export, but will keep lock fileid:algorithm for all files and directories within and underneath the share root.; The fsname_nodirs value disables synchronization of directory locks across the cluster nodes, but will leave lock fileid:algorithm enabled for files.; The hostname value completely disables cross−node lock fileid:algorithm for both directories and files.; By default, the fsname value is set that enables cross−node lock fileid:algorithm for both directories and files.; Note: Data integrity is ensured if an application does not use multiple processes to access the data at the same time, for example, reading of file content does not happen while another process is still writing to the file. Without locking, the consistency of files is no longer guaranteed on protocol level. If data integrity is not ensured on application level this can lead to data corruption. For example, if two processes modify the same file in parallel, assuming that they have exclusive access.
gpfs:leases: gpfs:leases are cross protocol oplocks (opportunistic locks), that means 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 a SMB client and the user gets informed when another user is accessing the same file at the same time.
gpfs:recalls: If the value is set as yes files that have been migrated from disk will be recalled on access. By default, this is enabled. If recalls = no files will not be recalled on access and the client will receive ACCESS_DENIED message.
gpfs:sharemodes: An application can set share modes. If you set gpfs:sharemodes = yes, using the mmsmb export change SMBexport --option "gpfs:sharemodes = yes" the sharemodes specified by the application will be respected by all protocols and not only by the SMB protocol. If you set gpfs:sharemodes = no the sharemodes specified by the application will only be respected by the SMB protocol. For example, the NFS protocol will ignore the sharemode set by the application.; The application can set the following sharemodes: SHARE_READ or SHARE_WRITE or SHARE_READ and SHARE_WRITE or no sharemodes.
gpfs:syncio: If the value is set as yes, it specifies the files in an export, for which the setting is enabled, are opened with the O_SYNC 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 O_SYNC 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. By default, this option is disabled.
guest ok: By default, this parameter is set to no.
hide unreadable: 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 because when a user is listing (enumerating) the directories and files within the export, they only see the files and directories that they have read access to. By default, this option is disabled.; Note: If the value is set as yes, there is a negative impact to the read and write performance of data in the export.
oplocks: If the value is set as yes, a client may 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. By default, this option is enabled.
Warning: While oplocks can enhance performance, they can also contribute to data loss in case of SMB connection breaks/timeouts. To avoid the loss of data in case of an interface node failure or storage timeout, you might want to disable oplocks.; Opportunistic locking allows a client to notify the SMB server that it will be the exclusive writer of the file. It also notifies the SMB server that it will cache its changes to that file on its own system and not on the SMB server to speed up file access for that client. When the SMB server is notified about a file being opportunistically locked by a client, it marks its version of the file as having an opportunistic lock and waits for the client to complete work on the file. The client has to send the final changes back to the SMB server for synchronization. If a second client requests access to that file before the first client has finished working on it, the SMB server can send an oplock break request to the first client. This request informs the client to stop caching its changes and return the current state of the file to the server so that the interrupting client can use it. An opportunistic lock, however, is not a replacement for a standard deny-mode lock. There are many use cases when the interrupting process to be granted an oplock break only to discover that the original process also has a deny-mode lock on the file.
posix locking: If the value is set as yes, it will be 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 via multiple protocols, for example, SMB and NFS.
read only: If the value is set as yes, files cannot be modified or created on this export independent of the ACLs. By default, the value is no.
smb encrypt: This option controls whether the remote client is allowed or required to use SMB encryption. Possible values are auto, mandatory, and disabled. This is set when the export is created with default value. Clients may chose to encrypt the entire session, not just traffic to a specific export. The server would return access denied message to all non−encrypted requests on such an export. Selecting encrypted traffic reduces throughput as smaller packet sizes must be used as well as the overhead of encrypting and signing all the data. If SMB encryption is selected, Windows style SMB signing is no longer necessary, as the GSSAPI flags use select both signing and sealing of the data. When set to auto , SMB encryption is offered, but not enforced. When set to mandatory, SMB encryption is required and if set to disabled, SMB encryption can not be negotiated.
syncops:onclose: 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. By default, this option is enabled.
Warning: Disabling this option increases the risk of data loss in case of a node failure.

mmsmb config

list

Lists the global configuration options of SMB shares.

ListofSMBOptions: Specifies the list of SMB options that needs to be listed.
--supported: Displays all changeable SMB options and their values.

change

Modifies the global configuration options of SMB shares.

--option SMBOption=value: Sets the value of the specified SMB option. If no value is given, the SMB option is removed.; Specifies the SMB option for the SMB protocol. If the SMB option is not configured for global configuration, it will be added with the specified value. If no value is specified, the specified SMB option is set to default and removed from the global configuration. If the SMB option is not supported or the value is not allowable for the SMB option, the command terminates with an error.
--remove SMBOption: Specifies the SMB option that is to be removed. If the SMB option is supported it will be removed from the global configuration. The default value becomes active. If the SMB option is not supported, the command terminates with an error.

List of supported SMB options by the mmsmb config {list | change} command:

gpfs:dfreequota

gpfs:dfreequota stands for disk Free Quota. If the value is set to yes the free space and size reported to a SMB client for a share will be adjusted according to the applicable quotas. The applicable quotas are the quota of the user requesting this information, the quota of the user's primary group and the quota of the fileset containing the export.

restrict anonymous

The setting of this parameter determines whether access to information is allowed or restricted for anonymous users. The options are:

restrict anonymous = 2: anonymous users are restricted from accessing information.

restrict anonymous = 0: anonymous users are allowed to access information. This is the default setting.

restrict anonymous = 1: is not supported

server string

server string stands for Server Description. It specifies the server description for SMB protocol. Server description with special characters must be provided in single quotes.

mmsmb exportacl

getid

Retrieve the ID of the specified user/group/system.

mmsmb exportacl getid myUser
mmsmb exportacl getid --user myUser
mmsmb exportacl getid --group myGroup
mmsmb exportacl getid --system mySystem

list

List can only take viewing options.

mmsmb exportacl list myExport                      Show the export ACL for this exportname
mmsmb exportacl list                               Show all the export ACLs
mmsmb exportacl list myExport --viewsddl           Show the export ACL for this exportname in sddl format.

add

Add will add a new permission to the export ACL. It will include adding a user, group or system. The options are:

{User/group/system name} If you do not specify the type of name, the system will prioritize in this order:
--user
--group
--system, or
--SID (this can be the SID for a user, group or system).

Mandatory arguments are:

--access: ALLOWED or DENIED
--permissions: One of FULL, CHANGE, or READ or any combination of RWXDPO.

Examples:

mmsmb exportacl add myExport0 myUser --access ALLOWED --permissions FULL
mmsmb exportacl add myExport1 --user user01 --access ALLOWED --permissions RWO
mmsmb exportacl add myExport2 --group   group01 --access DENIED -- permissions RWXDP

change

Change will update the specified ACE in an export ACL. The options are:

{User/group/system name} If you do not specify the type of name, the system will prioritize in this order:
--user
--group
--system
--SID (This can be the SID for a user, group or system).

Mandatory arguments are:

--access: ALLOWED or DENIED
--permissions: One of FULL, CHANGE, or READ or any combination of RWXDPO.

Examples:

mmsmb exportacl change myExport --user myUser --access ALLOWED --permissions RWX
mmsmb exportacl change myExport --group allUsers --access ALLOWED --permissions R

remove

Remove will remove the ACE for the specified user/group/system from the ACL.

The user, group or system will be removed automatically for a specified name.

In the event that the system is unable to locate an ACE within the export ACL that it can remove the permissions for as instructed, an error will be issued to the user informing them of this.

The options are:

{User/group/system name} If you do not specify the type of name, the system will prioritize in this order:
--user
--group
--system
--SID (This can be the SID for a user, group or system).

Optional arguments are:

--access: ALLOWED or DENIED
--permissions: One of FULL, CHANGE, or READ or any combination of RWXDPO.

Examples:

mmsmb exportacl remove myExport01 UserName --access ALLOWED --permissions CHANGE
mmsmb exportacl remove myExport02 GroupName --access DENIED --permissions READ
mmsmb exportacl remove myExport03 UserName

replace

The replace command replaces all the permissions in a export ACL with those indicated in its ACE specification. It is therefore a potentially destructive command and will include a confirmation. This confirmation can be overridden with the --force command. The options are:

{User/group/system name} If you do not specify the type of name, the system will prioritize in this order:
--user
--group
--system
--SID (This can be the SID for a user, group or system)
--force.

Mandatory arguments are:

--access: ALLOWED or DENIED
--permissions: One of FULL, CHANGE, or READ or any combination of RWXDPO.

Examples:

mmsmb exportacl replace myExport01 --user user01 --access ALLOWED --permissions FULL
mmsmb exportacl replace myExport02 --group group01 --access ALLOWED --permissions READ --force
mmsmb exportacl replace myUser --access ALLOWED --permissions FULL

delete

The Delete command will remove an entire export ACL. It therefore does not require a system, id or user identified as they are not appropriate in this case. All it needs is the name of an export for which the export ACL will be deleted.

Delete will include a confirmation. This can be overridden using the --force parameter.

Examples:

mmsmb exportacl delete myExport01
mmsmb exportacl delete myExport02 --force

Parameters common for both mmsmb export and mmsmb config commands

-Y

Displays command output in machine-readable format.

Note: The output includes colon ":" as a field separator. If the values in the output include a ":", then it is replaced by "%3A". If the values include a "%". then it is replaced by a "%25".

--header n

Repeats the output table header every n lines for a table that is spread over multiple pages. The value n can be of any integer value.

--key-info arg

Displays the supported SMB options and their possible values.

arg SMBoption | supported

SMBoption: Specifies the SMB option.
supported: Displays descriptions for all the supported SMB options.

Exit status

0: Successful completion.
nonzero: A failure has occurred.

Security

You must have root authority to run the mmsmb command.

The node on which the command is issued must be able to execute remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.