# sharing.smb.update

Update the SMB share identified by `id`.

Renaming a share or changing its `path` is disruptive: existing SMB sessions on the affected share are forcibly closed so that the change can take effect.

Note

Setting raw `smb.conf` auxiliary parameters (`options.auxsmbconf`) is restricted to callers with full administrative privileges. Auxiliary parameters that would break the SMB server are rejected and the original configuration is restored.

Type: object

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: id

#### id

Type: integer

ID of the SMB share to update.

##### Parameter 2: data

#### data

Type: object

Updated SMB share configuration data.

No Additional Properties

##

#### Purpose

Type: enum (of string)

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.

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

- `FCP_SHARE`: The SMB share is a used for Final Cut Pro storage. This feature automatically configures the share to provide storage according to Apple support guidelines described in https://support.apple.com/en-ca/101919. NOTE: `aapl_extensions` must be set in the global `smb.config`. WARNING: This feature forcibly enables `aapl_name_mangling` on the SMB share which may cause unexpected behavior for data that was written without this feature enabled.

##### Must be one of:

- "DEFAULT_SHARE"
- "LEGACY_SHARE"
- "TIMEMACHINE_SHARE"
- "MULTIPROTOCOL_SHARE"
- "TIME_LOCKED_SHARE"
- "PRIVATE_DATASETS_SHARE"
- "EXTERNAL_SHARE"
- "VEEAM_REPOSITORY_SHARE"
- "FCP_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.

## Any of

Type: string

Must be at least `1` characters long

Type: const
Specific value: `"EXTERNAL"`
Examples:

    "/mnt/dozer/SHARE"

    "EXTERNAL"

##

#### Enabled

Type: boolean

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

##

#### Comment

Type: string

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

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

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

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.

##

#### SmbAuditConfig

Type: object

Audit configuration for monitoring SMB share access and operations.

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

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

## Any of

## One of

#### LegacyOpt

Type: object

These configuration options apply to shares with the `LEGACY_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"LEGACY_SHARE"`

##

#### 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

Path suffix template for dynamic path generation. Uses SMB variable substitution patterns like `%D` (domain) and `%U` (username).

## Any of

Type: string

Must be at least `1` characters long

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.

Value must be greater or equal to `0` and lesser or equal to `109951162777600`

##

#### 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 null makes the TrueNAS server generate a new UUID for the share.

## Any of

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.

Must be at most `2147483647` characters long

#### DefaultOpt

Type: object

These configuration options apply to shares with the `DEFAULT_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"DEFAULT_SHARE"`

##

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

##

#### 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"
    ]

#### TimeMachineOpt

Type: object

These configuration options apply to shares with the `TIMEMACHINE_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"TIMEMACHINE_SHARE"`

##

#### Timemachine Quota

Type: integer Default: 0

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`

##

#### 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. For example, if `%u` is specified then the character `\` may be inserted in the username (which is not supported in ZFS).

## Any of

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 null makes the TrueNAS server generate a new UUID for the share.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Example:

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

##

#### 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"
    ]

#### MultiprotocolOpt

Type: object

These configuration options apply to shares with the `MULTIPROTOCOL_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"MULTIPROTOCOL_SHARE"`

##

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

##

#### 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"
    ]

#### TimeLockedOpt

Type: object

These configuration options apply to shares with the `TIME_LOCKED_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"TIME_LOCKED_SHARE"`

##

#### Grace Period

Type: integer Default: 900

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`

##

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

##

#### 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"
    ]

#### PrivateDatasetOpt

Type: object

These configuration options apply to shares with the `PRIVATE_DATASETS_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"PRIVATE_DATASETS_SHARE"`

##

#### Dataset Naming Schema

Default: null

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.

## Any of

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.

Value must be greater or equal to `0`

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.

##

#### 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"
    ]

#### ExternalOpt

Type: object

These configuration options apply to shares with the `EXTERNAL_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"EXTERNAL_SHARE"`

##

#### 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"
    ]

#### VeeamRepositoryOpt

Type: object

These configuration options apply to shares with the `VEEAM_REPOSITORY_SHARE` purpose.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"VEEAM_REPOSITORY_SHARE"`

##

#### 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"
    ]

#### FCPStorageOpt

Type: object

These configuration options apply to shares with the `FCP_SHARE` purpose as a storage location for Final Cut Pro data.

No Additional Properties

##

#### Purpose

Type: const
Specific value: `"FCP_SHARE"`

##

#### Aapl Name Mangling

Type: const Default: true

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.

Specific value: `true`

##

#### 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"
    ]

Type: null
Examples:

    {
        "auto_snapshot": true
    }

    {
        "auto_quota": 100
    }

##

#### SharingSMBEntry

Type: object

The updated SMB share configuration.

No Additional Properties

##

#### Id

Type: integer

Unique identifier for this SMB share.

##

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

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

- `FCP_SHARE`: The SMB share is a used for Final Cut Pro storage. This feature automatically configures the share to provide storage according to Apple support guidelines described in https://support.apple.com/en-ca/101919. NOTE: `aapl_extensions` must be set in the global `smb.config`. WARNING: This feature forcibly enables `aapl_name_mangling` on the SMB share which may cause unexpected behavior for data that was written without this feature enabled.

##### Must be one of:

- "DEFAULT_SHARE"
- "LEGACY_SHARE"
- "TIMEMACHINE_SHARE"
- "MULTIPROTOCOL_SHARE"
- "TIME_LOCKED_SHARE"
- "PRIVATE_DATASETS_SHARE"
- "EXTERNAL_SHARE"
- "VEEAM_REPOSITORY_SHARE"
- "FCP_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.

## Any of

Type: string

Must be at least `1` characters long

Type: const
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

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.

## Any of

Type: boolean
Type: null

##

#### SmbAuditConfig

Type: object

Audit configuration for monitoring SMB share access and operations.

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 accounts. 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 null, then the default options related to the share purpose will be applied.

## Any of

## One of

#### 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

Path suffix template for dynamic path generation. Uses SMB variable substitution patterns like `%D` (domain) and `%U` (username).

## Any of

Type: string

Must be at least `1` characters long

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.

Value must be greater or equal to `0` and lesser or equal to `109951162777600`

##

#### 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 null makes the TrueNAS server generate a new UUID for the share.

## Any of

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.

Must be at most `2147483647` characters long

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

##

#### 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"
    ]

#### 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 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`

##

#### 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. For example, if `%u` is specified then the character `\` may be inserted in the username (which is not supported in ZFS).

## Any of

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 null makes the TrueNAS server generate a new UUID for the share.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Example:

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

##

#### 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"
    ]

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

##

#### 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"
    ]

#### TimeLockedOpt

Type: object

These configuration options apply to shares with the `TIME_LOCKED_SHARE` purpose.

No Additional Properties

##

#### Grace Period

Type: integer Default: 900

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`

##

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

##

#### 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"
    ]

#### PrivateDatasetOpt

Type: object

These configuration options apply to shares with the `PRIVATE_DATASETS_SHARE` purpose.

No Additional Properties

##

#### Dataset Naming Schema

Default: null

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.

## Any of

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.

Value must be greater or equal to `0`

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.

##

#### 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"
    ]

#### 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"
    ]

#### VeeamRepositoryOpt

Type: object

These configuration options apply to shares with the `VEEAM_REPOSITORY_SHARE` purpose.

No Additional Properties

##

#### 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"
    ]

#### FCPStorageOpt

Type: object

These configuration options apply to shares with the `FCP_SHARE` purpose as a storage location for Final Cut Pro data.

No Additional Properties

##

#### Aapl Name Mangling

Type: const Default: true

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.

Specific value: `true`

##

#### 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"
    ]

Type: null
Examples:

    {
        "auto_snapshot": true
    }

    {
        "auto_quota": 100
    }

Required roles: SHARING_SMB_WRITE