Share Configuration
The second-level help menu displays the subcommands supported by the first-level commands.
For example, in dynamic share configuration, the second-level help menu for the ‘share’ commands is:
$ /usr/bin/tsmb-cfg share help
Usage: tsmb-cfg share <COMMAND> [PARAMETERS]
Available share commands are:
- ‘add’ – Register a share in the server
- ‘del’ – Delete a share from the server
- ‘update’ – Update an existing share in the server
- ‘list’ – List existing shares in the server
- ‘help’ – Display this help info
Use ‘tsmb-cfg share COMMAND [-h|--help]’ for more command-specific information.
Adding a New Share
You can register a new share using the ‘add’ subcommand. For a list of supported options, run:
$ /usr/bin/tsmb-cfg share add -h
By default, registering a new share requires some mandatory options like the path of the shared resource and netname (used to identify the shared resource over the network).
Example:
$ /usr/bin/tsmb-cfg share add -n <name of share> -p <path to share>
You may also use the following optional parameters with the ‘add’ subcommand:
| Title | Title |
|---|---|
| --administrative BOOL | Set the share as an administrative share. These are special shares like C$ or D$ that represent the root of a volume. Default: false |
| --audit-level NUM | Level of audit logging for the share. |
| --ca BOOL | Enable continuous availability on the share. Default: false |
| --ca-params STR | CA parameters. MANDATORY for continuously available shares. |
| --dfs BOOL | Enable DFS on the share. Default: false |
| --vss BOOL | Enable VSS on the share. Default: false |
| --vss-params STR | VSS parameters |
| --case-insensitive BOOL | Enable case-insensitive access on the share. Default: false |
| --force-l2oplock BOOL | Enable issuing of exclusive caching rights on share. Default: false |
| --encrypt BOOL | Enable encryption on share. Default: false |
| --access-based-enumeration BOOL | Enable access permission based hiding of directory contents during enumeration. Default: false |
| --permissions STR | Share access permissions. Default: ”every-one:read” |
| --security-descriptor STR | Share access permissions in SDDL format. |
| --remark STR | Additional information about the shared resource. |
| --type STR | Type of the share to be added. Default: ”disk” |
| --files-allow STR | Set of patterns used as a filter to allow accessing and listing files and directories |
| --files-deny STR | Set of patterns used as a filter to deny accessing and listing files and directories. |
| --compression-deny STR | Set of patterns to recognize files for which compression should not be performed. |
| --map-attributes STR | Method for storing SMB file attributes. |
| --map-acls STR | Method for storing ACLs. |
| --security STR | Share security model. |
| --vfs STR | VFS parameters in the following format: <type>:[<parameter=value>,*]´, where type is VFS type to use for the share. |
| --vfs-zerocopy-write BOOL | Enable zero-copy writes if supported. Default: true |
| --vfs-zerocopy-read BOOL | Enable zero-copy reads if supported. Default: true |
| --vfs-clone-file-range BOOL | Enable clone_file_range for server side copy if supported. Default: true |
| --vfs-data-threads NUM | The number of share specific VFS data threads. |
| --vfs-metadata-threads NUM | The number of share specific VFS metadata threads. |
| --vfs-fallocate-min NUM | Minimum threshold (in bytes) for using fallocate() system call. |
| --vfs-fallocate-max NUM | Maximum threshold (in bytes) for using fallocate() system call. |
| --create-mask MASK | Maximum allowed POSIX permission for a file. If not specified then no mask is applied. |
| --force-create-mode MASK | Minimal required POSIX permissions for a file. If not specified then no mask is applied. |
| --directory-mask MASK | Maximum allowed POSIX permission for a directory. If not specified then no mask is applied. |
| --force-directory-mode MASK | Minimal required POSIX permissions for a directory. If not specified then no mask is applied. |
| --enable-oplock BOOL | Set oplocks (leases) on a share. Default: true |
Refer to the help (--help) for a more detailed explanation.
Deleting a Share
You can delete an existing share using the ‘del’ subcommand. Run the following for a list of parameters or options supported by ‘del’:
$ /usr/bin/tsmb-cfg share del -h
To delete a share, run:
$ /usr/bin/tsmb-cfg share del -n <name_of_share>
A delete operation performed on a non-existent share will fail.
Updating a Share
You can change the configuration for an existing share using the ‘update’ subcommand.
Run the following for a list of parameters or options supported by ‘update’:
$ /usr/bin/tsmb-cfg share update -h
You may ‘update’ an existing share with the following parameters:
| Title | Title |
|---|---|
| -n, --name=STRING | Netname to identify the shared resource [Mandatory] |
| --force-l2oplock BOOL | Enable issuing exclusive caching rights on share. Default: false |
| --encrypt BOOL | Enable encryption on share. Default: false |
| --access-based-enumeration BOOL | Enable access permission based hiding of directory contents during enumeration. Default: false |
| --permissions STR | Share access permissions. Default: ”everyone:read” |
| --security-descriptor STR | Share access permissions in SDDL format. |
| --remark STR | Additional information about the shared resource. |
| --files-allow STR | Set of patterns used as a filter to allow accessing and listing files and directories. Each entry in the filter MUST be separated by a pipe ‘ | ’ and each entry can contain characters such as ‘ ? ’ and ‘ * ’ to denote wildcards when filters multiple files. |
| --files-deny STR | Set of patterns used as a filter to deny accessing and listing files and directories. |
| --compression-deny STR | Set of patterns to recognize files for which compression should not be performed. |
| --vfs-params STR | Set new values of VFS parameters on the share. Parameters are in the following format: [<parameter=value>,*] |
| --case-insensitive BOOL | Set case-insensitive access on the share. |
| --create-mask MASK | Maximum allowed POSIX permission for a regular file. |
| --force-create-mode MASK | Minimal required POSIX permissions for a file. |
| --directory-mask MASK | Maximum allowed POSIX permission for a directory. |
| --force-directory-mode MASK | Minimal required POSIX permissions for a directory. |
| --enable-oplock BOOL | Set oplocks (leases) on a share. Default: true |
| --help | Display help message. |
There are limitations on the options that can be updated using this command. These limitations are imposed by the protocol’s technical document. The tool allows you to dynamically update the user permissions and the remark associated with an existing share. This limitation is imposed so that if a user is connected to an existing share, the user does not need to reconnect to the share to notice the effects of the new user-permissions. The changes are effective immediately on-the-fly.
During an update if certain fields are not specified, then the unspecified fields will be left untouched in the server.
Listing Shares
You can list all the existing shares using the ‘list’ subcommand. Run the following for a list of available options:
$ /usr/bin/tsmb-cfg share list -h
The supported parameter(s) to ‘list’ all existing shares are:
| Title | Title |
|---|---|
| --info-level NUM | The info level to retrieve while listing share(s) [DEFAULT: 1] The supported levels are:
|
| --format STR | Specify the format in which to output the share info. The supported formats are: raw, json [DEFAULT: raw] |
| -n STR, --name STR | Filter share based on netname when listing. |
| --server STR | Filter share(s) based on server when listing scoped share(s.) |
| --help | Display help message. |