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]
or
mmsmb export add SMBExport Path [--option SMBOption=Value | --key-info SMBOption]
or
mmsmb export change SMBExport [--option SMBOption=Value | --remove SMBOption
|--key-info SMBOption]
or
mmsmb export remove SMBExport [--force]
or
mmsmb config list [ListofSMBOptions | -Y | --supported | --header N
| --key-info SMBOption]
or
mmsmb config change {--option SMBOption=Value | --remove SMBOption
|--key-info SMBOption | --vfs-fruit-enable}
or
mmsmb exportacl getid { Name | --user UserName | --group GroupName
| --system SystemName }
or
mmsmb exportacl list { [ExportName] | [ExportName --viewsddl] }[--viewsids]
or
mmsmb exportacl add ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } [--viewsids] --access Access --permissions
Permissions [--force]
or
mmsmb exportacl change ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } [--viewsids] --access Access --permissions Permissions
or
mmsmb exportacl remove ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } [--viewsids] [--access Access ]
[--permissions Permissions ]
or
mmsmb exportacl replace ExportName { Name | --user UserName | --group GroupName
| --system SystemName | --SID SID } --access Access--permissions Permissions [--viewsids]
[--force]
or
mmsmb exportacl delete ExportName [--viewsids] [--force]
Availability
Available on all IBM Spectrum Scale editions.
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.
- 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.
- 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.
- Enable SMB fruit support
- 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 {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-regex arg
- 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.
Note: You cannot change the "guest ok" option by using the mmsmb command as it is an unsupported option. - 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.
- --vfs-fruit-enable
- Enables the vfs_fruit module and alternate data streams support for better support of Mac OS SMB2 clients. Setting this option requires the SMB service to be down on all CES nodes. Disabling it requires the help of IBM® support as the Apple file meta-data that has been moved to extended attributes and would not be accessible any more unless restored back to files. For more information, see Support of vfs_fruit for the SMB protocol.
- 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
. This is a list of users who will be granted administrative privileges on the share. This means that they will do all file operations as the super user (root). You should use this option very carefully, as any user in this list will be able to do anything they like on the share, irrespective of file permissions. - 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. Settingcsc policy = 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.
- 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 oplock of an 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 themmsmb 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 setgpfs: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. - 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.
- hide unreadable
- If the value is set as yes, all files and directories that the user has
no permission to read are 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. - 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.
- 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, which is the default behavior. 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,
disabled, and desired. This is set when the
export is created with default value, which is auto. 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, the message
integrity is guaranteed so that signing is implicit. 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 cannot be negotiated. This setting controls SMB encryption setting for the individual SMB share. Supported values are:
- auto/default: This will enable negotiation of encryption but will not turn on data encryption globally.
- mandatory: This will enable SMB encryption and turn on data encryption
for this share. Clients that do not support encryption will be denied access to this SMB
share.Note: This requires the global mmsmb config smb encrypt setting to be either auto/default or mandatory.
- disabled: Disables the encryption feature for a specific SMB share.
- desired: Enables negotiation and turns on data encryption on sessions and share connections for those clients that support it.
- syncops:onclose
- This option ensures that the file system synchronizes data to the disk each time a file is closed after writing. The data written is flushed to the disk, but this can reduce performance for workloads writing many files. Enabling this option will decrease the risk of possible data loss in case of a node failure. This option is disabled by default. Enabling this should not be necessary, as data is flushed to disk periodically by the file system and also when requested from an application on a SMB client.
- hide dot files
- Setting this to "no" will remove hidden attributes for dot files in an SMB share so that those files become visible when you access that share.
- msdfs proxy
- This option enables the IBM Spectrum Scale customers to configure DFS redirects for SMB shares. If an SMB client attempts to connect to such a share, the client is redirected to one or multiple proxy shares by using the SMB-DFS protocol.
- 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.
- --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. This is the default setting.restrict anonymous = 0
: anonymous users are allowed to access information.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.
- smb encrypt
-
This setting controls the global SMB encryption setting that applies to each SMB connection. Supported values are:
- auto/default: This will enable negotiation of encryption but will not turn on data encryption globally.
- mandatory: This will enable negotiation and turn on data encryption for all SMB shares. Clients that do not support encryption will be denied access to the server.
- disabled: This will completely disable the encryption feature for all
connections.Note: With smb encrypt = disabled on the share and smb encrypt = mandatory in the global section, access will be denied for all clients.
- 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).
- --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).
- --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).
- --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.
- --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 the command output in a parseable format with a colon (:) as a field
delimiter. Each column is described by a header.Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.
- --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.
Examples
mmsmb config list
- Show descriptions of all the supported SMB configuration options.
The system displays output similar to this:mmsmb config list −−key−info supported
Supported smb options with allowed values: gpfs:dfreequota = yes, no restrict anonymous = 0, 2 server string = any
- List the SMB option that specifies whether anonymous access is
allowed or not.
The system displays output similar to this:mmsmb config list "gpfs:dfreequota"
SMB option value gpfs:dfreequota yes
- Display the SMB configuration options in a machine-readable format.
The system displays output similar to this:mmsmb config list -Y
add share command:aio read size:aio write size:aio_pthread%3Aaio open:async smb echo handler:auth methods:change notify:change share command:client NTLMv2 auth:ctdb locktime warn threshold:debug hires timestamp:delete share command:dfree cache time:disable netbios:disable spoolss:dmapi support:ea support:fileid%3Amapping:force unknown acl user:gencache%3Astabilize_count:gpfs%3Adfreequota:gpfs%3Ahsm:gpfs%3Aleases:gpfs%3Aprealloc:gpfs%3Asharemodes:
mmsmb config change
- Show descriptions of all the supported SMB configuration options.
The system displays output similar to this:mmsmb config change −−key−info supported
Supported smb options with allowed values: gpfs:dfreequota = yes, no restrict anonymous = 0, 2 server string = any
Note: The output of this command depends on the configuration options supported by the system. - Change an SMB configuration option.
mmsmb config change --option "restrict anonymous=0"
You can confirm the change by using this mmsmb config list "restrict anonymous" command.
- Remove an SMB configuration option.
The system displays output similar to this:mmsmb config change --remove "server string"
Warning: Unused options suppressed in display: server string
mmsmb export list
- To list all SMB options for export myExport, issue this
command:
The system displays output similar to this:mmsmb export list myExport −−option all
export path smb encrypt guest ok browseable myExport /gpfs/fs0/combo-1 auto no no
- To list SMB option csc policy for SMB share myexport and all
SMB shares starting with foo followed by any quantity of 1 and ending on 2 or 3,
issue this
command:
The system displays output similar to this:mmsmb export list −−option "csc policy" myexport −−export−regex "foo1*[23]$"
export path csc policy myExport /mnt/gpfs0/shared - - - foo11b23 /mnt/gpfs0/testExport/testSmbEncypt disable foo111b23 /mnt/gpfs0/testExport/testSmbEncypt documents
- To list all exports where unsupported SMB options are set, issue
this command:
The system displays output similar to this:mmsmb export list −−option unsupported
export path mangled names hasForbiddenOptions /mnt/gpfs0/shared yes
- To list the DFS redirect option setting for a share, issue this
command:
The system displays output similar to this:mmsmb export list redirect --option "msdfs proxy"
export path msdfs proxy redirect /ibm/gpfs0/redirect/ \cluster1\share
- To list all share options (including "msdfds proxy" setting), issue
this command:
The system displays output similar to this:mmsmb export list redirect --all
export path smb encrypt msdfs proxy guest ok comment browseable redirect /ibm/gpfs0/redirect/ auto \cluster1\share no redirect to /cluster1/share no
mmsmb export add
- To create an export myExport as default SMB share for path
/ibm/gpfs0/myFolder with default options, issue this
command:
The system displays output similar to this:mmsmb export add myExport "/ibm/gpfs0/myFolder"
mmsmb export add: The SMB export was created successfully.
- To add a new share and set "msdfs proxy" share option, issue this
command:
The system displays output similar to this:msmb export add redirect /ibm/gpfs0/redirect --option "msdfs proxy"="/cluster1/share"
mmsmb export add: The SMB export was created successfully.
mmsmb export change
- To change the SMB option oplocks to value yes for SMB
share myExport, issue this
command:
mmsmb export change myExport −−option "oplocks"="yes"
You can confirm the change by using this mmsmb export list --option "oplocks" myExport command. The system displays output similar to this:export path oplocks myExport /mnt/gpfs0/shared yes
- To remove the SMB option oplocks from SMB share
myExport, issue the following
commands:
You can confirm the change by using this mmsmb export list --option all myExport command.mmsmb export change myExport −−remove "oplocks"
- To change the "msdfs proxy" share option, issue this
command:
The system displays output similar to this:mmsmb export change redirect --option "msdfs proxy"="\cluster1\share"
mmsmb export change: The SMB export was changed successfully.
mmsmb export remove
- To delete the SMB share myExport with confirmation, issue this
command:
The system asks for confirmation, similar to this:mmsmb export remove myExport
Do you really want to perform the operation (yes/no - default no):
- To delete the SMB share myExport without
confirmation:
The system removes the SMB share without any confirmation.mmsmb export remove myExport −−force
See also
Location
/usr/lpp/mmfs/bin