mmsmb command

Availability

Available on all IBM Storage 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.

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 server 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 anymore 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.

Default: admin users =

Example: admin users = win-dom\jason

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 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.

fsname ensures data integrity in the entire cluster by managing concurrent access to files and directories cluster-wide.

The fsname_norootdir is the default value that disables synchronization of directory locks for the root directory of the specified export only and keeps locking enabled 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 keeps locking enabled for files.

The hostname value completely disables cross−node locking for both directories and files on the selected share.

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.

force user

This option specifies a 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 can cause security problems.

This user name only gets used after a connection is established. Thus, clients still need to connect as a valid user and enter a valid password. Once connected, all file operations are performed as the forced user, no matter what username the client connected as.

mmsmb export change myShareName --option "force user"="<valid name>"

force group

This option specifies a 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. Thus, by assigning permissions for this group to the files and directories within this service the Samba administrator can restrict or allow sharing of these files.

In Samba 2.0.5 and later releases, this parameter has following extended functionality:

• If the group name listed here has a plus (+) character added to it then the current user that accesses the share only has the primary group default assigned to this group if they are already assigned as a member of that group.
• The preceding change allows an administrator to decide that only users who are already in a particular group creates files with group ownership set to that group. This gives a finer granularity of ownership assignment. For example, the setting force group = +sys means that only users who are already in group sys has their default primary group that is assigned to sys when accessing this Samba share. All other users retain their ordinary primary group.

If the force user parameter is also set, the group that is specified in force group overrides the primary group set in the force user.

mmsmb export change  myShareName --option "force group"="<valid name>"

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 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.

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.

Warning: Enabling this option has a negative impact on directory listing performance, especially for large directories as the ACLs for all directory entries have to be read and evaluated. This option is disabled by default.

hosts allow

The hosts allow option specifies the clients that have permission to access shares on the Samba server, written as a comma (-) or space (-) separated lists of IP addresses.

Important: Passing hostnames as arguments is not yet supported.

You can specify any of the following formats for this option:

• IP addresses, such as 130.63.9.252. It allows access control of shares on the ip-address level. To allow only specific hosts to access a share, list the hosts, separated by comma's. Such as hosts allow = 192.168.1.5, 192.168.1.40
• Netgroups, which start with an at sign (@), such as @printerhosts are usually available only on systems running NIS or NIS plus (+). If netgroups are supported on your system, there should be a netgroups manual page that describes them in more detail.
• Subnets, which end with a dot (.). For example, 130.63.9., means all the systems whose IP addresses begin with 130.63.9.
  • Allowing entire subnets is done by ending the range with a dot (.)

    hosts allow = 192.168.1.

  • Subnet masks can be added in the classical way.

    hosts allow = 10.0.0.0/255.0.0.0

  • You can also allow an entire subnet with exceptions.

    
    Default: "no default"
    Allowable values: any // ips or list of ips
    Example: hosts allow = 10. except 10.0.0.12

• The keyword ALL, which allows any client access.
• The keyword EXCEPT followed by one or more names, IP addresses, domain names, netgroups, or subnets. For example, you can specify that Samba allow all hosts except those on the 192.168.110 subnet with hosts allow = ALL EXCEPT 192.168.110. (ensure to include the trailing dot).

Using the ALL keyword by itself is not a good idea because it means that crackers on any network can access your Samba server.

Other than that, there is no default value for the hosts allow configuration option. The default course of action in the event that neither the hosts allow or hosts deny option is specified in smb.conf is to allow access from all the sources.

Tip: If you specify hosts allow in the [global] section, that definition overrides any hosts allow lines in the share definitions. This is the opposite of the usual behavior, which is for parameters set in share definitions to override default values set in the [global] section

mmsmb export change myShare --option "hosts allow"=<ip / list of ips>

hosts deny

The hosts deny option specifies client systems that do not have permission to access a share, written as a comma (-) or space (-) separated list of IP addresses.

Important: Passing hostnames as arguments is not yet supported.

For example, to restrict access to the server from everywhere but for example.com, you can write:

hosts deny = ALL EXCEPT .example.com

There is no default value for the hosts deny configuration option, although the default course of action in the event that neither option is specified is to allow access from all the sources. Also, if you specify this option in the [global] section of the configuration file, it overrides any hosts deny options defined in shares. If you wish to deny access to specific shares, delete both the hosts allow and hosts deny options from the [global] section of the configuration file.

The hosts deny parameter is the logical counterpart of the previous. The syntax is the same as for hosts allow.

Default: "no default"
    Allowable values: any // ips or list of ips
    Example: hosts deny = 192.168.1.55, 192.168.1.56

mmsmb export change myShare --option "hosts deny"=<ip / list of ips>

Note:

• Never include the loopback address (localhost at IP address 127.0.0.1) in the hosts deny list. The smbpasswd program needs to connect through the loopback address to the Samba server as a client to change a user's encrypted password. If the loopback address is disabled, the locally generated packets requesting the change of the encrypted password will be discarded by Samba.
• In addition, both local browsing propagation and some functions of SWAT require access to the Samba server through the loopback address and will not work correctly if this address is disabled.

min domain uid(G)

The minimum domain uid (G) specifies the minimum uid allowed when mapping a local account to a domain account. This option interacts with the configured idmap ranges!

Default: min domain uid = 1000 //by default no UNIX uid below this value is accepted

Allowable values: any //valid lowest uid of a user accessing SMB

Example usage:

mmsmb config change --option "min domain uid = 1000"

To lists the added configuration, issue the following command:

mmsmb config list |grep "min domain uid"

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, 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.

server 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 server 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.

Default: "syncops:onclose = no"

Allowable values: yes, no

Example: "syncops:onclose = yes"

Warning: Enabling this option can have a negative performance impact on workloads creating many files from an 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 Storage 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.

Here, "msdfs proxy" needs a value to be assigned, which is the list of proxy shares. The syntax for this list is,

\<smbserver1>\<someshare>[,\<smbserver2>\<someshare>,...]

wide links

The wide links parameter controls whether or not links in the UNIX file system can be followed by the server. Links that point to the areas within the directory tree exported by the server are always allowed. The parameter controls access only to the areas that are outside the directory tree being exported.

Wide links option usage example:

mmsmb export change SMBExport [--option wide links=yes]

Note: Turning the wide links parameter 'ON' when UNIX extensions are enabled allows UNIX clients to create symbolic links on the share that can point to the files or directories outside restricted path exported by the share definition. This can cause access to areas outside of the share. Due to this problem, this parameter gets automatically disabled (with a message in the log file) if the UNIX extensions option is 'ON'. See the parameter allow insecure wide links if you wish to change this coupling between the two parameters. The default value of wide links is 'no'. For example, wide links = no.

server signing

The server signing parameter controls whether the client is allowed or required to use signing. Possible values are default, auto, mandatory, and disabled. The default and auto options exist for compatibility because these options do not mandate signing.

If this parameter is set to mandatory, SMB1 signing is required. If this parameter is set to disabled, SMB signing is not offered.

For the SMB2 protocol, you cannot disable signing. Where SMB2 is negotiated, if this parameter is set to disabled, the parameter value is auto. If you set the parameter value to mandatory, signing into the server becomes mandatory. This is default for IBM Storage Scale 5.2.1 and higher.

Important: By default, server signing is set to mandatory.

Default: server signing = mandatory

Allowable values: mandatory, default, auto, and disabled

Example: "server signing = auto"

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. 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.

server 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 server smb encrypt = disabled on the share and server 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).

Mandatory arguments are:

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

Examples:

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 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.

See also

Location