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.
TIMELOCKEDSHARE: The SMB share makes files read-only through the SMB protocol after the set graceperiod ends.
WARNING: This setting does not work if the path is accessed locally or if another SMB share without the
TIMELOCKED_SHARE purpose uses the same path. WARNING: This setting might not meet regulatory requirements for
write-once storage.
PRIVATEDATASETSSHARE: 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.
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 showing if the share is in a locked dataset.
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 acounts. 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 None, then the default
options related to the share purpose will be applied.
These configuration options apply to shares with the LEGACY_SHARE purpose.
No Additional Properties"LEGACY_SHARE" 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.
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 None 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.
No Additional Properties"DEFAULT_SHARE" 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.
No Additional Properties"TIMEMACHINE_SHARE" If set, it defines the maximum size of a single time machine sparsebundle volume by limiting the
reported disk size to the SMB client.
NOTE: Modern MacOS versions you set Time Machine quotas client-side. This gives more predictable
server and client behavior.
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.
"%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 None 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.
No Additional Properties"MULTIPROTOCOL_SHARE" 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 TIMELOCKEDSHARE purpose.
No Additional Properties"TIME_LOCKED_SHARE" Time in seconds when write access to the file or directory is allowed.
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 PRIVATEDATASETSSHARE purpose.
No Additional Properties"PRIVATE_DATASETS_SHARE" 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).
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.
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.
No Additional Properties"EXTERNAL_SHARE" 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"
]
{
"auto_snapshot": true
}
{
"auto_quota": 100
}
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.
TIMELOCKEDSHARE: The SMB share makes files read-only through the SMB protocol after the set graceperiod ends.
WARNING: This setting does not work if the path is accessed locally or if another SMB share without the
TIMELOCKED_SHARE purpose uses the same path. WARNING: This setting might not meet regulatory requirements for
write-once storage.
PRIVATEDATASETSSHARE: 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.
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 showing if the share is in a locked dataset.
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 acounts. 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 None, then the default
options related to the share purpose will be applied.
These configuration options apply to shares with the LEGACY_SHARE purpose.
No Additional Properties"LEGACY_SHARE" 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.
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 None 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.
No Additional Properties"DEFAULT_SHARE" 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.
No Additional Properties"TIMEMACHINE_SHARE" If set, it defines the maximum size of a single time machine sparsebundle volume by limiting the
reported disk size to the SMB client.
NOTE: Modern MacOS versions you set Time Machine quotas client-side. This gives more predictable
server and client behavior.
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.
"%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 None 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.
No Additional Properties"MULTIPROTOCOL_SHARE" 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 TIMELOCKEDSHARE purpose.
No Additional Properties"TIME_LOCKED_SHARE" Time in seconds when write access to the file or directory is allowed.
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 PRIVATEDATASETSSHARE purpose.
No Additional Properties"PRIVATE_DATASETS_SHARE" 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).
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.
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.
No Additional Properties"EXTERNAL_SHARE" 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"
]
{
"auto_snapshot": true
}
{
"auto_quota": 100
}