SMB Protocol

SMB Protocol Properties

Each share has protocol-specific properties that define the behavior of different protocols for that share. These properties can be defined for each share or inherited from a share's project.

Table 4-58 SMB Protocol Properties

BUI Property	CLI Property	Property Type	Description
Share mode	`off` \| `rw` \| `ro`	Inherited	Specifies whether the share is available for reading only, for reading and writing, or neither. See table "SMB Share Mode Values (BUI and CLI)" in SMB Protocol Share Mode Exceptions.
Resource name	`resource_name`	Inherited	The name by which SMB clients refer to this share. Share mode exceptions can be specified for this resource. See table "SMB Share Mode Values (BUI and CLI)" in SMB Protocol Share Mode Exceptions.
Enable access-based enumeration	`abe`	Inherited	Specifies whether to perform access-based enumeration.
Enable guest access	`guestok`	Inherited	Specifies whether to grant guest access. This property is disabled by default.
Is a DFS namespace	`dfsroot`	Inherited	Specifies whether this share is provisioned as a standalone DFS namespace.
Client-side caching policy	`csc`	Inherited	Per-share configuration options provided to support client-side caching. For more information, see Client-side Caching Property.
Opportunistic locks policy	`oplocks`	Inherited	Specifies whether opportunistic locks are enabled at the share level. For more information, see Opportunistic Locks Property.
Enable continuous availability	`cont_avail`	Inherited	Specifies whether SMB3 clients can request persistent file handles for the share. When enabled, the appliance can store the state associated with a persistent file handle in stable, persistent storage. The state can be transparently restored in the event of a controller failure, such as a takeover and failback operation on clustered controllers. Continuously available SMB shares are not allowed to be shared over NFS or used on workloads such as Home Directory that have a very high number of opens/closes. Continuously available SMB shares are only recommended for enterprise applications that have limited number of opens/closes.
Encrypt data access	`encrypt`	Inherited	Specifies whether SMB3 encryption is enabled at the share level. When enabled, the SMB server requires clients to encrypt requests to access the share. This enforcement can be bypassed if the server allows unencrypted access. This property is disabled by default. For global-level SMB encryption properties, see `Encrypt data access` and `Reject unencrypted access` in SMB Service Properties.
Bypass traverse checking	`bypasstraverse`	Inherited	Specifies whether to bypass traverse checking for the share. This property is disabled by default. When bypass traverse is disabled, UNIX semantics are used: Always enforce the traversal permissions of folders when navigating an object on this share. When bypass traverse is enabled, Windows semantics are used: Access to an object on this share depends on the user's rights to that object, ignoring the traversal permissions of folders.

Client-side Caching Property

The client-side caching property (csc) controls whether files and programs from the share are cached on the local client for offline use when disconnected from the appliance.

BUI Value	CLI Value	Description
No caching	`none`	Disables client-side caching for the share. No files or programs from the share are available offline. This option blocks offline files on the client computers from making copies of the files and programs on the shared folder.
Manual caching	`manual`	Only specified files and programs are cached on the local client and available offline. This is the default option when you set up a shared folder. By using this option, no files or programs are available offline by default. You can control which files and programs to access when you are not connected to the network.
Automatic document caching	`documents`	All files accessed from the share are cached on the local client and available offline. Files are automatically reintegrated when the local client is online again. Programs accessed from the share are not available offline unless previously cached locally.
Automatic program caching	`programs`	All programs accessed from the share are cached on the local client and available offline. When online, the programs are run from the local client. Additionally, all files accessed from the share are cached on the local client and available offline. Files are automatically reintegrated when the local client is online again.

Opportunistic Locks Property

Opportunistic locks are a client-caching mechanism that facilitates local caching to reduce network traffic and improve performance. The property (oplocks) controls whether the server grants or denies opportunistic locks at the share level, and applies to both lease (SMB 2.1 and above) and legacy (SMB 2.0 and below) opportunistic locks.

The client requests an opportunistic lock on a file within a share, and that request is either granted or denied depending on the server configuration and the current state of the file. If the client attempts to access a file in a manner inconsistent with the opportunistic locks that have already been granted for that file, a conflict occurs. In such cases, the server initiates a process to break the existing opportunistic locks before proceeding with the conflicting operation.

Enabling opportunistic locks improves performance when files within a share are accessed by a single client. In some scenarios, however, such as when the same file is accessed simultaneously by multiple clients, it can introduce unnecessary overhead. Opportunistic locks can thus be enabled or disabled per share, instead of globally controlled, based on the expected pattern of workloads.

If an opportunistic locks property is not defined at the share level, the default is the global opportunistic locks property set at the service level. For more information, see Enable oplocks in section SMB Service Properties.

BUI Value	CLI Value	Description	Example
Enabled	`enabled`	Enables opportunistic locks for a share.	`set sharesmb="myshare,oplocks=enabled,abe=off,dfsroot=false"`
Disabled	`disabled`	Disables opportunistic locks for a share.	`set sharesmb="myshare,oplocks=disabled,abe=off,dfsroot=false"`
empty	--	The opportunistic locks property is neither enabled or disabled. Uses the global opportunistic locks property when the share-level property is not set.	`set sharesmb="myshare,abe=off,dfsroot=false"`

SMB Protocol Share Mode Exceptions

Exceptions to the global sharing mode may be defined for clients or collections of clients by setting client-specific share modes or exceptions. To restrict access to certain clients, set the global sharing mode to none and increasingly grant access to smaller and smaller groups. For example, you could create a share with the global sharing mode set to none, which denies access to all clients, and then grant read-only access to a subset of the clients. Further, you could grant read/write access to an even smaller subset of the clients and, finally, only trusted hosts might have read/write access.

Table 4-59 Client Types

Type	CLI Prefix	Description	Example
Host (FQDN)	`none`	A single client with an IP address that resolves to the specified fully qualified name.	`hostname.sf.example.com`
Netgroup	`%`	A netgroup name in LDAP that grants access to certain named clients. This client type can only be used in an exception if the `explicit_netgroups` property is set to `true` in the CLI, or Use new syntax for netgroups in share access lists is selected in the BUI.	`netgroup.sf.example.com`
DNS Domain	`.`	All clients with IP addresses that resolve to a fully qualified name ending in this suffix.	`sf.example.com`
IPv4 Subnet	`@`	All clients with IP addresses that are within the specified IPv4 subnet, expressed in CIDR notation.	`192.0.2.254/22`
IPv6 Subnet	`@`	All clients with IP addresses that are within the specified IPv6 subnet, expressed in CIDR notation.	`2001:db8:410:d43::/64`

For each client or collection of clients, you specify whether the client has read-only or read-write access to the share.

Managing netgroups - Netgroups can be used to control access for SMB exports. However, managing netgroups can be complex. Consider using IP subnet rules or DNS domain rules instead.

If netgroups are used, they will be resolved from NIS or LDAP, depending on which service is enabled. If LDAP is used, each netgroup must be located at the default location, ou=Netgroup,(Base DN), and must use the standard schema.

The username component of a netgroup entry typically has no effect on SMB; only the hostname is significant. Hostnames contained in netgroups must be canonical and, if resolved using DNS, fully qualified. That is, the SMB subsystem will attempt to verify that the IP address of the requesting client resolves to a canonical hostname that matches either the specified FQDN, or one of the members of one of the specified netgroups. This match must be exact, including any domain components; otherwise, the exception will not match and the next exception will be tried. For more information on hostname resolution, see DNS.

As of the 2013.1.0 software release, UNIX client users may belong to a maximum of 1024 groups without any performance degradation. Prior releases supported up to 16 groups per UNIX client user.

SMB Share Modes and Exception Options

In the CLI, all SMB share modes and exceptions are specified using a single options string for the sharesmb property. This string is a comma-separated list of values. It should begin with one of ro, rw, on, or off, as an analogue to the global share modes described for the BUI.

Table 4-60 SMB Share Mode Values (BUI and CLI)

BUI Share Mode Value	CLI Share Mode Value	Description	Example
None	`off`	Share mode is disabled.	`sharesmb=off`
	`on`	The share name is the dataset name and is available for reading and writing or reading only if the `rw` or `ro` SMB exceptions are defined. For all other clients, share mode is disabled.	`sharesmb="on,ro=sf.example.com"`
	`resource_name`	The share name is the resource name and is available for reading and writing or reading only if the `rw` or `ro` SMB exceptions are defined. For all other clients, share mode is disabled.	`sharesmb="myshare,ro=sf.example.com"`
Read/write	`on`	The share name is the dataset name and is available for reading and writing for all clients if there are no SMB exceptions.	`sharesmb=on`
	`rw`	The share name is the dataset name and is available for reading and writing for all clients except those for which the `ro` exception is defined.	`sharesmb=rw` or `sharesmb="rw,ro=sf.example.com"`
	`resource_name`	The share name is the resource name and is available for reading and writing for all clients if there are no SMB exceptions.	`sharesmb=myshare`
	`resource_name,rw`	The share name is the resource name and is available for reading and writing for all clients except those for which the `ro` exception is defined. SMB exceptions may or may not be defined.	`sharesmb="myshare,rw"` or `sharesmb="myshare,rw,ro=sf.example.com"`
Read only	`ro`	The share name is the dataset name and is available for reading only for all hosts except those for which the `rw` exception is defined.	`sharesmb="ro,rw=sf.example.com"`
Read only	`resource_name,ro`	The share name is the resource name and is available for reading only for all clients except those for which the `rw` exception is defined. SMB exceptions may or may not be defined.	`sharesmb="myshare,ro"` or `sharesmb="myshare,ro,rw=sf.example.com"`

The following example sets the share mode for all clients to read-only.

set sharesmb=ro

Additional SMB exceptions can be specified by appending text of the form option=collection, where option is either ro or rw. You cannot grant root access with SMB exceptions. The collection is specified by the prefix character from table 114, and either a DNS hostname/domain name or CIDR network number.

For example, to grant read-write access to all hosts in the sf.example.com domain:

set sharesmb="ro,rw=.sf.example.com"

This example grants read-only access to clients with the IP addresses 2001:db8:410:d43::/64 and 192.0.2.254/22:

set sharesmb="on,ro=@[2001:db8:410:d43::/64]:@192.0.2.254/22"

Netgroup names can be used anywhere an individual fully qualified hostname can be used. For example, you can permit read-write access to the engineering netgroup as follows:

set sharesmb="ro,rw=engineering"

Share-Level ACLs

A share-level access control list (ACL), when combined with the ACL of a file or directory in the share, determines the effective permissions for that file. By default, this ACL grants everyone full control. This ACL provides another layer of access control above the ACLs on files and allows for more sophisticated access control configurations. This property may only be set once the filesystem has been exported by configuring the SMB resource name. If the filesystem is not exported over the SMB protocol, setting the share-level ACL has no effect.

When access-based enumeration is enabled, clients may see directory entries for files which they cannot open. Directory entries are filtered only when the client has no access to that file. For example, if a client attempts to open a file for read/write access but the ACL grants only read access, that open request will fail but that file will still be included in the list of entries.

For more information about ACLs, see Access Control Lists for Filesystems.