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.
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
).
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:
Condition | Result |
---|---|
Flags are zero | Mapped ACE will be stored in ACL_Type_ACCESS |
Flag is INHERITED_ACE | Mapped ACE will be stored in ACL_TYPE_ACCESS |
Target is directory AND flags are OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE | Mapped 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_ACE | Mapped 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_ACE | Mapped ACE will be stored in ACL_TYPE_DEFAULT |
Target is directory AND flags are OBJECT_INHERIT_ACE, CONTAINER_INHERIT_ACE, INHERIT_ONLY_ACE, INHERITED_ACE | Mapped ACE will be stored in ACL_TYPE_DEFAULT |
All other scenarios | Fail with STATUS_INVALID_PARAMETER |
The principals are mapped in following way:
Condition | POSIX 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 Owner | USER_OBJ (ACL_TYPE_ACCESS) and USER |
SID matches with Primary Group | GROUP_OBJ (ACL_TYPE_ACCESS) and GROUP |
SID is converted to UID | USER |
SID is converted to GID | GROUP |
All other scenarios | Fail with STATUS_INVALID_PARAMETER |
The access masks are mapped in following way:
ACCESS Mask Bit | POSIX Permission Bit |
---|---|
FILE_READ_DATA | R |
FILE_WRITE_DATA | W |
FILE_APPEND_DATA | W |
FILE_READ_EA | R |
FILE_WRITE_EA | W |
FILE_EXECUTE | X |
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.
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 theC$
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
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
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.
- Configuration file's
[global]
section:apple_extensions
tsmb-cfg global update
:--apple-extensions
tsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
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:
- Configuration file's
[global]
section:case_insensitive
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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
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.
- Configuration file's
[global]
section:change_notify
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
Enabling compression is done by specifying the compression algorithm you wish to use.
- Configuration file's
[global]
section:compression_algorithms
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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:
- Configuration file's
[global]
section:compression_threads
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
- Configuration file's
[global]
section:compression_threshold
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
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:
- Configuration file's
[global]
section:dfs
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
Value Type: boolean
Value Format: true|false
true
: Enables inclusion in DFS.false
: Disables 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:
- Configuration file's
[global]
section:durable_v1_timeout
tsmb-cfg global update
:-t
or--durable_v1_timeout
tsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
- Configuration file's
[global]
section:durable_v2_timeout
tsmb-cfg global update
:-T
or--durable_v2_timeout
tsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
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:
- Configuration file's
[global]
section:enable_ipc
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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.
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:
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.
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:
- Configuration file's
[global]
section:server_side_copy
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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
- Configuration file's
[global]
section:apple_server_side_copy
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
server_side_copy
Value Type: boolean
Value Format: true|false
true
: Enables server-side copy macOS clients (has no effect ifserver_side_copy
isfalse
).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:
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.
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.
- Configuration file's
[global]
section:vss
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
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
- Configuration file's
[global]
section:vss_params
tsmb-cfg global update
: Not supportedtsmb-cfg global add
andtsmb-cfg global del
: Not supported
vss_params
Value Type: string
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'snetname
parameter.${share.path.dirname}
: refers to the share's path, as defined in the share'spath
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'spath
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 issh1
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.
When VSS is enabled, depending on the underlying file system and its VSS support, you may need to configure additional parameters.
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.
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