SMB Protocol

Language:

This section contains the following topics:

For more information about the SMB protocol, use these topics:

For information about other supported protocols, see the following sections:

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. The following table shows SMB protocol properties and possible values.

Table 119 SMB Protocol Properties

Property	CLI Value(s)	Property Type	Description
Share mode	`off/on/rw/ro`	Inherited	Determines whether the share is available for reading only, for reading and writing, or neither. See SMB Protocol Share Mode Exceptions.
Resource name	`resource_name/off/on`	Inherited	Shows the name by which SMB clients refer to this share. The resource name `off` indicates no SMB client may access the share, and the resource name `on` indicates the share will be exported with the filesystem's name.
Enable access-based enumeration	`abe`	Inherited	Performs access-based enumeration when enabled.
Enable guest access	`guestok`	Inherited	Grants guest access when enabled. This property is disabled by default.
Is a DFS namespace	`dfsroot`	Inherited	Indicates whether this share is provisioned as a standalone DFS namespace.
Client-side caching policy	`csc`	Inherited	Indicates per-share configuration options provided to support client-side caching. For more information, see Client-side Caching Property.
Opportunistic locks policy	`oplocks`	Inherited	Enables or disables opportunistic locks at the share level. For more information, see Opportunistic Locks Property
Enable continuous availability	cont_avail	Inherited	When enabled, SMB3 clients can request persistent file handles for the share. This allows the appliance to 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.

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 120 Client Types

Type	CLI Prefix	Description	Example
Host(FQDN) or Netgroup	`none`	A single client whose IP address resolves to the specified fully qualified name, or a netgroup containing fully qualified names to which a client's IP address resolves.	caji.sf.example.com
DNS Domain	`.`	All clients whose IP addresses resolve to a fully qualified name ending in this suffix.	sf.example.com
IPv4 Subnet	@	All clients whose IP addresses are within the specified IPv4 subnet, expressed in CIDR notation.	192.0.2.254/22
IPv6 Subnet	@	All clients whose IP addresses 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 121 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, 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, 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.