sharing.smb.get_instance

Returns instance matching id. If id is not found, Validation error is raised.

Please see query method documentation for options.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: id

id

Type: integer
Parameter 2: options

options

Type: object Default: {}

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 Properties

Relationships

Type: boolean Default: true

Extend

Default: null

Type: string
Type: null

Extend Fk

Type: array of string Default: []
No Additional Items
Each item of this array must be:
Type: string

Extend Context

Default: null

Type: string
Type: null

Prefix

Default: null

Type: string
Type: null

Extra

Type: object Default: {}

Extra options are defined on a per-endpoint basis and are described in the documentation for the associated
query method.

Order By

Type: array of string Default: []

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).

No Additional Items
Each item of this array must be:
Type: string

Example:

[
    "size",
    "-devname",
    "nulls_first:-expiretime"
]

Select

Type: array Default: []

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.

No Additional Items
Each item of this array must be:

Type: string
Type: array
No Additional Items
Each item of this array must be:
Type: object

Example:

[
    "username",
    "Authentication.status"
]

Count

Type: boolean Default: false

Return a numeric value representing the number of items that match the specified query-filters.

Get

Type: boolean Default: false

Return the JSON object of the first result matching the specified query-filters. The query fails
if there specified query-filters return no results.

Offset

Type: integer Default: 0

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.

Limit

Type: integer Default: 0

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.

Force Sql Filters

Type: boolean Default: false

SmbShareEntry

Type: object

SMB share entry on the TrueNAS server.

No Additional Properties

Id

Type: integer

Purpose

Type: enum (of string) Default: "DEFAULT_SHARE"

This 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.

Must be one of:
  • "DEFAULT_SHARE"
  • "LEGACY_SHARE"
  • "TIMEMACHINE_SHARE"
  • "MULTIPROTOCOL_SHARE"
  • "TIME_LOCKED_SHARE"
  • "PRIVATE_DATASETS_SHARE"
  • "EXTERNAL_SHARE"

Name

Type: string

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.
Examples:

"SHARE"

"Macrodata_refinement"

Path


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.

Type: string

Must be at least 1 characters long

Type: const
Must be one of:
  • "EXTERNAL"
Specific value: "EXTERNAL"

Examples:

"/mnt/dozer/SHARE"

"EXTERNAL"

Enabled

Type: boolean Default: true

If unset, the SMB share is not available over the SMB protocol.

Comment

Type: string Default: ""

Text field that is seen next to a share when an SMB client requests a list of SMB shares on the TrueNAS
server.


Example:

"Mammalian nurturable"

Readonly

Type: boolean Default: false

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.

Browsable

Type: boolean Default: true

If set, the share is included when an SMB client requests a list of SMB shares on the TrueNAS server.

Access Based Share Enumeration

Type: boolean Default: false

If set, the share is only included when an SMB client requests a list of shares on the SMB server if
the share (not filesystem) access control list (see sharing.smb.getacl) grants access to the user.

Locked

Type: boolean

Read-only value showing if the share is in a locked dataset.

SmbAuditConfig

Type: object

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.

No Additional Properties
Examples:

{
    "enable": true,
    "ignore_list": [],
    "watch_list": [
        "interns"
    ]
}

{
    "enable": true,
    "ignore_list": [
        "automation"
    ],
    "watch_list": []
}

Enable

Type: boolean Default: false

Turn on auditing for the SMB share. SMB share auditing may not be enabled if enable_smb1 is True
in the SMB service configuration.

Watch List

Type: array of string Default: []

Only audit the listed group acounts. If the list is empty, all groups will be audited.

No Additional Items
Each item of this array must be:
Type: string

Must be at least 1 characters long


Example:

[
    "interns",
    "contractors"
]

Ignore List

Type: array of string Default: []

List of groups that will not be audited.

No Additional Items
Each item of this array must be:
Type: string

Must be at least 1 characters long


Example:

[
    "automation",
    "apps"
]

Options

Default: null

Additional configuration related to the configured SMB share purpose. If None, then the default
options related to the share purpose will be applied.


LegacyOpt

Type: object

These configuration options apply to shares with the LEGACY_SHARE purpose.

No Additional Properties

Recyclebin

Type: boolean Default: false

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.

Path Suffix

Default: null

Type: string
Type: null

Example:

"%D/%u"

Hostsallow

Type: array of string Default: []

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
Each item of this array must be:
Type: string

Examples:

[
    "192.168.0.200",
    "150.203."
]

[
    "150.203.15.0/255.255.255.0"
]

[
    "150.203. EXCEPT 150.203.6.66"
]

Hostsdeny

Type: array of string Default: []

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.

No Additional Items
Each item of this array must be:
Type: string

Examples:

[
    "150.203.4."
]

[
    "ALL"
]

[
    "0.0.0.0/0"
]

Guestok

Type: boolean Default: false

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.

Streams

Type: boolean Default: true

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.

Durablehandle

Type: boolean Default: true

If set, support for SMB durable handles is enabled.

WARNING: this feature is incompatible with multiprotocol and local filesystem access.

Shadowcopy

Type: boolean Default: true

If set, previous versions of files contained in ZFS snapshots are accessible through standard SMB protocol
operations on previous versions of files.

Fsrvp

Type: boolean Default: false

If set, enable support for the File Server Remote VSS Protocol. This allows clients to manage
snapshots for the specified SMB share.

Home

Type: boolean Default: false

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.

Acl

Type: boolean Default: true

If set, enable mapping of local filesystem ACLs to NT ACLs for SMB clients.

Afp

Type: boolean Default: false

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.

Timemachine

Type: boolean Default: false

If set, MacOS clients can use the share as a time machine target.

Timemachine Quota

Type: integer Default: 0

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.

Aapl Name Mangling

Type: boolean Default: false

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.

Vuid

Default: null

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.

Type: string

Must be at least 1 characters long

Type: null

Example:

"d12aafdc-a7ac-4e3c-8bbd-6001f7f19819"

Auxsmbconf

Type: string Default: ""

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.

DefaultOpt

Type: object

These configuration options apply to shares with the DEFAULT_SHARE purpose.

No Additional Properties

Aapl Name Mangling

Type: boolean Default: false

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.

TimeMachineOpt

Type: object

These configuration options apply to shares with the TIMEMACHINE_SHARE purpose.

No Additional Properties

Timemachine Quota

Type: integer Default: 0

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.

Auto Snapshot

Type: boolean Default: false

If set, the server makes a ZFS snapshot of the share dataset when the client makes a new
Time Machine backup.

Auto Dataset Creation

Type: boolean Default: false

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.

Dataset Naming Schema

Default: null

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.

Type: string
Type: null

Example:

"%D/%u"

Vuid

Default: null

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.

Type: string

Must be at least 1 characters long

Type: null

Example:

"d12aafdc-a7ac-4e3c-8bbd-6001f7f19819"

MultiprotocolOpt

Type: object

These configuration options apply to shares with the MULTIPROTOCOL_SHARE purpose.

No Additional Properties

Aapl Name Mangling

Type: boolean Default: false

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.

TimeLockedOpt

Type: object

These configuration options apply to shares with the TIMELOCKEDSHARE purpose.

No Additional Properties

Grace Period

Type: integer Default: 900

Time in seconds when write access to the file or directory is allowed.

Aapl Name Mangling

Type: boolean Default: false

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.

PrivateDatasetOpt

Type: object

These configuration options apply to shares with the PRIVATEDATASETSSHARE purpose.

No Additional Properties

Dataset Naming Schema

Default: null

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.

Type: string
Type: null

Example:

"%D/%u"

Auto Quota

Type: integer Default: 0

Set the specified ZFS quota (in gibibytes) on new datasets. If the value is zero, TrueNAS disables
automatic quotas for the share.
Example:

10

Aapl Name Mangling

Type: boolean Default: false

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.

ExternalOpt

Type: object

These configuration options apply to shares with the EXTERNAL_SHARE purpose.

No Additional Properties

Remote Path

Type: array of string

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 Items
Each item of this array must be:
Type: string

Must be at least 1 characters long


Examples:

[
    "192.168.0.200\\SHARE"
]

[
    "SERVER1.MYDOM.INTERNAL\\SHARE"
]

[
    "SERVER1.MYDOM.INTERNAL\\SHARE, SERVER2.MYDOM.INTERNAL\\SHARE"
]
Type: null

Examples:

{
    "auto_snapshot": true
}

{
    "auto_quota": 100
}


Required roles: SHARING_SMB_READ