Skip to main content

Authorization and Access Management

Share Permissions​

Share permissions are the primary method for controlling access to shares. Configured at the share level, they apply uniformly to all files and directories within the share. While share permissions provide a simple way to manage access, they lack the granularity of more advanced access control mechanisms.

Permissions can be configured in the configuration file or with the CLI when adding or updating shares by specifying the relevant parameters.

Share Parameter Permissions

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.

Setting Permissions on a Share Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the permissions parameter to the desired value, similar to the following example:

[share]
netname = MyShare
path = /export/share
permissions = everyone:full
[/share]

Adding a Share with Permissions Using the CLI​

When adding a share using the CLI, you can specify the permissions using the -P or --permissions parameter. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share -P everyone:full

Updating a Share's Permissions Using the CLI​

To update a share's permissions using the CLI, use the tsmb-cfg share update command with the -P or --permissions parameter. For example:

sudo tsmb-cfg share update -n MyShare -P everyone:read

Security Descriptors​

Security descriptors provide more granular control over share access than standard permissions. Administrators can use SDDL (Security Descriptor Definition Language) strings to define detailed access rules, specifying who can access a share and what actions they can perform based on a wide range of criteria and attributes.

Security descriptors can be configured in the configuration file, and using the CLI when adding or updating shares by specifying the relevant parameter.

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

Setting Security Descriptors on a Share Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the security_descriptor parameter to the desired value, similar to the following example:

[share]
netname = MyShare
path = /export/share
security_descriptor = O:SYG:SYD:(A;;FA;;;WD)
[/share]

Adding a Share with Security Descriptors Using the CLI​

When adding a share using the CLI, you can specify the security descriptor using the --security-descriptor parameter. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share --security-descriptor "O:SYG:SYD:(A;;FA;;;WD)"

Updating a Share's Security Descriptors Using the CLI​

To update a share's security descriptors using the CLI, use the tsmb-cfg share update command with the --security-descriptor parameter. For example:

sudo tsmb-cfg share update -n MyShare --security-descriptor "O:SYG:SYD:(A;;FA;;;WD)"

File Security Mode​

The file security mode is a global setting that controls how Fusion File Share Server handles file permissions. For each share, you can choose one of the following three modes:

  • Windows: In Windows mode, Fusion File Share Server stores and enforces file permissions based on Windows ACLs. This is the default mode, and it conforms to the behavior expected by Windows clients.
  • POSIX:
    In POSIX mode, Fusion File Share Server stores and enforces file permissions based on the connected user's UID/GID (see POSIX ID Mapping) and the file's mode bits (i.e., the standard UNIX rwx permissions).
  • None:
    In None mode, Fusion File Share Server does not enforce file permissions, making all files accessible to users according to the share permissions.

Windows Security Mode​

The Windows security mode makes Fusion File Share Server behave like a Windows server when authorizing access to files:

  1. Fusion File Share Server stores the ACL for each file created on a share, according to the ACL storage settings.
  2. Upon file access, Fusion File Share Server checks the the file's ACLs, to determine the permissions, based on the the user's SIDs provided by the domain controller during authentication.
note

If extended attributes are not supported on the shared file's path, Fusion File Share Server will attempt to determine the file's security descriptor by reading the parent directory's security descriptor, recursively up to the share's root. If the share's root directory lacks a security descriptor, Fusion File Share Server will use the other bits of the share root's mode (interpreted as the Everyone group) to authorize access to the file.

POSIX Security Mode​

The POSIX mode disregards any ACLs stored on the files, and does not store ACLs for new files.

When authorizing access, Fusion File Share Server considers only the file's mode bits (i.e., the standard UNIX rwx permissions), and the UID/GID of the connected user, as determined by the POSIX ID Mapping settings. Access is then authorized according to the standard UNIX permissions model:

  1. If the user's UID matches the file's owner UID, the user's access is determined by the owner bits.
  2. If the user's UID does not match the file's owner UID, but the user's GID matches the file's group GID, the user's access is determined by the group bits.
  3. If the user's UID and GID do not match the file's owner UID and group GID, the user's access is determined by the other bits.
note

Unlike with the Windows mode, Fusion File Share Server does not check the parent directory's permissions when determining access to a file.

None Security Mode​

In this mode, no access permission checks are performed on files. Access is determined by the share permissions.

Share Parameter Security Mode

Value Type: string

Value Format: <mode>

Default Value: windows

Creating a Share with a Specific Security Mode Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the security parameter to the desired value, similar to the following example:

[share]
netname = MyShare
path = /export/share
security = posix
[/share]

Adding a Share with a Specific Security Mode Using the CLI​

When adding a share using the CLI, you can specify the security mode using the -S or --security parameter. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share -S posix

Hiding Shares​

Fusion File Share Server allows you to mark shares as hidden. Hidden shares are not listed when browsing the server, but users with the share's name and proper permissions can still access them.

Hidden shares can be configured in the configuration file, and using the CLI when adding or updating shares by specifying the relevant parameter.

Share Parameter Hiding a Share

Value Type: boolean

Value Format: true|false

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

Default Value: false

Hiding a Share Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the hidden parameter to true to hide the share, similar to the following example:

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

Adding a Hidden Share Using the CLI​

When adding a share using the CLI, use the tsmb-cfg share add command with the --hidden parameter to hide the share. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share --hidden true

Updating a Share to Hide It Using the CLI​

To update a share to hide it using the CLI, use the tsmb-cfg share update command with the --hidden parameter. For example:

sudo tsmb-cfg share update -n MyShare --hidden true

Veto Files​

The veto files feature allows administrators to hide files from clients and restrict access to them. It controls both visibility and access, ensuring that even if a user knows the name of a restricted file, they cannot access it unless it matches the allowed pattern set.

Files that are permitted through the veto rules remain subject to the share's permissions and the ACLs applied to the files.

The feature is controlled by two lists, the Allowed Files, and the Denied Files:

  • If neither Allowed Files nor Denied Files are set, all files are accessible, based on the share's permissions and the ACLs on the files.
  • If only Allowed Files is set, only files that are on the list will be accessible.
  • If only Denied Files is set, all files except those that are on the list will be accessible.
  • If both Allowed Files and Denied Files are set, only files on the Allowed Files list but not the Denied Files list will be accessible. In other words, the Denied Files list takes precedence.

This feature is controlled by the following parameters:

Share Parameter Allowed and Denied Lists

Allowed List:

Denied List:

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

Allowed List Default Value: *

Denied List 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.

Setting Veto Files on a Share Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the files_allow and files_deny parameters to the desired values, similar to the following example:

[share]
netname = MyShare
path = /export/share
files_allow = *.txt|*.doc
files_deny = secret.*
[/share]

In this example, access is allowed to files with the .txt and .doc extensions, but denied to files starting with secret.. Therefore, even though .txt and .doc files are allowed, access to secret.txt and secret.doc files will be denied.

Adding a Share with Veto Files Using the CLI​

When adding a share using the CLI, you can specify the veto files using the -a or --files-allow and -d or --files-deny parameters. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share -a "*.txt|*.doc" -d "*.tmp|*.bak"

Updating a Share's Veto Files Using the CLI​

To update a share's veto files using the CLI, use the tsmb-cfg share update command with the -a or --files-allow and -d or --files-deny parameters. For example:

sudo tsmb-cfg share update -n MyShare -a "*.txt|*.doc" -d "*.tmp|*.bak"

Access Based Enumeration​

Access based enumeration allows you to control which shares, files, and folders are visible to users based on their permissions. When enabled, users see resources to which they have at least read access, as defined by their permissions or security descriptors.

Access based enumeration can be enabled either globally or on specific shares:

  • When enabled globally, users browsing the server root will only see shares they have permission to access.
  • When enabled on a share, users will only see files and folders they have permission to access within that share.

While improving both user experience and security, access based enumeration may affect performance, as the server must evaluate permissions for each share, file, and folder before displaying them.

Global Access Based Share Enumeration​

Global Parameter Access Based Share Enumeration

Value Type: boolean

Value Format: true|false

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

Default Value: false

Enabling Access Based Share Enumeration Using the Configuration File​

In the [global] section of the configuration file, set the access_based_share_enumeration parameter to the desired value, similar to the following example:

[global]
. . .
access_based_share_enumeration = true
. . .
[/global]

Updating the Access Based Share Enumeration Setting Using the CLI​

To update the access based share enumeration setting using the CLI, use the tsmb-cfg global update command with the --access-based-share-enumeration parameter. For example:

sudo tsmb-cfg global update --access-based-share-enumeration true

Per-Share Access Based Enumeration​

Share Parameter Access Based File Enumeration

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

Enabling Access Based Enumeration on a Share Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the access_based_enumeration parameter to the desired value, similar to the following example:

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

Adding a Share with Access Based Enumeration Using the CLI​

When adding a share using the CLI, you can specify the access based enumeration setting using the --access-based-enumeration parameter. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share \
    --access-based-enumeration true

Updating a Share's Access Based Enumeration Setting Using the CLI​

To update a share's access based enumeration setting using the CLI, use the tsmb-cfg share update command with the --access-based-enumeration parameter. For example:

sudo tsmb-cfg share update -n MyShare \
    --access-based-enumeration true

Host-Based Access Control​

Host-based access control allows you to restrict access to a share based on the IP addresses or IP address ranges of clients. However, allowing hosts to access a share does not supersede the permissions or security descriptors set on the share. This means that even if a host is granted access, the user must still have the correct permissions to access the share.

The feature is controlled by two lists, the Allowed Hosts, and the Denied Hosts:

  • If neither Allowed Hosts nor Denied Hosts are set, all hosts are allowed access to the share.
  • If only Allowed Hosts is set, only hosts that are on the list or in the specified ranges will be allowed access to the share.
  • If only Denied Hosts is set, all hosts except those on the list or in the specified ranges will be allowed access to the share.
  • If both Allowed Hosts and Denied Hosts are set, only hosts that are on the Allowed Hosts list but not on the Denied Hosts list will be allowed access to the share. In other words, the Denied Hosts list takes precedence.
Share Parameter Allowed and Denied Hosts

Allowed Hosts:

Denied Hosts:

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.

Allowed Hosts Default Value: none (all allowed)

Denied Hosts 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.

Setting Host-Based Access Control on a Share Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the hosts_allow and hosts_deny parameters to the desired values, similar to the following example:

[share]
netname = MyShare
path = /export/share
hosts_allow = 192.168.0.0/16
hosts_deny = 192.168.2.0/24
[/share]

In this example, access is allowed to hosts in the 192.168.0.0 to 192.168.255.255 range, except for hosts in the 192.168.2.0 to 192.168.2.255 range.

Adding a Share with Host-Based Access Control Using the CLI​

When adding a share using the CLI, you can specify the host-based access control using --hosts-allow and --hosts-deny parameters. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share \
    --hosts-allow 192.168.0.0/16 \
    --hosts-deny 192.168.2.0/24

Updating a Share's Host-Based Access Control Using the CLI​

To update a share's host-based access control using the CLI, use the tsmb-cfg share update command with the --hosts-allow and --hosts-deny parameters. For example:

sudo tsmb-cfg share update -n MyShare \
    --hosts-allow 192.168.0.0/16 \
    --hosts-deny 192.168.2.0/24

POSIX Permissions at File Creation​

You can to control the maximum and minimum POSIX permissions for file creation by using the following parameters: the file/directory creation mask, and the forced file/directory mode.

At creation, the effective permissions are determined by the following calculation:

Permissions = (Default Permissions AND Mask) OR Forced Mode.

To illustrate, let's assume the following configuration:

  • File Creation Mask: 0750: Owner has full rwx permissions, group has r-x permissions, and others have no permissions.
  • File Forced Mode: 0644: Owner has rw- permissions, group has r-- permissions, and others have r-- permissions as well.

Assume a file is created, that based on its path should inherit the permissions 0666 from its parent directory.

The effective permissions are calculated as:

                        OCTAL          BINARY              MODE
                                                        usr grp oth
                        –––––      –––––––––––––––      ––––––––––––

Default Permissions   = 0666       000 110 110 110      rw- rw- rw-

                        AND        AND                  AND

Mask                  = 0750       000 111 101 000      rwx r-x ---

                        ––––       –––––––––––––––      ––––––––––––

With Mask             = 0640       000 110 100 000      rw- r-- ---

                        OR         OR                   OR

Forced Mode           = 0644       000 110 100 100      rw- r-- r--

                        ––––       –––––––––––––––      ––––––––––––

Effective Permissions = 0644       000 110 100 100      rw- r-- r--

After applying the mask, the effective permissions are 0640, but since a forced mode is specified, the effective permissions are 0644, since it's applied after the mask.

You can specify the creation mask and forced mode for both files and directories.

Also, for the forced mode , you can specify the first octal digit to signify addition of the following:

  • setuid bit for files (4) – indicates that the file should be executed with the permissions of the file's owner, rather than the user who is executing the file (ignored when the user is not mapped to a valid POSIX ID).
  • setgid bit for directories (2)– indicates that files and directories created in this directory should be created with the group ID of the directory, rather than the user's primary group ID.
  • sticky bit for directories (1) – indicates that the directory should be created with the sticky bit set, which would permit deleting or renaming files in the directory only by their owner.
Share Parameter File Creation Mask

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.
Share Parameter File Forced Mode

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.
Share Parameter Directory Creation Mask

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.
Share Parameter Directory Forced Mode

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.

Setting POSIX Permissions at File Creation Using the Configuration File​

In the relevant[share] section of the configuration file for the share you want to configure, set the create_mask, forced_create_mode, forced_directory_mode, and forced_file_mode parameters to the desired values, similar to the following example:

[share]
netname = MyShare
path = /export/share
create_mask = 0750
forced_create_mode = 0644
forced_directory_mode = 0755
forced_file_mode = 0644
[/share]

Adding a Share with POSIX Permissions at File Creation Using the CLI​

When adding a share using the CLI, you can specify the POSIX permissions at file creation using the --create-mask, --force-create-mode, --directory-mask, and --force-directory-mode parameters. For example:

sudo tsmb-cfg share add -n MyShare \
    -p /export/share \
    --create-mask 0750 \
    --force-create-mode 0644 \
    --directory-mask 0755 \
    --force-directory-mode 0644

Updating a Share's POSIX Permissions at File Creation Using the CLI​

To update a share's POSIX permissions at file creation using the CLI, use the tsmb-cfg share update command with the --create-mask, --force-create-mode, --directory-mask, and --force-directory-mode parameters. For example:

sudo tsmb-cfg share update -n MyShare \
    --create-mask 0750 \
    --force-create-mode 0644 \
    --directory-mask 0755 \
    --force-directory-mode 0644