Skip to main content
Version: 3024.10

SMB Features and Settings

Access Control Lists (ACLs) Storage​

In Windows environments, Access Control Lists (ACLs) define the permissions that users and groups have on files and directories. When a user creates a new file or directory, Windows assigns it a default set of permissions, which can then be modified to allow or deny access to specific users or groups.

When a user attempts to access a file or directory, Windows checks its ACL and the ACLs of parent directories to determine whether the user has the necessary permissions to perform the requested operation. If the required permissions are missing, access is denied.

In standard Windows environments, ACLs are stored as part of the NTFS file system.

Since Fusion SMB operates in a Linux environment, where the shared file system may not support ACLs natively, Fusion SMB offers multiple mechanisms to store Windows Access Control Lists (ACLs) regardless of the underlying file system. ACL storage mechanisms can be configured on a per-share basis.

Share Parameter ACL Storage Mechanism

Value Type: string

Value Format: <method>[,<method>,...]

  • Values are separated by ,.

  • A <method> can be one of the following:

    • xattr[:<variant>]: Store the ACLs in a dedicated extended attribute. Optional argument <variant> specifies the name of the extended attribute and the format used to save the ACLs:
      • raw: Use the self-relative security descriptor in Fusion SMB specific extended attribute user.tsmb.$sd (default).
      • v3: Use version 3 of the Samba extended attribute security.NTACL without duplication in POSIX ACL.
      • v4: Use version 4 of the Samba extended attribute security.NTACL without duplication in POSIX ACL.
    • native: Store the ACLs natively on the file system, if supported. Use this option if the underlying file system is NTFS, or another private VFS module that supports these attributes.
    • posix-acl[:map_full_control]: Attempt to convert Windows ACLs to POSIX ACLs with best-effort mapping. If map_full_control is specified, the rwx permission bits are mapped to Full Control.
    • xattr, posix-acl : Specifies an ordered preference between the two backends, so xattr is preferred over posix-acl. The granularity of the two backends also plays a role since ACLs saved in extended attributes (xattr) will often be more granular than a best effort mapping of Windows ACLs to POSIX ACLs (posix-acl). So in this case of "xattr, posix-acl", if ACLs are present in xattr then they are used since the posix-acl cannot be more granular. If ACLs are not present in xattr, then posix-acl is used since it is the only backend available.
    • posix-acl, xattr: Specifies an ordered preference of posix-acl over xattr. So if xattr is not available then posix-acl is used. Similarly, if posix-acl is not available then xattr is used. What if both are available? In this case the ordered preference does not match the order of granularity, ie xattr is more granular than posix-acl. So in this case, the hash of xattr is compared to the hash of posix-acl - if they are the same, then xattr is used because it is more granular. However, if the comparison shows xattr and posix-acl are different, then posix-acl is used since it was specified as the first preference. Please note that the hash is available only in xattr:v4. So in the case of xattr:v3, posix-acl would override xattr unconditionally since a comparison is not made.

Default Value: xattr:raw

Examples:

  • xattr:raw: Stores the ACLs in the default Fusion SMB specific extended attribute.
  • native: Stores the ACLs natively on a supported file system.

Setting Up ACL Storage for a Share Using the Configuration File​

In the relevant[share] section of the configuration file, set the map_acls parameter to the desired value, as shown in the following example:

[share]
netname = MyShare
path = /export/share
map_acls = xattr:raw
[/share]

Adding a Share with ACL Storage Using the Command Line​

When adding a share using the command line, specify the ACL storage method using the map-acls parameter. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share --map-acls xattr:raw

Windows/POSIX ACL Mapping in Fusion SMB​

Fusion SMB supports mapping Windows ACLs to POSIX ACLs. This backend mapping is specified by the global configuration option map_acls = posix-acl and is relevant only for the security mode security = windows which is the default (and typically not specified).

By default, permission mapping is performed individually (separately read, write and execute). Alternatively, it is possible to map POSIX "rwx" to Windows's "Full Control" (FILE_ALL_ACCESS) by supplying extra argument map_full_control (e.g. map_acls = posix-acl:map_full_control).

Attribute backend option map_attributes = posix-exec must not be utilized with map_acls = posix-acl as it will break permissions. Fusion checks for this incompatibility on startup and will not run if this invalid configuration is specified.

The use case for implementing POSIX ACL as a backend for Windows ACL is to export a directory for sharing both by SMB and by NFSv3. The differences in semantics and behaviour of POSIX ACL and Windows ACL must be taken into account when mapping between the two types of ACLs. However, since POSIX ACL is the backend mapping, it essentially dictates the behaviour.

POSIX ACL consists of following:

  • UID and GID stored in file metadata,
  • Permission part of POSIX mode stored in file metadata,
  • ACL_TYPE_ACCESS (optional), and
  • ACL_TYPE_DEFAULT (optional)

For more info, please refer to the USENIX guide on ACLs.

With POSIX, access check is performed only against ACEs in ACL_TYPE_ACCESS, which are inherently allow type permissions (as opposed to deny). Therefore, Fusion SMB establishes a mapping between ACL_TYPE_ACCESS and explicit Windows ACEs (permissions utilized in access check that are not dynamically inherited nor inheritable) of type ACCESS_ALLOWED_ACE_TYPE.

Also with POSIX, inheritance happens through default permissions in ACL_TYPE_DEFAULT, which are applied during file/folder creation. This behaviour corresponds to Windows permissions which are (only) inheritable to both subfolders and files. Therefore Fusion SMB establishes a mapping between ACL_TYPE_DEFAULT and Windows ACEs with type ACCESS_ALLOWED_ACE_TYPE, and with flags OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE and INHERIT_ONLY_ACE.

Besides these mappings, there are no more options left to distinguish between any more types of permissions. This means that Fusion cannot map, for example, deny type permissions or any other type of inheritable permissions.

In those cases where there is no mapping for any single ACE in the Windows DACL, Fusion rejects setting it. This is because silently failing setting of deny type permissions could be a security risk.

Please note that the POSIX ACL backend is only responsible for setting POSIX ACLs based on Windows ACLs and building Windows ACLs from POSIX ACL. Everything else, especially the inheritance, happens on the upper layer of ACLs management. So for the creation of new objects, there are a couple different possible behaviours in Fusion SMB. If a DACL (which can be NULL) is supplied during object creation, then that supplied DACL is utilized and inheritance is skipped. Otherwise, Fusion SMB attempts to inherit permissions from parent object. In the case that the inheritance is not successful, Fusion SMB assigns permissions to the new object (FILE_ALL_ACCESS to owner and LOCAL SYSTEM).

More details on how the backend mapping sets POSIX ACLs based on Windows ACLs (Mapping Windows ACL to POSIX ACL) and builds Windows ACLs from POSIX ACLs (Mapping POSIX ACL to Windows ACL) are below:

Mapping Windows ACL to POSIX ACL​

"OwnerSid" and "GroupSid" fields of a security descriptor are mapped to POSIX UID and GID, respectively.

If "AceType" is not ACCESS_ALLOWED_ACE_TYPE, the ACE conversion fails with STATUS_INVALID_PARAMETER.

The "AceFlags" affect processing in following way:

ConditionResult
Flags are zeroMapped ACE will be stored in ACL_Type_ACCESS
Flag is INHERITED_ACEMapped ACE will be stored in ACL_TYPE_ACCESS
Target is directory AND flags are OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACEMapped ACE will be stored in ACL_TYPE_ACCESS and ACL_TYPE_DEFAULT
Target is directory AND flags are OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE, INHERITED_ACEMapped ACE will be stored in ACL_TYPE_ACCESS and ACL_TYPE_DEFAULT
Target is directory AND flags are OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE, INHERIT_ONLY_ACEMapped ACE will be stored in ACL_TYPE_DEFAULT
Target is directory AND flags are OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE, INHERIT_ONLY_ACE, INHERITED_ACEMapped ACE will be stored in ACL_TYPE_DEFAULT
All other scenariosFail with STATUS_INVALID_PARAMETER

The principals are mapped in following way:

ConditionPOSIX Tag Type
SID is "Everyone"OTHER
Target is a directory, ACE is inheritable and SID is "CREATOR_OWNER"USER_OBJ (ACL_TYPE_DEFAULT)
Target is a directory, ACE is inheritable and SID is "CREATOR_GROUP"GROUP_OBJ (ACL_TYPE_DEFAULT)
SID matches with OwnerUSER_OBJ (ACL_TYPE_ACCESS) and USER
SID matches with Primary GroupGROUP_OBJ (ACL_TYPE_ACCESS) and GROUP
SID is converted to UIDUSER
SID is converted to GIDGROUP
All other scenariosFail with STATUS_INVALID_PARAMETER

The access masks are mapped in following way:

ACCESS Mask BitPOSIX Permission Bit
FILE_READ_DATAR
FILE_WRITE_DATAW
FILE_APPEND_DATAW
FILE_READ_EAR
FILE_WRITE_EAW
FILE_EXECUTEX
FILE_DELETE_CHILD
FILE_READ_ATTRIBUTES
FILE_WRITE_ATTRIBUTES
DELETE
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

Mapping POSIX ACL to Windows ACL​

POSIX UID and GID are mapped to "OwnerSid" and "GroupSid" fields of a security descriptor, respectively.

Fusion SMB fetches ACL_TYPE_ACCESS by reading the extended attribute corresponding to it. If ACL_TYPE_ACCESS is present, Fusion SMB converts it to DACL. The mapped ACEs have "AceType" ACCESS_ALLOWED_ACE_TYPE and no "AceFlags".

To map the principals, Fusion SMB uses following mapping for the "tag types":

  • USER_OBJ -> "OwnerSid"
  • USER -> A user that is defined by the "qualifier" field of ACE.
  • GROUP_OBJ -> "GroupSid"
  • GROUP -> A group that is defined by the "qualifier" field of ACE.
  • MASK -> No corresponding mapping in Windows DACL, instead utilized in figuring out the effective permissions for applicable principal types.
  • OTHER -> Well-known SID "Everyone"
  • UNDEFINED -> EA is malformatted and POSIX ACL backend will return with error.

Otherwise, if ACL_TYPE_ACCESS was not present, Fusion SMB needs to convert POSIX mode to DACL. To map the principals, Fusion SMB uses following mapping:

  • user -> "OwnerSid"
  • group -> "GroupSid"
  • other -> Well-known SID "Everyone"

Fusion SMB fetches ACL_TYPE_DEFAULT by reading the extended attribute corresponding to it. If ACL_TYPE_DEFAULT is present, Fusion SMB converts the contents of it into the same DACL. The mapped ACEs have "AceType" ACCESS_ALLOWED_ACE_TYPE and "AceFlags" OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE and INHERIT_ONLY_ACE.

To map the principals in ACL_TYPE_DEFAULT, Fusion SMB uses the same mapping as with ACL_TYPE_ACCESS, but with following changes:

  • USER_OBJ -> "CREATOR_OWNER"
  • GROUP_OBJ -> "CREATOR_GROUP"

The mapping from POSIX permissions to access mask utilizes Windows's GENERIC counterparts for the most part, but there are some distinct features that need to be handled separately. POSIX "w" permissions on a directory grants the ability to both create and delete files/directories under a directory. However, FILE_GENERIC_WRITE only grants the ability to create files/subdirectories. Fusion SMB therefore always give FILE_DELETE_CHILD with FILE_GENERIC_WRITE permissions to match the POSIX semantics regarding deletion of files/directories. FILE_DELETE_CHILD is only applicable for directories, but for simplicity Fusion SMB gives it also for files as there is no adverse effect in doing so (even Windows Explorer includes it for files in its "Full Control" permission set).

Another concern is ability to modify ACL and ownership. In POSIX, only owner and root have the ability to modify ACL and ownership of an object. In Windows, the previous are controlled by WRITE_DAC and WRITE_OWNER permissions, which are not included in any of the GENERIC permissions (although the owner has implicit right to modify ACL). Fusion SMB's implementation adds the ability to control how POSIX "rwx" permission is mapped. By default, Fusion SMB maps POSIX permissions individually (separately 'r', 'w' and 'x'). Alternatively Fusion SMB Share can map POSIX "rwx" to FILE_ALL_ACCESS by supplying extra argument map_full_control (e.g. map_acls = posix-acl:map_full_control).

To map POSIX permissions, Fusion SMB utilizes the following mapping:

  • POSIX --- -> 0
  • POSIX R -> FILE_GENERIC_READ
  • POSIX W -> FILE_GENERIC_WRITE | FILE_DELETE_CHILD
  • POSIX X -> FILE_GENERIC_EXECUTE
  • POSIX RWX -> Either FILE_GENERIC_[READ|WRITE|EXECUTE] | FILE_DELETE_CHILD or FILE_ALL_ACCESS

Administrative Shares​

Administrative shares, such as C$ and D$, are special hidden shares representing the root of a drive on a Windows machine. These shares are only accessible to members of the Administrators group.

In Fusion SMB, you can designate a share as administrative to simulate this behavior and potentially use it as a root for other shares.

Share Parameter Designating a Share as Administrative

Value Type: boolean

Value Format: true|false

  • true: Designates share as an administrative share.
  • false: Makes it a regular share.

Default Value: false

important

When designating a share as an administrative share, the netname parameter MUST be set to a single English letter followed by $ (e.g., C$, D$, etc.)

Additionally, the only other acceptable parameters for administrative shares are path and remark.

Setting Up an Administrative Share Using the Configuration File​

In the relevant[share] section of the configuration file, set the administrative parameter to true and configure the netname parameter with the desired administrative share name, as shown in the following example:

[share]
netname = C$
path = /mnt/drive-c
administrative = true
remark = Administrative share for drive C
[/share]

Adding an Administrative Share Using the Command Line​

When adding an administrative share using the command line, specify the administrative parameter and the netname parameter. For example:

sudo tsmb-cfg share add -n 'C$' -p /mnt/drive-c --administrative

Using an Administrative Share as a Root for Other Shares​

Administrative shares can be used as a root for other shares. For example, if you have an administrative share named C$, you can create other shares that are subdirectories of this share.

This is done by creating a share with its path pointing to C:/<dir>, where <dir> is the name of the subdirectory that exists in the directory shared as C$.

For example, given the directory tree:

/mnt
└── drive-c
    ├── shared
    └── private

You can create an administrative share for the drive-c directory as C$:

  • netname = C$
  • path = /mnt/drive-c

And a regular share for the shared directory

  • netname = shared
  • path = C:/shared – relative to the C$ share

Since the private directory is not explicitly shared, it will only be accessible to the administrators when using the administrative share C$.

Setting Up a Share Under an Administrative Share Using the Configuration File​
important

This can only be done when the parent administrative share is already configured.

In the relevant[share] section of the configuration file, set the path parameter to the desired path relative to the administrative share, as shown in the following example:

[share]
netname = shared
path = C:/shared
remark = Shared directory
[/share]
Adding a Share Under an Administrative Share Using the Command Line​
important

This can only be done when the parent administrative share is already configured.

When adding a share using the command line, specify the -p or --path parameter to the desired path relative to the administrative share. For example:

sudo tsmb-cfg share add -n shared -p C:/shared

Apple Extensions​

Fusion SMB supports Apple Extensions for SMB, enhancing interoperability with macOS clients. These extensions provide additional functionality, improve compatibility with macOS systems, and boost performance when accessing SMB shares from macOS devices. By enabling Apple Extensions, you can take advantage of features such as:

  • Improved Directory Enumeration: Enabled by the kAAPL_SUPPORTS_READ_DIR_ATTR capability, this allows the server to export macOS-specific metadata, such as resource forks and Finder information, improving performance.
  • Time Machine Support: Enabled by the kAAPL_SUPPORTS_FULL_SYNC capability, this feature allows macOS clients to use Time Machine for backup and restore operations on SMB shares.
Global Parameter Enabling Apple Extensions

Value Type: boolean

Value Format: true|false

  • true: Enables Apple Extensions for SMB.
  • false: Disables Apple Extensions for SMB.

Default Value: true

Enabling Apple Extensions Using the Configuration File​

In the [global] section of the configuration file, set the apple_extensions parameter to true to enable Apple Extensions for SMB, as shown below:

[global]
. . .
apple_extensions = true
. . .
[/global]

Case Sensitivity​

In Windows environments, file operations are case-insensitive by default, meaning the file system does not differentiate between uppercase and lowercase characters in file or directory names. For example, MyFile.txt is treated the same as myfile.txt.

However, on Linux–where Fusion SMB operates–file operations are inherently case-sensitive. Hence, file operations on Fusion SMB are case-sensitive by default. For use cases that require case-insensitive operations, you can modify this behavior. Case sensitivity can be controlled globally, or overridden on a per-share basis.

When configured to be case-insensitive, Fusion SMB first attempts to rely on the underlying file system's support for case-insensitive file name resolution. However, if not supported by the file system, Fusion SMB will fall back on performing a case-insensitive comparison of the file name against all the files in the directory.

important

Enabling case-insensitivity can introduce a significant overhead, especially on file systems that don't natively support it, or on large datasets and complex directory trees.

Case sensitivity is controlled with the following parameters:

Global Parameter Default Case Sensitivity Behavior for All Shares
Overridden by Per-Share Parameter: case_insensitive

Value Type: boolean

Value Format: true|false

  • true: Makes file operations case-insensitive by default.
  • false: Leaves file operations case-sensitive by default.

Default Value: false

Share Parameter Case Sensitivity for a Specific Share
Overrides Global Parameter: case_insensitive

Value Type: boolean

Value Format: true|false

  • true: Makes file operations on the share case-insensitive.
  • false: Leaves file operations on the share case-sensitive.

Default Value: as set in the global configuration.

Configuring Case Sensitivity for a Share Using the Configuration File​

Define the default behavior for all shares in the [global] section. You can override this behavior in specific [share] sections.

  • Example 1: Enabling Case-Insensitivity Globally but Keeping a Specific Share Case-Sensitive

    [global]
    . . .
    case_insensitive = true
    . . .
    [/global]

    [share]
    netname = MyShare
    path = /export/share
    case_insensitive = false
    [/share]

  • Example 2: Disabling Case-Insensitivity Globally but Enabling it for a Specific Share

    [global]
    . . . # no change - case-insensitivity is disabled by default
    [/global]

    [share]
    netname = MyShare
    path = /export/share
    case_insensitive = true
    [/share]

Adding a Case-Insensitive Share Using the Command Line​

When adding a share using the command line, specify the --case-insensitive parameter. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share \
    --case-insensitive true

Change Notifications​

SMB change notifications enable clients to subscribe to events that alert them to changes in files and directories on a share. This functionality is particularly useful for applications that need to monitor file changes in real-time, such as the Windows File Explorer or collaborative editing tools. Clients can receive notifications about both data changes and metadata updates, such as modifications to a file's name or attributes.

Global Parameter Change Notification Behavior

Value Type: string

Value Format: smb|kernel|none

  • smb: Generates change notifications based on file operations performed by SMB clients against Fusion SMB. This option does not detect changes made by other means, such as direct access to the storage, or changes made by other protocols (e.g., NFS shares enabled for the same data). Use this setting for custom VFS modules that don't trigger inotify events.
  • kernel: Generates change notifications for clients based on notifications Fusion SMB receives from the kernel's inotify interface. This includes changes made via any method, including direct access to storage, or changes made by other protocols.
  • none: Disables change notifications.

Default Value: kernel

Configuring Change Notifications Using the Configuration File​

In the [global] section of the configuration file, set the change_notify parameter to the desired method for generating change notifications.

[global]
. . .
change_notify = kernel
. . .
[/global]

Compression​

SMB Compression, introduced in SMB 3.1.1, enhances file transfer performance by minimizing the size of transmitted data. When enabled, it optimizes communication between Fusion SMB and supporting clients, reducing bandwidth usage by 20% to 70%, and achieving up to three times faster data transfer speeds, depending on the data type and network conditions.

Fusion SMB supports SMB Compression using the LZ77 algorithm. This feature allows you to configure the number of compression threads, the minimum SMB message size for compression, and specify files to exclude. Excluding files is particularly useful for pre-compressed files or directories containing many small files that would not benefit from compression but could incur unnecessary CPU overhead.

Required SMB Dialect: SMB 3.1.1

Enabling compression is done by specifying the compression algorithm you wish to use.

Global Parameter Enabling Compression and Specifying Compression Algorithms

Value Type: string

Value Format: <algorithm>[,<algorithm>,...]

  • <algorithm>: The compression algorithm to use for SMB compression. The supported algorithms are:
    • LZ77

Default Value: none (SMB compression is disabled)

Examples:

  • LZ77: Enables SMB compression using the LZ77 algorithm.

Additional compression parameters:

Global Parameter Number of Compression Threads

Value Type: integer

Value Format: <threads>

  • <threads>: A positive integer representing the number of threads to use for compression.

Default Value: 1

Examples:

  • 10 starts 10 threads for compression.
Global Parameter Minimum SMB Message Size for Compression

Value Type: integer

Value Format: <bytes>

  • <bytes>: A non-negative integer, representing the threshold size in bytes for SMB compression. Messages exceeding this threshold will be compressed if SMB compression is enabled.

Default Value: 4096

Examples:

  • 8192: Only messages larger than 8KB will be compressed.
  • 0: Compress all messages, regardless of size.
Share Parameter Excluding Files from Compression

Value Type: string

Value Format: <pattern>|<pattern>|...

  • Patterns are separated by |.
  • A pattern can include the ? wildcard to match a single character
  • A pattern can include the * wildcard to match any number of characters

Examples:

  • * matches all files.
  • *.tmp|*.bak matches files with the .tmp or .bak extension.
  • *.foo|*.bar|*foobar* matches files that have the .foo or .bar extension, or contain the string foobar.

Configuring Compression Using the Configuration File​

In the [global] section of the configuration file, ensure the SMB 3.1.1 dialect is enabled, enable compression using the LZ77 algorithm, and optionally configure the number of threads used for compression and the minimum message size for compression:

[global]
. . .
dialect_max = SMB3.1.1
compression_algorithms = LZ77
compression_threads = 10
compression_threshold = 1024
. . .
[/global]

Additionally, specify files excluded from compression in the relevant [share] section. The following example excludes common compressed file types from the MyShare share:

[share]
netname = MyShare
path = /export/share
compression_deny = *.zip|*.tar.gz|*.gz|*.tgz|*.rar|*.7z|*.cab|*.jar|*.z
. . .
[/share]

Distributed File System (DFS)​

The Distributed File System (DFS) in SMB simplifies the management and accessibility of network shares by consolidating multiple SMB file shares into a unified namespace. This functionality allows users to navigate shared folders without knowing which specific servers are hosting them.

To use DFS with Fusion SMB shares, the feature must be enabled both globally and on each share you want to include in the DFS namespace.

DFS behavior is controlled with the following parameters:

Global Parameter Toggling DFS Globally

Value Type: boolean

Value Format: true|false

  • true: Enables inclusion in DFS.
  • false: Disables inclusion in DFS.

Default Value: false

Share Parameter Toggling DFS Per-Share

Value Type: boolean

Value Format: true|false

  • true: Enables share's inclusion in DFS.
  • false: Disables share's inclusion in DFS.

Default Value: false

Enabling DFS Using the Configuration File​

In the [global] section of the configuration file, set the dfs parameter to true to enable DFS. Additionally, enable DFS for each share you want to include in the namespace by setting the dfs parameter to true in the respective [share] sections.

[global]
. . .
dfs = true
. . .
[/global]

[share]
netname = share1
dfs = true
path = . . .
. . .
[/share]

Durable Handles​

Durable handles enhance the reliability of file operations over network connections by enabling clients to maintain access to open files after temporary network disruptions. When a client requests a durable handle while opening a file, the SMB server assigns a unique handle identifier and retains its state. If the client disconnects unexpectedly, the server preserves the handle state for a defined timeout period, allowing the client to reconnect and continue operations without reopening the file or risking data loss.

  • Durable Handles V1, introduced in SMB2, provides a rudimentary mechanism for maintaining file handles during network disruptions.
  • Durable Handles V2, introduced in SMB3, extends functionality to support continuous and high availability scenarios, such as cluster failovers.

Fusion SMB allows you to configure the timeout period for durable handles requested by clients.

Clients using V1 and V2 durable handles are handled differently:

  • V1 clients cannot specify a timeout; Fusion SMB fully controls the timeout.
  • V2 clients can specify a timeout. If no timeout is provided, Fusion SMB controls the setting.

Durable handles behavior is controlled with the following parameters:

Global Parameter Durable Handles V1 Timeout

Value Type: integer

Value Format: <duration>

  • <duration> is a positive integer representing the number of seconds for the timeout of durable handles V1.

Default Value: 960

Examples:

  • 960 seconds (16 minutes) is the default timeout for durable handles V1.
Required SMB Dialect: SMB 2.002 or higher
Global Parameter Durable Handles V2 Timeout

Value Type: integer

Value Format: <duration>

  • <duration> is a positive integer representing the number of seconds for the timeout of durable handles V2.

Default Value: 180

Examples:

  • 180 seconds (3 minutes) is the default timeout for durable handles V2.
Required SMB Dialect: SMB 3.0 or higher

Setting the Timeout for Durable Handles Using the Configuration File​

In the [global] section of the configuration file, set the durable_v1_timeout parameter to the desired timeout value in seconds.

[global]
. . .
durable_v1_timeout = 540
durable_v2_timeout = 360
. . .
[/global]

The example above sets the timeout for durable handles V1 to 540 seconds (9 minutes) and the timeout for durable handles V2 to 360 seconds (6 minutes).

Setting the Timeout for Durable Handles Using the CLI​

To set the durable handles timeout via the CLI, use the tsmb-cfg global update command with the -t and -T options for V1 and V2 handles timeouts respectively:

sudo tsmb-cfg global update -t 540
sudo tsmb-cfg global update -T 360

In the example above:

  • The first command sets the timeout for durable handles V1 to 540 seconds (9 minutes).
  • The second command sets the timeout for durable handles V2 to 360 seconds (6 minutes).

IPC$ Shares​

The IPC$ share in Windows is a hidden, system-managed share managed by the Windows Server service (srvsvc) for remote administration and communication between networked computers via named pipes. It facilitates administrative tasks like listing available shares, enumerating users, and managing services through Remote Procedure Calls (RPC).

Fusion SMB provides an IPC$ share to enable share administration, which is enabled by default.

IPC$ shares behavior is controlled with the following parameter:

Global Parameter Enabling or Disabling the IPC$ Share

Value Type: boolean

Value Format: true|false

  • true: Enables the IPC$ share.
  • false: Disables the IPC$ share.

Default Value: true

Disabling the IPC$ Share Using the Configuration File​

In the [global] section of the configuration file, set the enable_ipc parameter to false to disable the IPC$ share.

[global]
. . .
enable_ipc = false
. . .
[/global]

Named Streams​

Named streams, also known as alternate data streams, allow files to contain multiple streams of data in addition to the default stream ($DATA). Both the default and alternate streams can be independently opened, written to, and read from.

Fusion SMB supports named streams by leveraging extended attributes provided by the underlying file system.

Required SMB Dialect: SMB 2.002 or higher
important

The named streams feature must be disabled for a share if the underlying file system does not support extended attributes (e.g., exFAT).

Named streams behavior is controlled with the following parameter:

Share Parameter Enabling or Disabling Named Streams for a Share

Value Type: boolean

Value Format: true|false

  • true: Enables named streams on the share.
  • false: Disables named streams on the share.

Default Value: true

Disabling Named Streams for a Share Using the Configuration File​

In the relevant [share] section of the configuration file, set the named_streams parameter to false, as shown in the following example:

[share]
netname = MyShare
path = /export/share
named_streams = false
[/share]

Adding a Share with Named Streams Disabled Using the Command Line​

When adding a share using the command line, enable or disable named streams by including the --named-streams parameter. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share \
    --named-streams false

Updating the Named Streams Setting for a Share Using the Command Line​

When updating a share using the command line, enable or disable named streams by including the --named-streams parameter. For example:

sudo tsmb-cfg share update -n MyShare --named-streams false

Server-Side Copy​

Server-side copy is a feature that allows the server to handle file copy operations within the same server internally, without transferring data to and from the client. Supporting clients initiate server-side copy operations whenever possible, significantly improving performance for large file transfers within the same server. This feature minimizes network traffic and reduces CPU usage on both the client and server, since the data does not need to be read by the client and re-sent to the server.

warning

macOS clients, including macOS 14.1 Sonoma, cannot display progress for server-side copy operations. This limitation can cause applications to appear unresponsive. To address this, server-side copy operations can be disabled specifically for macOS clients while remaining enabled for other client platforms.

Server-side copy behavior is controlled with the following parameters:

Global Parameter Toggling Server-Side Copy for All Clients
Possibly Overrides Global Parameter: apple_server_side_copy

Value Type: boolean

Value Format: true|false

  • true: Enables server-side copy for all clients.
  • false: Disables server-side copy (including macOS clients).

Default Value: true

Global Parameter Toggling Server-Side Copy for macOS Clients
Possibly Overridden by Global Parameter: server_side_copy

Value Type: boolean

Value Format: true|false

  • true: Enables server-side copy macOS clients (has no effect if server_side_copy is false).
  • false: Disables server-side copy for macOS clients.

Default Value: false

Configuring Server-Side Copy Using the Configuration File​

In the [global] section of the configuration file, set the server_side_copy and the apple_server_side_copy parameters to true to enable server-side copy for all clients:

[global]
. . .
server_side_copy = true
apple_server_side_copy = true
. . .
[/global]

Alternatively, you can enable server-side copy for clients except for macOS clients by setting the server_side_copy parameter to true and the apple_server_side_copy parameter to false:

[global]
. . .
server_side_copy = true
apple_server_side_copy = false
. . .
[/global]

Share Scoping​

Share scoping allows you to restrict access to a share based on the server name (or alias) the client uses to connect. When enabled, the share is only accessible if the client connects using the specified server name or alias. This feature is particularly useful for compartmentalizing access based on the server's DNS records, similar to the concept of virtual hosts in HTTP servers.

If share scoping is configured but the server is not accessible using the specified name (e.g., no DNS record resolves the name to any of the server's IP addresses), the share will not be available to clients.

Share scoping behavior is controlled with the following parameter:

Share Parameter Specifying the Server for a Share

Value Type: string

Default Value: none (the share will be visible through any hostname)

Examples:

  • filesrv01 specifies that the share is visible only to clients connecting to \\filesrv01.

Configuring Share Scoping Using the Configuration File​

In the relevant[share] section of the configuration file, set the server parameter to the desired server name, as shown in the following example:

[share]
netname = MyShare
path = /export/share
server = filesrv01
[/share]

Adding a Share with Share Scoping Using the Command Line​

When creating a share via the command line, use the --server parameter to specify the desired server name. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share \
    --server filesrv01

Volume Shadow Copy (VSS)​

Volume Shadow Copy Service (VSS) is a framework that enables manual or automatic snapshots of files or volumes, even while in use. This feature allows for point-in-time recovery (PITR), letting users browse the contents of a share as they were at a specific point in time.

Fusion SMB's support for VSS depends on the underlying file system's VSS capabilities (private VSS implementation), or by mounting snapshots in a directory accessible to Fusion SMB (default VSS implementation).

You can configure the default VSS behavior globally for all shares or override it on a per-share basis.

Required SMB Dialect: SMB 3.0 or higher

Controlling the Default VSS Behavior for All Shares​

You can configure the default VSS behavior for all shares. This setting applies to all shares unless overridden on a per-share basis.

This is particularly useful when shares are created out-of-band, and cannot be configured through the configuration file or CLI.

Global Parameter Enabling or Disabling VSS for Shares by Default
Overridden by Per-Share Parameter: vss

Value Type: boolean

Value Format: true|false

  • true: Enables VSS on all shares, except for shares for which it was explicitly disabled.
  • false: Disables VSS on all shares, except for shares for which it was explicitly enabled.

Default Value: false

Global Parameter Default Parameters for VSS Data Locations
Overridden by Per-Share Parameter: vss_params

Value Type: string

note

The following format applies only when when the default VSS implementation is used. If the underlying file system of the share has a different VSS implementation, use that file system's specific format to configure VSS.

Value Format: path=<path>[,share_root=<share_root>]

  • path=<path> (required): <path> is where the snapshot roots are located. Under this directory, subdirectories are expected named with the following timestamp format: @GMT-YYYY.MM.DD-hh.mm.ss (e.g., @GMT-2019.11.11-12.10.10, @GMT-2024.05.03-22.12.42, etc.). To allow for a consistent naming pattern across all shares, <path> can include the following variables:
    • ${share.netname}: refers to the share's name, as defined in the share's netname parameter.
    • ${share.path.dirname}: refers to the share's path, as defined in the share's path parameter, without the last component (e.g., /path/to for /path/to/share).
    • ${share.path.basename}: refers to the share's path, as defined in the share's path parameter, without the leading path (e.g., share for /path/to/share).
  • share_root=<share_root> (optional): This parameter is used when you have multiple shares on the same volume, and when a snapshot is taken, it's taken for the entire volume. Hence, <share_root> specifies the the directory inside each snapshot subdirectory that contains the files for this particular share at that point of time. If not specified, the share root defaults to the root of the snapshot subdirectory.

Default Value: none

Examples:

  • path=/mnt/.snapshots/${share.netname},share_root=data, if the share's name is sh1 and its path is /mnt/data, specifies that the snapshot roots are located in the /mnt/.snapshots/sh1 directory, and the share's data for each snapshot is in the /mnt/.snapshots/sh1/@GMT-<timestamp>/data directory.
  • path=${share.path.dirname}/.snapshots,share_root=data, if the share's path is /mnt/data, specifies that the snapshot roots are located in the /mnt/.snapshots directory, and the share's data for each snapshot is in the /mnt/.snapshots/@GMT-<timestamp>/data directory.
  • path=${share.path.dirname}/.snapshots,share_root=${share.path.basename}, if the share's path is /mnt/data/public, specifies that the snapshot roots are located in the /mnt/.snapshots directory, and the share's data for each snapshot is in the /mnt/.snapshots/@GMT-<timestamp>/public directory.

Controlling VSS Behavior for a Specific Share​

If VSS is disabled by default, first enable VSS on the share.

Share Parameter Enabling or Disabling VSS on a Share
Overrides Global Parameter: vss

Value Type: boolean

Value Format: true|false

  • true: Enables VSS on the share.
  • false: Disables VSS on the share.

Default Value: as set in the global configuration.

When VSS is enabled, depending on the underlying file system and its VSS support, you may need to configure additional parameters.

Share Parameter Configuring Additional Parameters for VSS on a Share
Overrides Global Parameter: vss_params

Value Type: string

note

The following format applies only when when the default VSS implementation is used. If the underlying file system of the share has a different VSS implementation, use that file system's specific format to configure VSS.

Value Format: path=<path>[,share_root=<share_root>]

  • path=<path> (required): <path> is where the snapshot roots are located. Under this directory, subdirectories are expected named with the following timestamp format: @GMT-YYYY.MM.DD-hh.mm.ss (e.g., @GMT-2019.11.11-12.10.10, @GMT-2024.05.03-22.12.42, etc.).
  • share_root=<share_root> (optional): This parameter is used when you have multiple shares on the same volume, and when a snapshot is taken, it's taken for the entire volume. Hence, <share_root> specifies the the directory inside each snapshot subdirectory that contains the files for this particular share at that point of time. If not specified, the share root defaults to the root of the snapshot subdirectory.

Default Value: as set in the global configuration.

Examples:

  • path=/mnt/my-share-snapshots specifies that the snapshot roots are located in the /mnt/my-share-snapshots directory.
  • path=/mnt/snapshots,share_root=my-share specifies that the snapshot roots are located in the /mnt/snapshots directory, and the share root for each share is the /mnt/snapshots/@GMT-<timestamp>/my-share directory.

Setting Up VSS for a Share Using the Configuration File​

Setting Up a Share with VSS, Using the Default Behavior:​

In the [global] section of the configuration file, set the vss parameter to true to enable VSS for shares by default. Additionally, specify the path where the snapshot roots are located if necessary.

[global]
. . .
vss = true
vss_params = path=/mnt/.snapshots/${share.netname},share_root=data
. . .
[/global]

[share]
netname = sh1
path = /mnt/data
[/share]

In the example above, VSS is enabled for shares by default, and the snapshot roots are located in the /mnt/.snapshots/sh1 directory. The share's data for each snapshot is in the /mnt/.snapshots/sh1/@GMT-<timestamp>/data directory.

Setting Up a Share with VSS, Overriding the Default Behavior:​

In the relevant[share] section of the configuration file, set the vss parameter to true, and set the vss_params parameter to point to the directory where the snapshot roots are located, as shown in the following example:

[share]
netname = MyShare
path = /export/share
vss = true
vss_params = path=/mnt/my-share-snapshots
[/share]

Adding a Share with VSS Using the Command Line​

When adding a share using the command line, specify the --vss parameter and the --vss-params parameter. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share\
    --vss true \
    --vss-params "path=/mnt/my-share-snapshots"

Windows/DOS File Attribute Storage​

In Microsoft environments, file systems such as FAT and NTFS traditionally support file attributes that define how the operating system should handle a file. These attributes are Hidden, System, and Archive:

  • Archive (A): Indicates that the file has been modified since the last backup and should be included in the next backup operation. Backup software clears this attribute after backing up the file, and the operating system sets it again when the file is modified.
  • Hidden (H): Marks the file as hidden, preventing it from appearing in directory listings, such as when in the DIR command output or when browsing in Windows File Explorer and file dialogs.
  • System (S): Marks the file as a system file, protecting it from being modified or deleted. This attribute safeguards critical files from accidental changes. System files are typically treated as hidden as well.

Since Fusion SMB operates in a Linux environment, where the shared file system is most likely does not support file attributes natively, Fusion SMB offers multiple mechanisms to store these attributes, which can be configured on a per-share basis, depending on the underlying file system.

Share Parameter Specifying the Storage Method for File Attributes

Value Type: string

Value Format: <method>[,<method>,...]

  • Values are separated by ,.

  • A <method> can be one of the following:

    • native: Store attributes natively on the file system, if supported. Use this option if the underlying file system is NTFS, or another private VFS module that supports these attributes.
    • xattr[:<version>]: Use Samba-compatible extended attribute user.DOSATTRIB to store the attributes. The optional <version> parameter specifies the version of the extended attribute format to use:
      • v3: Use the Samba 3.5 to 4.10 format.
      • v4: Use the Samba 4.11 to 4.16 format (default).
      • v5: Use the Samba 4.17 or newer format.
    • filename:<attributes>:<pattern>: Treat files matching <pattern> as always having the attributes specified in <attributes>:
      • <attributes> is a non-delimited combination of:
        • A: Archive.
        • S: System.
        • H: Hidden.
      • <pattern> is a shell-style wildcard pattern that matches the file name.
      note

      The only currently supported <pattern> is .*.

    • posix-exec:<attributes>: Map attributes to POSIX execute permission bits, where <attributes> is a non-delimited combination of:
      • A: Archive, stored in the user's execute permission bit (u+x).
      • S: System, stored in the group's execute permission bit (g+x).
      • H: Hidden, stored in the other's execute permission bit (o+x).
      note

      This is a legacy method and should be used with care. This method doesn't affect directories, and assumes that the execute permission bits are not used for their original purpose, and are only modified by Fusion SMB.

Default Value: xattr:v4

Examples:

  • xattr,filename:HS:.*: Uses the default Samba v4 extended attributes format, and treat all dot files as having the Hidden and System attributes.

Setting Up Windows File Attributes Storage for a Share Using the Configuration File​

In the relevant[share] section of the configuration file, set the map_attributes parameter to the desired value, as shown in the following example:

[share]
netname = MyShare
path = /export/share
map_attributes = xattr:v4
[/share]

Adding a Share with Windows File Attributes Storage Using the Command Line​

When adding a share using the command line, specify the the storage method using the -m or --map-attributes parameters. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share --map-attributes xattr:v4