Query options customize the results returned by a query method. More complete documentation with examples are covered in the "Query methods" section of the TrueNAS API documentation.
No Additional PropertiesExtra options are defined on a per-endpoint basis and are described in the documentation for the associated query method.
An array of field names describing the manner in which query results should be ordered. The field names may also have one of more of the following special prefixes: - (reverse sort direction), nulls_first: (place any null values at the head of the results list), nulls_last: (place any null values at the tail of the results list).
[
"size",
"-devname",
"nulls_first:-expiretime"
]
An array of field names specifying the exact fields to include in the query return. The dot character . may be used to explicitly select only subkeys of the query result.
[
"username",
"Authentication.status"
]
Return a numeric value representing the number of items that match the specified query-filters.
Return the JSON object of the first result matching the specified query-filters. The query fails if there specified query-filters return no results.
This specifies the beginning offset of the results array. When combined with the limit query-option it may be used to implement pagination of large results arrays. WARNING: some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.
This specifies the maximum number of results matching the specified query-filters to return. When combined wtih the offset query-option it may be used to implement pagination of large results arrays.
WARNING: Some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.
SMB share entry on the TrueNAS server.
No Additional PropertiesThis parameter sets the purpose of the SMB share. It controls how the SMB share behaves and what features are available through options. The DEFAULT_SHARE setting is best for most applications, and should be used, unless there is a specific reason to change it.
DEFAULT_SHARE: Set the SMB share for best compatibility with common SMB clients.
LEGACY_SHARE: Set the SMB share for compatibility with older TrueNAS versions. Automated backend migrations use this to help the administrator move to better-supported share settings. It should not be used for new SMB shares.
TIMEMACHINE_SHARE: The SMB share is presented to MacOS clients as a time machine target.
NOTE: aapl_extensions must be set in the global smb.config.
MULTIPROTOCOL_SHARE: The SMB share is configured for multi-protocol access. Set this if the path is shared through NFS, FTP, or used by containers or apps.
NOTE: This setting can reduce SMB share performance because it turns off some SMB features for safer interoperability with external processes.
TIME_LOCKED_SHARE: The SMB share makes files read-only through the SMB protocol after the set grace_period ends.
WARNING: This setting does not work if the path is accessed locally or if another SMB share without the TIME_LOCKED_SHARE purpose uses the same path.
WARNING: This setting might not meet regulatory requirements for write-once storage.
PRIVATE_DATASETS_SHARE: The server uses the specified dataset_naming_schema in options to make a new ZFS dataset when the client connects. The server uses this dataset as the share path during the SMB session.
EXTERNAL_SHARE: The SMB share is a DFS proxy to a share hosted on an external SMB server.
VEEAM_REPOSITORY_SHARE: The SMB share is a repository for Veeam Backup & Replication and supports Fast Clone.
NOTE: This feature is available only for TrueNAS Enterprise customers.
SMB share name. SMB share names are case-insensitive and must be unique, and are subject to the following restrictions:
A share name must be no more than 80 characters in length.
The following characters are illegal in a share name: \ / [ ] : | < > + = ; , * ? "
Unicode control characters are illegal in a share name.
The following share names are not allowed: global, printers, homes.
"SHARE"
"Macrodata_refinement"
Local server path to share by using the SMB protocol. The path must start with /mnt/ and must be in a ZFS pool.
Use the string EXTERNAL if the share works as a DFS proxy.
WARNING: The TrueNAS server does not check if external paths are reachable.
Must be at least 1 characters long
"EXTERNAL" "/mnt/dozer/SHARE"
"EXTERNAL"
If unset, the SMB share is not available over the SMB protocol.
Text field that is seen next to a share when an SMB client requests a list of SMB shares on the TrueNAS server.
"Mammalian nurturable"
If set, SMB clients cannot create or change files and directories in the SMB share.
NOTE: If set, the share path is still writeable by local processes or other file sharing protocols.
If set, the share is included when an SMB client requests a list of SMB shares on the TrueNAS server.
Read-only value indicating whether the share is located on a locked dataset.
Returns:
- True: The share is in a locked dataset.
- False: The share is not in a locked dataset.
- None: Lock status is not available because path locking information was not requested.
Settings for auditing SMB shares.
NOTE: If a user is a member of groups in the watch_list and the ignore_list, the watch_list has priority, and the SMB session is audited.
{
"enable": true,
"ignore_list": [],
"watch_list": [
"interns"
]
}
{
"enable": true,
"ignore_list": [
"automation"
],
"watch_list": []
}
Turn on auditing for the SMB share. SMB share auditing may not be enabled if enable_smb1 is true in the SMB service configuration.
Only audit the listed group accounts. If the list is empty, all groups will be audited.
No Additional ItemsMust be at least 1 characters long
[
"interns",
"contractors"
]
List of groups that will not be audited.
No Additional ItemsMust be at least 1 characters long
[
"automation",
"apps"
]
Additional configuration related to the configured SMB share purpose. If null, then the default options related to the share purpose will be applied.
These configuration options apply to shares with the LEGACY_SHARE purpose.
If set, deleted files are moved to per-user subdirectories in the .recycle directory. The SMB server creates the .recycle directory at the root of the SMB share if the file is in the same ZFS dataset as the share path. If the file is in a child ZFS dataset, the server uses the mountpoint of that dataset to create the .recycle directory.
NOTE: This feature does not work with recycle bin features in client operating systems.
WARNING: Do not use this feature instead of backups or ZFS snapshots.
"%D/%U"
A list of IP addresses or subnets that are allowed to access the SMB share. The EXCEPT keyword may be used to limit a wildcard list.
NOTE: Hostname lookups are disabled on the SMB server for performance reasons.
No Additional Items[
"192.168.0.200",
"150.203."
]
[
"150.203.15.0/255.255.255.0"
]
[
"150.203. EXCEPT 150.203.6.66"
]
A list of IP addresses or subnets that are not allowed to access the SMB share. The keyword ALL or the netmask 0.0.0.0/0 may be used to deny all by default.
[
"150.203.4."
]
[
"ALL"
]
[
"0.0.0.0/0"
]
If set, guest access to the share is allowed. This should not be used in production environments.
NOTE: If a user account does not exist, the SMB server maps access to the guest account.
WARNING: Additional client-side configuration downgrading security settings may be required in order to use this feature.
If set, support for SMB alternate data streams is enabled.
WARNING: This value should not be changed once data is written to the SMB share.
If set, support for SMB durable handles is enabled.
WARNING: This feature is incompatible with multiprotocol and local filesystem access.
If set, previous versions of files contained in ZFS snapshots are accessible through standard SMB protocol operations on previous versions of files.
If set, enable support for the File Server Remote VSS Protocol. This allows clients to manage snapshots for the specified SMB share.
Use the path to store user home directories. Each user has a personal home directory and share. Users cannot access other user directories when connecting to shares.
NOTE: This parameter changes the share name to homes. It also creates a dynamic share that mirrors the username of the user. Both shares use the same path. You can hide the homes share by turning off browsable. The dynamic user home share cannot be hidden.
WARNING: This parameter changes the global server configuration. The SMB server will not authenticate users without a valid home directory or shell.
If set, enable mapping of local filesystem ACLs to NT ACLs for SMB clients.
If set, SMB server will read and store file metadata in an on-disk format compatible with the legacy AFP file server.
WARNING: This should not be set unless the SMB server is sharing data that was originally written via the AFP protocol.
If set, MacOS clients can use the share as a time machine target.
If set, it defines the maximum size of a single time machine sparsebundle volume by limiting the reported disk size to the SMB client. A value of zero means no quota is applied to the share.
NOTE: Modern MacOS versions you set Time Machine quotas client-side. This gives more predictable server and client behavior.
Value must be greater or equal to 0 and lesser or equal to 109951162777600
If set, illegal NTFS characters commonly used by MacOS clients are stored with their native values on the SMB server's local filesystem.
NOTE: Files with illegal NTFS characters in their names may not be accessible to non-MacOS SMB clients.
WARNING: This value should not be changed once data is written to the SMB share.
This value is the Time Machine volume UUID for the SMB share. The TrueNAS server uses this value in the mDNS advertisement for the Time Machine share. MacOS clients may use it to identify the volume. When you create or update a share, setting this value to null makes the TrueNAS server generate a new UUID for the share.
Must be at least 1 characters long
"d12aafdc-a7ac-4e3c-8bbd-6001f7f19819"
Additional parameters to set on the SMB share. Parameters must be separated by the new-line character.
WARNING: These parameters are not validated and may cause undefined server behavior including data corruption or data loss.
WARNING: Auxiliary parameters are an unsupported configuration.
These configuration options apply to shares with the DEFAULT_SHARE purpose.
If set, illegal NTFS characters commonly used by MacOS clients are stored with their native values on the SMB server's local filesystem.
NOTE: Files with illegal NTFS characters in their names may not be accessible to non-MacOS SMB clients.
WARNING: This value should not be changed once data is written to the SMB share.
These configuration options apply to shares with the TIMEMACHINE_SHARE purpose.
If set, it defines the maximum size in bytes of a single time machine sparsebundle volume by limiting the reported disk size to the SMB client. A value of zero means no quota is set.
NOTE: Modern MacOS versions you set Time Machine quotas client-side. This gives more predictable server and client behavior.
Value must be greater or equal to 0 and lesser or equal to 109951162777600
If set, the server makes a ZFS snapshot of the share dataset when the client makes a new Time Machine backup.
If set, the server uses the dataset_naming_schema to make a new ZFS dataset when the client connects. The server uses this dataset as the share path during the SMB session.
NOTE: this setting requires the share path to be a dataset mountpoint.
The naming schema to use when auto_dataset_creation is specified. If you do not set a schema, the server uses %U (username) if it is not joined to Active Directory. If the server is joined to Active Directory it uses %D/%U (domain/username). See the VARIABLE SUBSTITUTIONS section in the smb.conf manpage for valid strings.
WARNING: ZFS dataset naming rules are more restrictive than normal path rules. For example, if %u is specified then the character \ may be inserted in the username (which is not supported in ZFS).
"%D/%U"
This value is the Time Machine volume UUID for the SMB share. The TrueNAS server uses this value in the mDNS advertisement for the Time Machine share. MacOS clients may use it to identify the volume. When you create or update a share, setting this value to null makes the TrueNAS server generate a new UUID for the share.
Must be at least 1 characters long
"d12aafdc-a7ac-4e3c-8bbd-6001f7f19819"
These configuration options apply to shares with the MULTIPROTOCOL_SHARE purpose.
If set, illegal NTFS characters commonly used by MacOS clients are stored with their native values on the SMB server's local filesystem.
NOTE: Files with illegal NTFS characters in their names may not be accessible to non-MacOS SMB clients.
WARNING: This value should not be changed once data is written to the SMB share.
These configuration options apply to shares with the TIME_LOCKED_SHARE purpose.
Time in seconds when write access to the file or directory is allowed.
Value must be greater or equal to 60 and lesser or equal to 15552000
If set, illegal NTFS characters commonly used by MacOS clients are stored with their native values on the SMB server's local filesystem.
NOTE: Files with illegal NTFS characters in their names may not be accessible to non-MacOS SMB clients.
WARNING: This value should not be changed once data is written to the SMB share.
These configuration options apply to shares with the PRIVATE_DATASETS_SHARE purpose.
The naming schema to use. If you do not set a schema, the server uses %U (username) if it is not joined to Active Directory. If the server is joined to Active Directory it uses %D/%U (domain/username).
WARNING: ZFS dataset naming rules are more restrictive than normal path rules.
"%D/%U"
Set the specified ZFS quota (in gibibytes) on new datasets. If the value is zero, TrueNAS disables automatic quotas for the share.
Value must be greater or equal to 0
10
If set, illegal NTFS characters commonly used by MacOS clients are stored with their native values on the SMB server's local filesystem.
NOTE: Files with illegal NTFS characters in their names may not be accessible to non-MacOS SMB clients.
WARNING: This value should not be changed once data is written to the SMB share.
These configuration options apply to shares with the EXTERNAL_SHARE purpose.
This is the path to the external server and share. Each server entry must include a full domain name or IP address and share name. Separate the server and share with the \ character.
WARNING: The SMB server and TrueNAS middleware do not check if external paths are reachable.
No Additional ItemsMust be at least 1 characters long
[
"192.168.0.200\\SHARE"
]
[
"SERVER1.MYDOM.INTERNAL\\SHARE"
]
[
"SERVER1.MYDOM.INTERNAL\\SHARE, SERVER2.MYDOM.INTERNAL\\SHARE"
]
These configuration options apply to shares with the VEEAM_REPOSITORY_SHARE purpose.
{
"auto_snapshot": true
}
{
"auto_quota": 100
}