Skip to main content

Share Parameters

The following parameters are in the [share] sections of the configuration file

access_based_enumeration​

Controls access-based enumeration for the share.

Value Type: boolean

Value Format: true|false

  • true: Enables access based enumeration for the share.
  • false: Disables access based enumeration for the share.

Default Value: false

administrative​

Designates the share as an administrative share. Used in conjuction with netname.

Value Type: boolean

Value Format: true|false

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

Default Value: false

audit_level​

Controls the audit level for the share.

Value Type: integer

Default Value: none

Examples:

  • 1 sets the audit level to 1 for the share.
  • 3 sets the audit level to 3 for the share.

ca​

Enables or disables the persistent file handle database for the share. Used in conjunction with ca_params.

Overrides Global Parameter: ca

Value Type: boolean

Value Format: true|false

  • true: Enables the persistent file handle database for the share.
  • false: Disables the persistent file handle database for the share.

Default Value: false

ca_params​

Controls the behavior of the persistent file handle database for the share. Used in conjunction with ca.

Value Type: string

Possibly Overrides Global Parameter: ca_path
This parameter is only required when Fusion File Share Server is configured as an active-passive cluster.

Value Format: [<path>][,durable]

  • <path> is the path on a shared storage where the Fusion File Share Server stores its persistent file handle database for this share. This path must be accessible by all nodes in the Fusion File Share Server cluster to support continuous or high availability. This value overrides the global ca_path parameter for this share.
  • durable is an optional flag that indicates whether durable handles on this share should be persisted in the persistent file handle database.

Default Value: <ca_path>/<netname>, as determined by the global ca_path parameter and the share's netname parameter.

Examples:

  • /mnt/shared/ca would store the persistent file handle database in /mnt/shared/ca/<share_name> for each share where continuous availability is enabled.

case_insensitive​

Controls case sensitivity for the 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.

create_mask​

Controls the maximum POSIX permissions for files created on the share.

Value type: string

Value format: <mask>
Where <mask> is a string of four octal digits, representing the permission bits the POSIX file permissions are masked against. The resulting permissions are calculated as a bitwise AND between the POSIX file permissions and the create mask. In other words, this value represents the maximum POSIX permissions that would be applied to the file at creation.

Default value: 0744

Examples:

  • 0744 - The resulting permissions will range between 0000 and 0744, ensuring that the file is at most readable by group and others, while owner will have the full set of permissions.
  • 0644 - The resulting permissions will range between 0000 and 0644, ensuring that the file is at most readable by group and others, while owner will not have execute permissions.
  • 0750 - The resulting permissions will range between 0000 and 0750, ensuring that the file is at most readable and executable by group, others will not have any permissions, and the owner will have the full set of permissions.

compression_deny​

Controls which files should not be compressed with SMB compression enabled.

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.

dfs​

Controls the share's inclusion in Distributed File System (DFS).

Value Type: boolean

Value Format: true|false

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

Default Value: false

directory_mask​

Controls the maximum POSIX permissions for directories created on the share.

Value type: string

Value format: <mask>
Where <mask> is a string of four octal digits, representing the permission bits the POSIX directory permissions are masked against. The resulting permissions are calculated as a bitwise AND between the POSIX directory permissions and the create mask. In other words, this value represents the maximum POSIX permissions that would be applied to the directory at creation.

Default value: 0744

Examples:

  • 0744 - The resulting permissions will range between 0000 and 0744, ensuring the directory will be at most readable by group and others, while user will have the full set of permissions.
  • 0644 - The resulting permissions will range between 0000 and 0644, ensuring the directory will be at most readable by group and others, while owner will not have list permissions.
  • 0750 - The resulting permissions will range between 0000 and 0750, ensuring the directory will be at most readable and listable by group, others will not have any permissions, and the owner will have the full set of permissions.

enable_oplock​

Controls opportunistic locking behavior for the share.

warning

This parameter is deprecated. Use oplock instead.

Overrides Global Parameter: enable_oplock

Value Type: boolean

Value Format: true|false

  • true: Allows the client to acquire opportunistic locks (oplocks) on share's files.
  • false: Disables opportunistic locks (oplocks) on share's files.

Default Value: true

encrypt_data​

Controls encryption in transit for the share.

Overrides Global Parameter: encrypt_data

Value Type: boolean

Value Format: true|false

  • true: enable data transfer encryption on the share.
  • false: disable data transfer encryption on the share.

Default Value: as set in the global configuration.

files_allow​

Controls which files are allowed when using veto files.

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

Default Value: *

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.

files_deny​

Controls which files are not allowed when using veto files.

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

Default Value: none

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.

force_create_mode​

Controls the minimal POSIX permissions for files created on the share.

Value type: string

Value format: <mode>
Where <mode> is a string of four octal digits, representing the permission bits the POSIX file permissions are masked against. The resulting permissions are calculated as a bitwise OR between the POSIX file permissions and the create mode, after the file mask has been applied, as defined in create_mask has been applied. In other words, this value represents the minimum POSIX permissions that would be applied to the file at creation.

Default value: 0000

Examples:

  • 0000 - The resulting permissions will range between 0000 and 7777, ensuring the file will be at least readable by group and others, while user will have the full set of permissions.
  • 0644 - The resulting permissions will range between 0644 and 7777, ensuring the file will be at least readable by group and others, while owner will not have execute permissions.
  • 4644 - The resulting permissions will range between 4644 and 7777, ensuring the file will be at least readable and executable by group, others will not have any permissions, and the owner will have the full set of permissions. It will also have setuid, signifying that the file will be executed with the permissions of its owner.

force_directory_mode​

Controls the minimal POSIX permissions for directories created on the share.

Value type: string

Value format: <mode>
Where <mode> is a string of four octal digits, representing the permission bits the POSIX directory permissions are masked against. The resulting permissions are calculated as a bitwise OR between the POSIX file permissions and the create mode, after the directory mask has been applied, as defined in directory_mask has been applied. In other words, this value represents the minimum POSIX permissions that would be applied to the directory at creation.

Default value: 0000

Examples:

  • 0000 - The resulting permissions will range between 0000 and 7777, ensuring the directory will be at least readable by group and others, while user will have the full set of permissions.
  • 0644 - The resulting permissions will range between 0644 and 7777, ensuring the directory will be at least readable by group and others, while owner will not have list permissions.
  • 2644 - The resulting permissions will range between 2644 and 7777, ensuring the directory will be at least readable and listable by group, others will not have any permissions, and the owner will have the full set of permissions. It will also have setgid, signifying that the directory will inherit the group of the parent directory.

force_level2oplock​

Allows to force opportunistic locking to be level 2 (read-only) for the share.

warning

This parameter is deprecated. Use oplock instead.

Value Type: boolean

Value Format: true|false

  • true: Indicates that the server would only issue level 2 (read-only) opportunistic locks when an oplock is requested by the client. This can increase performance when the workload mostly consists of read operations.
  • false: Indicates that the server would issue opportunistic locks of any type when requested by the client.

Default Value: false

hidden​

Enables/disables hiding the share.

Value Type: boolean

Value Format: true|false

  • true: Hides a share.
  • false: Makes a share visible.

Default Value: false

hosts_allow​

Controls which hosts are allowed to access the share when using host-based access control.

Value Type: string

Value Format: <IP|CIDR>,<IP|CIDR>,...

  • Values are separated by ,.
  • A value can be an either an IP address, or a subnet in CIDR notation.

Default Value: none (all allowed)

Examples:

  • 192.168.2.0/24 matches all IP addresses in the range of 192.168.2.0 to 192.168.2.255.
  • 10.0.0.1 matches only host 10.0.0.1.
  • 192.168.2.0/24,10.0.0.1 matches all IP addresses in the range of 192.168.2.0 to 192.168.2.255 and host 10.0.0.1.

hosts_deny​

Controls which hosts are denied access to the share when using host-based access control.

Value Type: string

Value Format: <IP|CIDR>,<IP|CIDR>,...

  • Values are separated by ,.
  • A value can be an either an IP address, or a subnet in CIDR notation.

Default Value: none (none denied)

Examples:

  • 192.168.2.0/24 matches all IP addresses in the range of 192.168.2.0 to 192.168.2.255.
  • 10.0.0.1 matches only host 10.0.0.1.
  • 192.168.2.0/24,10.0.0.1 matches all IP addresses in the range of 192.168.2.0 to 192.168.2.255 and host 10.0.0.1.

map_acls​

Controls the manner in which ACLs are stored for the files.

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

Default Value: xattr:raw

Examples:

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

map_attributes​

Controls the manner in which Windows attributes are stored for the files.

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 File Share Server.

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.

named_streams​

Enables/disables named streams for the 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

netname​

Sets the name by which the share is identified and accessed.

Value Type: string

Default Value: none.

Examples:

  • sh1 sets the net name to sh1.
  • MyShare sets the net name to MyShare.

oplock​

Controls the type of opportunistic locks to be issued.

Potentially Overrides Global Parameter: oplock
Ignored when global parameter oplock is set to disabled

Value Type: string

Value Format: <type>
Where <type> indicates the type of opportunistic lock to be issued:

  • none: Enables oplock/lease support and advertises the SMB2_GLOBAL_CAP_LEASING capability to clients. However, Fusion File Share Server server only grants NONE oplock/lease regardless of the value of RequestedOplockLevel.
  • read: Read-only oplock/lease support. This may be used to increase performance when the workload mostly consists of read operations.
  • all: Full oplock/lease support.

Default Value: all

path​

Sets the path or the name of the print queue for the share.

Value Type: string

Value Format: <path>
Where <path> is:

  • For shared directories: The directory on the server's file system to be shared.
  • For printer shares: The name of the print queue.

Default Value: none.

Examples:

  • /export/sh1, if the share type is disk, indicates that the shared directory is /export/sh1.
  • paperjam, if the share type is printer, indicates that the print queue is called paperjam.

permissions​

Controls the permissions for the share.

Value Type: string

Value Format: <id>:<access>, <id>:<access>, ...

  • <id> is the identifier to which its corresponding <access> applies. It can be:

    • Predefined groups (corresponding to similarly named standard Windows groups):
      • everyone: All users, excluding anonymous users.
      • anonymous: Anonymous users in a null session.
      • authenticatedusers: All authenticated users.
    • Username: A user on the domain or local machine
      • Example: johndoe
    • Group, prefixed by @:
      • Example: @staff
    • Security identifier (SID), prefixed by *S-:
      • Example: *S-1-1-0
    note

    User and group specification dependens on the authentication backend defined by the userdb_type global parameter.

  • <access> defines the access level granted to the identified user or group. It can be one of the following:

    • no: Denies all access.
    • read: Grants Read, ReadAttributes, ReadControl, and Execute permissions.
    • change: Grants all permissions granted by read, as well as the Write, WriteAttributes, AppendData, and Delete permissions.
    • full: Grants all permissions granted by change, as well as the DeleteChild, WriteDAC, and WriteOwner permissions.
    note

    For printer shares, <access> must be set to either full or change.

important

If an <id> cannot be resolved to a SID, it is ignored if <access> is read, change, or full. However, if <access> is no, the permission applies to all users, rendering the share inaccessible.

Moreover, Fusion File Share Server will continue attempting to resolve the <id> against the underlying authentication backend, such as Active Directory, which may slow down access to the share.

To ignore unresolved <id> values, you can set the share's ignore_unresolved_share_deny_permission parameter to true. However, this may grant unintended access, for example if <id> was misspelled.

Default Value: everyone:read

Examples:

  • everyone:full grants full access to `everyone``.
  • johndoe:full, @staff:change grants full access to user johndoe, and change access to all users in the staff group.
  • anonymous:read grants read access to anonymous users.

remark​

Sets a human-readable comment for the share.

Value Type: string

Default Value: none.

Examples:

  • My Awesome Share sets the remark to My Awesome Share.
  • Video Files sets the remark to Video Files.

security​

Sets the file security model for the share.

Value Type: string

Value Format: <mode>

Default Value: windows

security_descriptor​

Controls the permissions for the share using security descriptors.

Value Type: string

Value Format: SDDL string

Default Value: none

Examples:

  • O:SYG:SYD:(A;;FA;;;WD) grants full access to Everyone.
  • O:SYG:SYD:(A;;0x1200a9;;;WD) grants read only access to Everyone.
  • O:SYG:SYD:(A;;FA;;;AN) grants full access to anonymous users.

server​

Controls share scoping for the 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.

spool_path​

For printer shares, the path to the spool directory on the server's file system.

Value Type: string

Value Format: <path>
Where <path> is the path to the spool directory on the server's file system. When the share type is printer, this parameter must be set.

Default Value: none.

Examples:

  • /var/spool/tsmb sets the spool path to /var/spool/tsmb.

type​

Set the type of the share. Only necessary for printer shares.

Value Type: string

Value Format: disk|printer

  • disk: Indicates this share refers to a shared directory on the file system containing the share.
  • printer: Indicates that this share refers to a printer.

Default Value: disk

vfs​

Controls the VFS module used for file operations on the share.

Value Type: string

Value Format: <type>:<option>[,<option>,...]

  • <type> specifies the type of the VFS module to use. Currently, the only supported option is:
    • libc: the default VFS module for Linux.
  • <option> can be set to one of the following:
    • force_sync: opens each file with the O_SYNC flag to ensure that all data is written to disk before returning from a write operation. This option is useful for applications requiring strong durability guarantees, but it degrades performance. This option is required for clusters in active-passive mode.
    • nodirect: ignores client requests for direct I/O, bypassing the OS's page cache. This applies to FILE_NO_IMMEDIATE_BUFFERING on Windows, O_DIRECT on Linux, and F_NOCACHE on macOS. This option is likely to improve performance, but could disregard the client application's expectations, potentially resulting in undefined behavior. Use with caution.
    • lock: enables the propagation of byte-range locks to the underlying file system,allowing interoperability with other applications (such as NFS servers) that depend on byte-range locks. Note that this option may degrade performance.

Default Value: none (libc is configured to not use O_SYNC and to respect client's requests for direct I/O).

Examples:

  • libc:force_sync,nodirect will force Fusion File Share Server to open all files with the O_SYNC flag, and to ignore client's requests for direct I/O.

vfs_data_threads​

Controls the number of threads in the global pool for VFS data operations.

Potentially Overrides Global Parameter: vfs_data_threads

Value Type: integer

Value Format: <threads>
Determines the number of threads for VFS data operations in the share's pool. If set to 0:

  • If the share's vfs_metadata_threads is not set to 0, VFS operations will be executed on the share's data thread pool.
  • If the share's vfs_metadata_threads is also set to 0, VFS operations will be executed on the global pool, as specified in the global vfs_data_threads parameter.

Default Value: 1

vfs_fallocate_max​

Controls the maximum size of a file that can be allocated using fallocate().

Value Type: integer

Value Format: <bytes>
Where <bytes> is the maximum size of a file that will be allocated using fallocate.

Default Value: 0

vfs_fallocate_min​

Controls the minimum size of a file that can be allocated using fallocate().

Value Type: integer

Value Format: <bytes>
Where <bytes> is the minimum size of a file that will be allocated using fallocate.

Default Value: 0

vfs_metadata_threads​

Controls the number of threads in the global pool for VFS metadata operations.

Potentially Overrides Global Parameter: vfs_metadata_threads

Value Type: integer

Value Format: <threads>
Determines the number of threads for VFS metadata operations in the share's pool. If set to 0:

  • If the share's vfs_data_threads is not set to 0, VFS operations will be executed on the share's data thread pool.
  • If the share's vfs_data_threads is also set to 0, VFS operations will be executed on the global pool, as specified in the global vfs_metadata_threads parameter.

Default Value: 1

vfs_zerocopy_read​

Controls the use of zero-copy read operations for the share.

Value Type: boolean

Value Format: true|false

  • true: Enables zero-copy for read operations on the share.
  • false: Disables zero-copy for read operations on the share.

Default Value: false

vfs_zerocopy_write​

Controls the use of zero-copy write operations for the share.

Value Type: boolean

Value Format: true|false

  • true: Enables zero-copy for write operations on the share.
  • false: Disables zero-copy for write operations on the share.

Default Value: true

vss​

Enables or disables Volume Shadow Copy Service (VSS) for the share. Used in conjunction with vss_params.

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.

vss_params​

Controls additional parameters for Volume Shadow Copy Service (VSS) on the share. Used in conjunction with vss.

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.