# directoryservices.update

This method is a job.

Type: object

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: directoryservices_update

#### directoryservices_update

Type: object

DirectoryServicesUpdateArgs parameters.

No Additional Properties

##

#### Service Type

The pre-existing directory service type to which to bind TrueNAS. Select ACTIVEDIRECTORY to join an Active Directory domain. Select IPA to join a FreeIPA domain. Select LDAP to bind to one or more OpenLDAP-compatible servers.

## Any of

Type: enum (of string)

##### Must be one of:

- "ACTIVEDIRECTORY"
- "IPA"
- "LDAP"

Type: null

##

#### Credential

Credential used to bind to the specified directory service. Kerberos credentials are required for Active Directory or IPA domains. Generic LDAP environments support various authentication methods. Available methods depend on the remote LDAP server configuration. If Kerberos credentials are selected for LDAP, GSSAPI binds replace plain LDAP binds. Use Kerberos or mutual TLS authentication when possible for better security.

The following credential types are supported based on `service_type`:

`ACTIVEDIRECTORY` service_type: `KERBEROS_USER` and `KERBEROS_PRINCIPAL`.

`LDAP` service_type: `LDAP_PLAIN`, `LDAP_ANONYMOUS`, `LDAP_MTLS`, `KERBEROS_USER`, and `KERBEROS_PRINCIPAL`. NOTE: prior configuration of kerberos realm is required in order to use kerberos credentials with the `LDAP` `service_type`.

`IPA` service_type: `KERBEROS_USER` and `KERBEROS_PRINCIPAL`. NOTE: `KERBEROS_USER` should be used when initially joining an IPA domain.

## Any of

## One of

#### CredKRBUser

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for Kerberos user authentication.

Specific value: `"KERBEROS_USER"`

##

#### Username

Type: string

Username of the account to use to create a kerberos ticket for authentication to directory services. This account must exist on the domain controller.

Must be at least `1` characters long

##

#### Password

Type: string

The password for the user account that will obtain the kerberos ticket.

Must be at least `1` characters long

#### CredKRBPrincipal

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for Kerberos principal authentication.

Specific value: `"KERBEROS_PRINCIPAL"`

##

#### Principal

Type: string

A kerberos principal is a unique identity to which Kerberos can assign tickets. The specified kerberos principal must have an entry within a keytab on the TrueNAS server.

Must be at least `1` characters long

#### CredLDAPPlain

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for LDAP plain text authentication.

Specific value: `"LDAP_PLAIN"`

##

#### Binddn

Type: string

Distinguished name to use for LDAP authentication.

##

#### Bindpw

Type: string

Password for the bind DN used for LDAP authentication.

Must be at least `1` characters long

#### CredLDAPAnonymous

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Anonymous LDAP authentication with no credentials required.

Specific value: `"LDAP_ANONYMOUS"`

#### CredLDAPMTLS

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for LDAP mutual TLS authentication.

Specific value: `"LDAP_MTLS"`

##

#### Client Certificate

Type: string

The client certificate name used for mutual TLS authentication to the remote LDAP server.

Must be at least `1` characters long

Type: null
Examples:

    {
        "binddn": "uid=truenasserver,ou=Users,dc=ldap01,dc=internal",
        "bindpw": "Canary",
        "credential_type": "LDAP_PLAIN"
    }

    {
        "credential_type": "LDAP_ANONYMOUS"
    }

    {
        "client_certificate": "ldap01_client_cert",
        "credential_type": "LDAP_MTLS"
    }

    {
        "credential_type": "KERBEROS_USER",
        "password": "Canary",
        "username": "truenas_user"
    }

    {
        "credential_type": "KERBEROS_PRINCIPAL",
        "principal": "truenas@LDAP01.INTERNAL"
    }

##

#### Enable

Type: boolean

Enable the directory service.

If TrueNAS has never joined the specified domain (IPA or Active Directory), setting this to True causes TrueNAS to attempt to join the domain.

NOTE: The domain join process for Active Directory and IPA will make changes to the domain such as creating a new computer account for the TrueNAS server and creating DNS records for TrueNAS.

##

#### Enable Account Cache

Type: boolean

Enable backend caching for user and group lists. If enabled, then directory services users and groups will be presented as choices in the UI dropdowns and in API responses for user and group queries. This setting also controls whether users and groups appear in getent results. Disable this setting to reduce load on the directory server when necessary.

##

#### Enable Dns Updates

Type: boolean

Enable automatic DNS updates for the TrueNAS server in the domain via nsupdate and gssapi / TSIG.

##

#### Timeout

Type: integer

The timeout value for DNS queries that are performed as part of the join process and NETWORK_TIMEOUT for LDAP requests.

Value must be greater or equal to `5` and lesser or equal to `60`

##

#### Kerberos Realm

Name of kerberos realm used for authentication to the directory service. If set to null, then Kerberos is not used for binding to the directory service. When joining an Active Directory or IPA domain for the first time, the realm is detected and configured automatically if not specified.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Configuration

The service_type specific configuration for the directory sevices plugin.

## Any of

## One of

#### ActiveDirectoryConfig

Type: object
No Additional Properties

##

#### Service Type

Type: const
Specific value: `"ACTIVEDIRECTORY"`

##

#### Hostname

Type: string

Hostname of TrueNAS server to register in Active Directory. Example: "truenasnyc".

Must be at least `1` characters long

##

#### Domain

Type: string

The full DNS domain name of the Active Directory domain. This must not be a domain controller. Example: "mydomain.internal".

Must be at least `1` characters long

##

#### PrimaryDomainIdmap

Type: object
Default:
{ "builtin": { "name": null, "range_high": 100000000, "range_low": 90000001 }, "idmap_domain": { "idmap_backend": "RID", "name": null, "range_high": 200000000, "range_low": 100000001, "sssd_compat": false } }

Configuration for mapping Active Directory accounts to accounts on the TrueNAS server. The exact settings may vary based on other servers and Linux clients in the domain. Defaults are suitable for new deployments without existing support for unix-like operating systems.

No Additional Properties
Example:

    {
        "builtin": {
            "range_high": 100000000,
            "range_low": 90000001
        },
        "idmap_domain": {
            "idmap_backend": "RID",
            "name": "MYDOMAIN",
            "range_high": 200000000,
            "range_low": 100000001
        }
    }

##

#### BuiltinDomainTdb

Type: object
Default:
{ "name": null, "range_low": 90000001, "range_high": 100000000 }

UID and GID range configuration for automatically generated accounts linked to well-known and BUILTIN accounts on Windows servers.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 90000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 100000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Domain

Default:
{ "name": null, "range_low": 100000001, "range_high": 200000000, "idmap_backend": "RID", "sssd_compat": false }

This configuration defines how domain accounts joined to TrueNAS are mapped to Unix UIDs and GIDs on the TrueNAS server. Most TrueNAS deployments use the RID backend, which algorithmically assigns UIDs and GIDs based on the Active Directory account SID. Another common option is the AD backend, which reads predefined Active Directory LDAP schema attributes that assign explicit UID and GID numbers to accounts.

## One of

#### AD_Idmap

Type: object

The AD backend reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions. The administrator must add mappings for users and groups in Active Directory before use.

NOTE: these schema extensions are not present by default in Active Directory.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for Active Directory RFC2307 schema integration.

Specific value: `"AD"`

##

#### Schema Mode

Type: enum (of string)

The schema mode the idmap backend uses to query Active Directory for user and group information. The RFC2307 schema applies to Windows Server 2003 R2 and newer. The Services for Unix (SFU) schema applies to versions before Windows Server 2003 R2.

##### Must be one of:

- "RFC2307"
- "SFU"
- "SFU20"

##

#### Unix Primary Group

Type: boolean Default: false

Defines if the user's primary group is fetched from SFU attributes or the Active Directory primary group. If True, the TrueNAS server uses the `gidNumber` LDAP attribute. If False, it uses the `primaryGroupID` LDAP attribute.

##

#### Unix Nss Info

Type: boolean Default: false

If True, the login shell and home directory are retrieved from LDAP attributes. If False, or if the Active Directory LDAP entry lacks SFU attributes, the home directory defaults to `/var/empty`.

#### LDAP_Idmap

Type: object

The LDAP backend reads and writes UID / GID mapping tables from an external LDAP server.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for external LDAP server mapping.

Specific value: `"LDAP"`

##

#### Ldap Base Dn

Type: string

Directory base suffix to use for mapping UIDs and GIDs to SIDs.

##

#### Ldap User Dn

Type: string

Defines the user DN to be used for authentication to the LDAP server.

##

#### Ldap User Dn Password

Type: string

Secret to use for authenticating the user specified by `ldap_user_dn`.

Must be at least `1` characters long

##

#### Ldap Url

Type: string

LDAP server to use for the idmap entries.

##

#### Readonly

Type: boolean Default: true

If readonly is set to True then TrueNAS will not attempt to write new idmap entries.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RFC2307_Idmap

Type: object

The RFC2307 backend reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only. Use the `AD` idmap backend if the server is an Active Directory domain controller.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RFC2307 LDAP attribute mapping.

Specific value: `"RFC2307"`

##

#### Ldap Url

Type: string

The LDAP URL used to access the LDAP server.

##

#### Ldap User Dn

Type: string

Defines the DN used to authenticate to the LDAP server.

##

#### Ldap User Dn Password

Type: string

The password used to authenticate the account specified in ldapuserdn.

Must be at least `1` characters long

##

#### Bind Path User

Type: string

The search base that contains user objects in the LDAP server.

##

#### Bind Path Group

Type: string

The search base that contains group objects in the LDAP server.

##

#### User Cn

Type: boolean Default: false

If set, query the CN attribute instead of the UID attribute for the user name in LDAP.

##

#### Ldap Realm

Type: boolean Default: false

Append @realm to the CN for groups. Also append it to users if user_cn is specified.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RID_Idmap

Type: object

The RID backend uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low. RID values in an Active Directory domain can be large, especially as the domain ages. Administrators should configure a range large enough to cover the current RID values assigned by the RID master. One way to do this is to check the RID of a recently created account in Active Directory. For example, if the RID is 500000, the range must include at least 500000 Unix IDs (for example, 1000000 to 2000000).

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RID-based algorithmic mapping.

Specific value: `"RID"`

##

#### Sssd Compat

Type: boolean Default: false

Generate an idmap low range using the algorithm from SSSD. This works if the domain uses only a single SSSD idmap slice, and is sufficient if the domain uses only a single SSSD idmap slice.

##

#### Site

Default: null

The Active Directory site where the TrueNAS server is located. TrueNAS detects this automatically during the domain join process.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Computer Account Ou

Default: null

Use this setting to override the default organizational unit (OU) in which the TrueNAS computer account is created during the domain join. Use it to set a custom location for TrueNAS computer accounts.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Example:

    "TRUENAS_SERVERS/NYC"

##

#### Use Default Domain

Type: boolean Default: false

Controls if the system removes the domain prefix from Active Directory user and group names. If enabled, users appear as "administrator" instead of "EXAMPLE\administrator". In most cases, disable this (default) to avoid name conflicts between Active Directory and local accounts.

##

#### Enable Trusted Domains

Type: boolean Default: false

Enable support for trusted domains. If True, then separate trusted domain configuration must be set for all trusted domains.

##

#### Trusted Domains

Type: array Default: []

Configuration for trusted domains.

No Additional Items

##### Each item of this array must be:

Default:
{ "name": null, "range_low": 100000001, "range_high": 200000000, "idmap_backend": "RID", "sssd_compat": false }

## One of

#### AD_Idmap

Type: object

The AD backend reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions. The administrator must add mappings for users and groups in Active Directory before use.

NOTE: these schema extensions are not present by default in Active Directory.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for Active Directory RFC2307 schema integration.

Specific value: `"AD"`

##

#### Schema Mode

Type: enum (of string)

The schema mode the idmap backend uses to query Active Directory for user and group information. The RFC2307 schema applies to Windows Server 2003 R2 and newer. The Services for Unix (SFU) schema applies to versions before Windows Server 2003 R2.

##### Must be one of:

- "RFC2307"
- "SFU"
- "SFU20"

##

#### Unix Primary Group

Type: boolean Default: false

Defines if the user's primary group is fetched from SFU attributes or the Active Directory primary group. If True, the TrueNAS server uses the `gidNumber` LDAP attribute. If False, it uses the `primaryGroupID` LDAP attribute.

##

#### Unix Nss Info

Type: boolean Default: false

If True, the login shell and home directory are retrieved from LDAP attributes. If False, or if the Active Directory LDAP entry lacks SFU attributes, the home directory defaults to `/var/empty`.

#### LDAP_Idmap

Type: object

The LDAP backend reads and writes UID / GID mapping tables from an external LDAP server.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for external LDAP server mapping.

Specific value: `"LDAP"`

##

#### Ldap Base Dn

Type: string

Directory base suffix to use for mapping UIDs and GIDs to SIDs.

##

#### Ldap User Dn

Type: string

Defines the user DN to be used for authentication to the LDAP server.

##

#### Ldap User Dn Password

Type: string

Secret to use for authenticating the user specified by `ldap_user_dn`.

Must be at least `1` characters long

##

#### Ldap Url

Type: string

LDAP server to use for the idmap entries.

##

#### Readonly

Type: boolean Default: true

If readonly is set to True then TrueNAS will not attempt to write new idmap entries.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RFC2307_Idmap

Type: object

The RFC2307 backend reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only. Use the `AD` idmap backend if the server is an Active Directory domain controller.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RFC2307 LDAP attribute mapping.

Specific value: `"RFC2307"`

##

#### Ldap Url

Type: string

The LDAP URL used to access the LDAP server.

##

#### Ldap User Dn

Type: string

Defines the DN used to authenticate to the LDAP server.

##

#### Ldap User Dn Password

Type: string

The password used to authenticate the account specified in ldapuserdn.

Must be at least `1` characters long

##

#### Bind Path User

Type: string

The search base that contains user objects in the LDAP server.

##

#### Bind Path Group

Type: string

The search base that contains group objects in the LDAP server.

##

#### User Cn

Type: boolean Default: false

If set, query the CN attribute instead of the UID attribute for the user name in LDAP.

##

#### Ldap Realm

Type: boolean Default: false

Append @realm to the CN for groups. Also append it to users if user_cn is specified.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RID_Idmap

Type: object

The RID backend uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low. RID values in an Active Directory domain can be large, especially as the domain ages. Administrators should configure a range large enough to cover the current RID values assigned by the RID master. One way to do this is to check the RID of a recently created account in Active Directory. For example, if the RID is 500000, the range must include at least 500000 Unix IDs (for example, 1000000 to 2000000).

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RID-based algorithmic mapping.

Specific value: `"RID"`

##

#### Sssd Compat

Type: boolean Default: false

Generate an idmap low range using the algorithm from SSSD. This works if the domain uses only a single SSSD idmap slice, and is sufficient if the domain uses only a single SSSD idmap slice.

Examples:

    {
        "idmap_backend": "RID",
        "name": "BROOK",
        "range_high": 300000000,
        "range_low": 200000001
    }

    {
        "idmap_backend": "RID",
        "name": "DARVO",
        "range_high": 400000000,
        "range_low": 300000001
    }

#### IPAConfig

Type: object
No Additional Properties

##

#### Service Type

Type: const
Specific value: `"IPA"`

##

#### Target Server

Type: string

The name of the IPA server that TrueNAS uses to build URLs when it joins or leaves the IPA domain. Example: "ipa.example.internal".

Must be at least `1` characters long

##

#### Hostname

Type: string

Hostname of TrueNAS server to register in IPA during the join process. Example: "truenasnyc".

Must be at least `1` characters long

##

#### Domain

Type: string

The domain of the IPA server. Example "ipa.internal".

Must be at least `1` characters long

##

#### Basedn

Type: string

The base DN to use when performing LDAP operations. Example: "dc=example,dc=internal".

##

Default: null

Settings for the IPA SMB domain. TrueNAS detects these settings during IPA join. Some IPA domains may not include SMB schema configuration.

## Any of

#### IPA_SMBDomain

Type: object

This is a special idmap backend used when TrueNAS joins an IPA domain. The remote IPA server provides the configuration information during the domain join process.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for System Security Services Daemon integration.

Specific value: `"SSS"`

##

#### Domain Name

Default: null

Name of the SMB domain as defined in the IPA configuration for the IPA domain to which TrueNAS is joined.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Example:

    "IXDOM.INTERNAL"

##

#### Domain Sid

Default: null

The domain SID for the IPA domain to which TrueNAS is joined.

## Any of

Type: string
Type: null
Example:

    "S-1-5-21-3696504179-2855309571-923743039"

Type: null

##

#### Validate Certificates

Type: boolean Default: true

If `False`, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### LDAPConfig

Type: object
No Additional Properties

##

#### Service Type

Type: const
Specific value: `"LDAP"`

##

#### Server Urls

Type: array of string

List of LDAP server URIs used for LDAP binds. Each URI must begin with ldap:// or ldaps:// and may use either a DNS name or an IP address. Example: `['ldaps://myldap.domain.internal']`.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Basedn

Type: string

The base DN to use when performing LDAP operations. Example: `"dc=domain,dc=internal"`.

##

#### Starttls

Type: boolean Default: false

Establish TLS by transmitting a StartTLS request to the server.

##

#### Validate Certificates

Type: boolean Default: true

If `False`, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

##

#### Schema

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

The type of LDAP attribute schema that the remote LDAP server uses.

##### Must be one of:

- "RFC2307"
- "RFC2307BIS"

##

#### LDAPSearchBases

Type: object
Default:
{ "base_user": null, "base_group": null, "base_netgroup": null }

Alternative LDAP search base settings. These settings define where to find user, group, and netgroup entries. If unspecified (the default), TrueNAS uses the `basedn` to find users. groups, and netgroups. Use these settings only if the LDAP server uses a non-standard LDAP schema or if you want to limit the accounts available on TrueNAS.

No Additional Properties

##

#### Base User

Default: null

Optional base DN to limit LDAP user searches. If null (default) then the `base_dn` is used.

## Any of

Type: string
Type: null

##

#### Base Group

Default: null

Optional base DN to limit LDAP group searches. If null (default) then the `base_dn` is used.

## Any of

Type: string
Type: null

##

#### Base Netgroup

Default: null

Optional base DN to limit LDAP netgroup searches. If null (default) then the `base_dn` is used.

## Any of

Type: string
Type: null

##

#### LDAPAttributeMaps

Type: object
Default:
{ "passwd": { "user_gecos": null, "user_gid": null, "user_home_directory": null, "user_name": null, "user_object_class": null, "user_shell": null, "user_uid": null }, "shadow": { "shadow_expire": null, "shadow_inactive": null, "shadow_last_change": null, "shadow_max": null, "shadow_min": null, "shadow_warning": null }, "group": { "group_gid": null, "group_member": null, "group_object_class": null }, "netgroup": { "netgroup_member": null, "netgroup_object_class": null, "netgroup_triple": null } }

Optional LDAP attribute mapping for LDAP servers that do not follow RFC2307 or RFC2307BIS. Use this only if the LDAP server is non-standard.

No Additional Properties

##

#### LDAPMapPasswd

Type: object
Default:
{ "user_object_class": null, "user_name": null, "user_uid": null, "user_gid": null, "user_gecos": null, "user_home_directory": null, "user_shell": null }

LDAP attribute mappings for passwd/user entries.

No Additional Properties

##

#### User Object Class

Default: null

The user entry object class in LDAP.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Name

Default: null

The LDAP attribute for the user's login name.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Uid

Default: null

The LDAP attribute for the user's id.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Gid

Default: null

The LDAP attribute for the user's primary group id.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Gecos

Default: null

The LDAP attribute for the user's gecos field.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Home Directory

Default: null

The LDAP attribute for the user's home directory.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Shell

Default: null

The LDAP attribute for the path to the user's default shell.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### LDAPMapShadow

Type: object
Default:
{ "shadow_last_change": null, "shadow_min": null, "shadow_max": null, "shadow_warning": null, "shadow_inactive": null, "shadow_expire": null }

LDAP attribute mappings for shadow password entries.

No Additional Properties

##

#### Shadow Last Change

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (date of the last password change).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Min

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (minimum password age).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Max

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (maximum password age).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Warning

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (password warning period).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Inactive

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (password inactivity period).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Expire

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (account expiration date).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### LDAPMapGroup

Type: object
Default:
{ "group_object_class": null, "group_gid": null, "group_member": null }

LDAP attribute mappings for group entries.

No Additional Properties

##

#### Group Object Class

Default: null

The LDAP object class for group entries.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group Gid

Default: null

The LDAP attribute for the group's id.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group Member

Default: null

The LDAP attribute for the names of the group's members.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### LDAPMapNetgroup

Type: object
Default:
{ "netgroup_object_class": null, "netgroup_member": null, "netgroup_triple": null }

LDAP attribute mappings for netgroup entries.

No Additional Properties

##

#### Netgroup Object Class

Default: null

The LDAP object class for netgroup entries.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Netgroup Member

Default: null

The LDAP attribute for the netgroup's members.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Netgroup Triple

Default: null

The LDAP attribute for netgroup triples (host, user, domain).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Auxiliary Parameters

Default: null

Additional paramaters to add to the SSSD configuration.

WARNING: TrueNAS does not check the validity of these parameters. Incorrect values can cause production outages when they are applied or after an operating system upgrade.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Type: null
Examples:

    {
        "computer_account_ou": "TRUENAS_SERVERS",
        "domain": "ACME.INTERNAL",
        "hostname": "TRUENASZ356"
    }

    {
        "basedn": "dc=ipadom,dc=internal",
        "domain": "ipadom.internal",
        "hostname": "TRUENASZ345",
        "target_server": "ipasrv5.ipadom.internal"
    }

    {
        "basedn": "dc=ipadom,dc=internal",
        "server_urls": [
            "ldap.ipadom.internal"
        ]
    }

##

#### Force

Type: boolean

Bypass validation to check if a server with this hostname and NetBIOS name is already registered in an IPA or Active Directory domain. Use this option, for example, to replace an existing server with a TrueNAS server. Do not use the force parameter indiscriminately. Using it may cause production outages for clients that rely on the existing server.

##

#### DirectoryServicesEntry

Type: object

The updated directory services configuration.

No Additional Properties

##

#### Id

Type: integer

Unique identifier for the directory services configuration.

##

#### Service Type

The pre-existing directory service type to which to bind TrueNAS. Select ACTIVEDIRECTORY to join an Active Directory domain. Select IPA to join a FreeIPA domain. Select LDAP to bind to one or more OpenLDAP-compatible servers.

## Any of

Type: enum (of string)

##### Must be one of:

- "ACTIVEDIRECTORY"
- "IPA"
- "LDAP"

Type: null

##

#### Credential

Credential used to bind to the specified directory service. Kerberos credentials are required for Active Directory or IPA domains. Generic LDAP environments support various authentication methods. Available methods depend on the remote LDAP server configuration. If Kerberos credentials are selected for LDAP, GSSAPI binds replace plain LDAP binds. Use Kerberos or mutual TLS authentication when possible for better security.

The following credential types are supported based on `service_type`:

`ACTIVEDIRECTORY` service_type: `KERBEROS_USER` and `KERBEROS_PRINCIPAL`.

`LDAP` service_type: `LDAP_PLAIN`, `LDAP_ANONYMOUS`, `LDAP_MTLS`, `KERBEROS_USER`, and `KERBEROS_PRINCIPAL`. NOTE: prior configuration of kerberos realm is required in order to use kerberos credentials with the `LDAP` `service_type`.

`IPA` service_type: `KERBEROS_USER` and `KERBEROS_PRINCIPAL`. NOTE: `KERBEROS_USER` should be used when initially joining an IPA domain.

## Any of

## One of

#### CredKRBUser

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for Kerberos user authentication.

Specific value: `"KERBEROS_USER"`

##

#### Username

Type: string

Username of the account to use to create a kerberos ticket for authentication to directory services. This account must exist on the domain controller.

Must be at least `1` characters long

##

#### Password

Type: string

The password for the user account that will obtain the kerberos ticket.

Must be at least `1` characters long

#### CredKRBPrincipal

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for Kerberos principal authentication.

Specific value: `"KERBEROS_PRINCIPAL"`

##

#### Principal

Type: string

A kerberos principal is a unique identity to which Kerberos can assign tickets. The specified kerberos principal must have an entry within a keytab on the TrueNAS server.

Must be at least `1` characters long

#### CredLDAPPlain

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for LDAP plain text authentication.

Specific value: `"LDAP_PLAIN"`

##

#### Binddn

Type: string

Distinguished name to use for LDAP authentication.

##

#### Bindpw

Type: string

Password for the bind DN used for LDAP authentication.

Must be at least `1` characters long

#### CredLDAPAnonymous

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Anonymous LDAP authentication with no credentials required.

Specific value: `"LDAP_ANONYMOUS"`

#### CredLDAPMTLS

Type: object
No Additional Properties

##

#### Credential Type

Type: const

Credential type identifier for LDAP mutual TLS authentication.

Specific value: `"LDAP_MTLS"`

##

#### Client Certificate

Type: string

The client certificate name used for mutual TLS authentication to the remote LDAP server.

Must be at least `1` characters long

Type: null
Examples:

    {
        "binddn": "uid=truenasserver,ou=Users,dc=ldap01,dc=internal",
        "bindpw": "Canary",
        "credential_type": "LDAP_PLAIN"
    }

    {
        "credential_type": "LDAP_ANONYMOUS"
    }

    {
        "client_certificate": "ldap01_client_cert",
        "credential_type": "LDAP_MTLS"
    }

    {
        "credential_type": "KERBEROS_USER",
        "password": "Canary",
        "username": "truenas_user"
    }

    {
        "credential_type": "KERBEROS_PRINCIPAL",
        "principal": "truenas@LDAP01.INTERNAL"
    }

##

#### Enable

Type: boolean

Enable the directory service.

If TrueNAS has never joined the specified domain (IPA or Active Directory), setting this to True causes TrueNAS to attempt to join the domain.

NOTE: The domain join process for Active Directory and IPA will make changes to the domain such as creating a new computer account for the TrueNAS server and creating DNS records for TrueNAS.

##

#### Enable Account Cache

Type: boolean Default: true

Enable backend caching for user and group lists. If enabled, then directory services users and groups will be presented as choices in the UI dropdowns and in API responses for user and group queries. This setting also controls whether users and groups appear in getent results. Disable this setting to reduce load on the directory server when necessary.

##

#### Enable Dns Updates

Type: boolean Default: true

Enable automatic DNS updates for the TrueNAS server in the domain via nsupdate and gssapi / TSIG.

##

#### Timeout

Type: integer Default: 10

The timeout value for DNS queries that are performed as part of the join process and NETWORK_TIMEOUT for LDAP requests.

Value must be greater or equal to `5` and lesser or equal to `60`

##

#### Kerberos Realm

Default: null

Name of kerberos realm used for authentication to the directory service. If set to null, then Kerberos is not used for binding to the directory service. When joining an Active Directory or IPA domain for the first time, the realm is detected and configured automatically if not specified.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Configuration

Default: null

The service_type specific configuration for the directory sevices plugin.

## Any of

## One of

#### ActiveDirectoryConfig

Type: object
No Additional Properties

##

#### Hostname

Type: string

Hostname of TrueNAS server to register in Active Directory. Example: "truenasnyc".

Must be at least `1` characters long

##

#### Domain

Type: string

The full DNS domain name of the Active Directory domain. This must not be a domain controller. Example: "mydomain.internal".

Must be at least `1` characters long

##

#### PrimaryDomainIdmap

Type: object
Default:
{ "builtin": { "name": null, "range_high": 100000000, "range_low": 90000001 }, "idmap_domain": { "idmap_backend": "RID", "name": null, "range_high": 200000000, "range_low": 100000001, "sssd_compat": false } }

Configuration for mapping Active Directory accounts to accounts on the TrueNAS server. The exact settings may vary based on other servers and Linux clients in the domain. Defaults are suitable for new deployments without existing support for unix-like operating systems.

No Additional Properties
Example:

    {
        "builtin": {
            "range_high": 100000000,
            "range_low": 90000001
        },
        "idmap_domain": {
            "idmap_backend": "RID",
            "name": "MYDOMAIN",
            "range_high": 200000000,
            "range_low": 100000001
        }
    }

##

#### BuiltinDomainTdb

Type: object
Default:
{ "name": null, "range_low": 90000001, "range_high": 100000000 }

UID and GID range configuration for automatically generated accounts linked to well-known and BUILTIN accounts on Windows servers.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 90000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 100000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Domain

Default:
{ "name": null, "range_low": 100000001, "range_high": 200000000, "idmap_backend": "RID", "sssd_compat": false }

This configuration defines how domain accounts joined to TrueNAS are mapped to Unix UIDs and GIDs on the TrueNAS server. Most TrueNAS deployments use the RID backend, which algorithmically assigns UIDs and GIDs based on the Active Directory account SID. Another common option is the AD backend, which reads predefined Active Directory LDAP schema attributes that assign explicit UID and GID numbers to accounts.

## One of

#### AD_Idmap

Type: object

The AD backend reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions. The administrator must add mappings for users and groups in Active Directory before use.

NOTE: these schema extensions are not present by default in Active Directory.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for Active Directory RFC2307 schema integration.

Specific value: `"AD"`

##

#### Schema Mode

Type: enum (of string)

The schema mode the idmap backend uses to query Active Directory for user and group information. The RFC2307 schema applies to Windows Server 2003 R2 and newer. The Services for Unix (SFU) schema applies to versions before Windows Server 2003 R2.

##### Must be one of:

- "RFC2307"
- "SFU"
- "SFU20"

##

#### Unix Primary Group

Type: boolean Default: false

Defines if the user's primary group is fetched from SFU attributes or the Active Directory primary group. If True, the TrueNAS server uses the `gidNumber` LDAP attribute. If False, it uses the `primaryGroupID` LDAP attribute.

##

#### Unix Nss Info

Type: boolean Default: false

If True, the login shell and home directory are retrieved from LDAP attributes. If False, or if the Active Directory LDAP entry lacks SFU attributes, the home directory defaults to `/var/empty`.

#### LDAP_Idmap

Type: object

The LDAP backend reads and writes UID / GID mapping tables from an external LDAP server.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for external LDAP server mapping.

Specific value: `"LDAP"`

##

#### Ldap Base Dn

Type: string

Directory base suffix to use for mapping UIDs and GIDs to SIDs.

##

#### Ldap User Dn

Type: string

Defines the user DN to be used for authentication to the LDAP server.

##

#### Ldap User Dn Password

Type: string

Secret to use for authenticating the user specified by `ldap_user_dn`.

Must be at least `1` characters long

##

#### Ldap Url

Type: string

LDAP server to use for the idmap entries.

##

#### Readonly

Type: boolean Default: true

If readonly is set to True then TrueNAS will not attempt to write new idmap entries.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RFC2307_Idmap

Type: object

The RFC2307 backend reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only. Use the `AD` idmap backend if the server is an Active Directory domain controller.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RFC2307 LDAP attribute mapping.

Specific value: `"RFC2307"`

##

#### Ldap Url

Type: string

The LDAP URL used to access the LDAP server.

##

#### Ldap User Dn

Type: string

Defines the DN used to authenticate to the LDAP server.

##

#### Ldap User Dn Password

Type: string

The password used to authenticate the account specified in ldapuserdn.

Must be at least `1` characters long

##

#### Bind Path User

Type: string

The search base that contains user objects in the LDAP server.

##

#### Bind Path Group

Type: string

The search base that contains group objects in the LDAP server.

##

#### User Cn

Type: boolean Default: false

If set, query the CN attribute instead of the UID attribute for the user name in LDAP.

##

#### Ldap Realm

Type: boolean Default: false

Append @realm to the CN for groups. Also append it to users if user_cn is specified.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RID_Idmap

Type: object

The RID backend uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low. RID values in an Active Directory domain can be large, especially as the domain ages. Administrators should configure a range large enough to cover the current RID values assigned by the RID master. One way to do this is to check the RID of a recently created account in Active Directory. For example, if the RID is 500000, the range must include at least 500000 Unix IDs (for example, 1000000 to 2000000).

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RID-based algorithmic mapping.

Specific value: `"RID"`

##

#### Sssd Compat

Type: boolean Default: false

Generate an idmap low range using the algorithm from SSSD. This works if the domain uses only a single SSSD idmap slice, and is sufficient if the domain uses only a single SSSD idmap slice.

##

#### Site

Default: null

The Active Directory site where the TrueNAS server is located. TrueNAS detects this automatically during the domain join process.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Computer Account Ou

Default: null

Use this setting to override the default organizational unit (OU) in which the TrueNAS computer account is created during the domain join. Use it to set a custom location for TrueNAS computer accounts.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Example:

    "TRUENAS_SERVERS/NYC"

##

#### Use Default Domain

Type: boolean Default: false

Controls if the system removes the domain prefix from Active Directory user and group names. If enabled, users appear as "administrator" instead of "EXAMPLE\administrator". In most cases, disable this (default) to avoid name conflicts between Active Directory and local accounts.

##

#### Enable Trusted Domains

Type: boolean Default: false

Enable support for trusted domains. If True, then separate trusted domain configuration must be set for all trusted domains.

##

#### Trusted Domains

Type: array Default: []

Configuration for trusted domains.

No Additional Items

##### Each item of this array must be:

Default:
{ "name": null, "range_low": 100000001, "range_high": 200000000, "idmap_backend": "RID", "sssd_compat": false }

## One of

#### AD_Idmap

Type: object

The AD backend reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions. The administrator must add mappings for users and groups in Active Directory before use.

NOTE: these schema extensions are not present by default in Active Directory.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for Active Directory RFC2307 schema integration.

Specific value: `"AD"`

##

#### Schema Mode

Type: enum (of string)

The schema mode the idmap backend uses to query Active Directory for user and group information. The RFC2307 schema applies to Windows Server 2003 R2 and newer. The Services for Unix (SFU) schema applies to versions before Windows Server 2003 R2.

##### Must be one of:

- "RFC2307"
- "SFU"
- "SFU20"

##

#### Unix Primary Group

Type: boolean Default: false

Defines if the user's primary group is fetched from SFU attributes or the Active Directory primary group. If True, the TrueNAS server uses the `gidNumber` LDAP attribute. If False, it uses the `primaryGroupID` LDAP attribute.

##

#### Unix Nss Info

Type: boolean Default: false

If True, the login shell and home directory are retrieved from LDAP attributes. If False, or if the Active Directory LDAP entry lacks SFU attributes, the home directory defaults to `/var/empty`.

#### LDAP_Idmap

Type: object

The LDAP backend reads and writes UID / GID mapping tables from an external LDAP server.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for external LDAP server mapping.

Specific value: `"LDAP"`

##

#### Ldap Base Dn

Type: string

Directory base suffix to use for mapping UIDs and GIDs to SIDs.

##

#### Ldap User Dn

Type: string

Defines the user DN to be used for authentication to the LDAP server.

##

#### Ldap User Dn Password

Type: string

Secret to use for authenticating the user specified by `ldap_user_dn`.

Must be at least `1` characters long

##

#### Ldap Url

Type: string

LDAP server to use for the idmap entries.

##

#### Readonly

Type: boolean Default: true

If readonly is set to True then TrueNAS will not attempt to write new idmap entries.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RFC2307_Idmap

Type: object

The RFC2307 backend reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only. Use the `AD` idmap backend if the server is an Active Directory domain controller.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RFC2307 LDAP attribute mapping.

Specific value: `"RFC2307"`

##

#### Ldap Url

Type: string

The LDAP URL used to access the LDAP server.

##

#### Ldap User Dn

Type: string

Defines the DN used to authenticate to the LDAP server.

##

#### Ldap User Dn Password

Type: string

The password used to authenticate the account specified in ldapuserdn.

Must be at least `1` characters long

##

#### Bind Path User

Type: string

The search base that contains user objects in the LDAP server.

##

#### Bind Path Group

Type: string

The search base that contains group objects in the LDAP server.

##

#### User Cn

Type: boolean Default: false

If set, query the CN attribute instead of the UID attribute for the user name in LDAP.

##

#### Ldap Realm

Type: boolean Default: false

Append @realm to the CN for groups. Also append it to users if user_cn is specified.

##

#### Validate Certificates

Type: boolean Default: true

If False, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### RID_Idmap

Type: object

The RID backend uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low. RID values in an Active Directory domain can be large, especially as the domain ages. Administrators should configure a range large enough to cover the current RID values assigned by the RID master. One way to do this is to check the RID of a recently created account in Active Directory. For example, if the RID is 500000, the range must include at least 500000 Unix IDs (for example, 1000000 to 2000000).

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for RID-based algorithmic mapping.

Specific value: `"RID"`

##

#### Sssd Compat

Type: boolean Default: false

Generate an idmap low range using the algorithm from SSSD. This works if the domain uses only a single SSSD idmap slice, and is sufficient if the domain uses only a single SSSD idmap slice.

Examples:

    {
        "idmap_backend": "RID",
        "name": "BROOK",
        "range_high": 300000000,
        "range_low": 200000001
    }

    {
        "idmap_backend": "RID",
        "name": "DARVO",
        "range_high": 400000000,
        "range_low": 300000001
    }

#### IPAConfig

Type: object
No Additional Properties

##

#### Target Server

Type: string

The name of the IPA server that TrueNAS uses to build URLs when it joins or leaves the IPA domain. Example: "ipa.example.internal".

Must be at least `1` characters long

##

#### Hostname

Type: string

Hostname of TrueNAS server to register in IPA during the join process. Example: "truenasnyc".

Must be at least `1` characters long

##

#### Domain

Type: string

The domain of the IPA server. Example "ipa.internal".

Must be at least `1` characters long

##

#### Basedn

Type: string

The base DN to use when performing LDAP operations. Example: "dc=example,dc=internal".

##

Default: null

Settings for the IPA SMB domain. TrueNAS detects these settings during IPA join. Some IPA domains may not include SMB schema configuration.

## Any of

#### IPA_SMBDomain

Type: object

This is a special idmap backend used when TrueNAS joins an IPA domain. The remote IPA server provides the configuration information during the domain join process.

No Additional Properties

##

#### Name

Default: null

Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. It may be null if the domain is configured as the base idmap for Active Directory.

## Any of

Type: string
Type: null
Example:

    "IXDOM"

##

#### Range Low

Type: integer Default: 100000001

The lowest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Range High

Type: integer Default: 200000000

The highest UID or GID that the idmap backend can assign.

Value must be greater or equal to `1000` and lesser or equal to `2147000000`

##

#### Idmap Backend

Type: const

Idmap backend type identifier for System Security Services Daemon integration.

Specific value: `"SSS"`

##

#### Domain Name

Default: null

Name of the SMB domain as defined in the IPA configuration for the IPA domain to which TrueNAS is joined.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Example:

    "IXDOM.INTERNAL"

##

#### Domain Sid

Default: null

The domain SID for the IPA domain to which TrueNAS is joined.

## Any of

Type: string
Type: null
Example:

    "S-1-5-21-3696504179-2855309571-923743039"

Type: null

##

#### Validate Certificates

Type: boolean Default: true

If `False`, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

#### LDAPConfig

Type: object
No Additional Properties

##

#### Server Urls

Type: array of string

List of LDAP server URIs used for LDAP binds. Each URI must begin with ldap:// or ldaps:// and may use either a DNS name or an IP address. Example: `['ldaps://myldap.domain.internal']`.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Basedn

Type: string

The base DN to use when performing LDAP operations. Example: `"dc=domain,dc=internal"`.

##

#### Starttls

Type: boolean Default: false

Establish TLS by transmitting a StartTLS request to the server.

##

#### Validate Certificates

Type: boolean Default: true

If `False`, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server's trusted certificate store.

##

#### Schema

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

The type of LDAP attribute schema that the remote LDAP server uses.

##### Must be one of:

- "RFC2307"
- "RFC2307BIS"

##

#### LDAPSearchBases

Type: object
Default:
{ "base_user": null, "base_group": null, "base_netgroup": null }

Alternative LDAP search base settings. These settings define where to find user, group, and netgroup entries. If unspecified (the default), TrueNAS uses the `basedn` to find users. groups, and netgroups. Use these settings only if the LDAP server uses a non-standard LDAP schema or if you want to limit the accounts available on TrueNAS.

No Additional Properties

##

#### Base User

Default: null

Optional base DN to limit LDAP user searches. If null (default) then the `base_dn` is used.

## Any of

Type: string
Type: null

##

#### Base Group

Default: null

Optional base DN to limit LDAP group searches. If null (default) then the `base_dn` is used.

## Any of

Type: string
Type: null

##

#### Base Netgroup

Default: null

Optional base DN to limit LDAP netgroup searches. If null (default) then the `base_dn` is used.

## Any of

Type: string
Type: null

##

#### LDAPAttributeMaps

Type: object
Default:
{ "passwd": { "user_gecos": null, "user_gid": null, "user_home_directory": null, "user_name": null, "user_object_class": null, "user_shell": null, "user_uid": null }, "shadow": { "shadow_expire": null, "shadow_inactive": null, "shadow_last_change": null, "shadow_max": null, "shadow_min": null, "shadow_warning": null }, "group": { "group_gid": null, "group_member": null, "group_object_class": null }, "netgroup": { "netgroup_member": null, "netgroup_object_class": null, "netgroup_triple": null } }

Optional LDAP attribute mapping for LDAP servers that do not follow RFC2307 or RFC2307BIS. Use this only if the LDAP server is non-standard.

No Additional Properties

##

#### LDAPMapPasswd

Type: object
Default:
{ "user_object_class": null, "user_name": null, "user_uid": null, "user_gid": null, "user_gecos": null, "user_home_directory": null, "user_shell": null }

LDAP attribute mappings for passwd/user entries.

No Additional Properties

##

#### User Object Class

Default: null

The user entry object class in LDAP.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Name

Default: null

The LDAP attribute for the user's login name.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Uid

Default: null

The LDAP attribute for the user's id.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Gid

Default: null

The LDAP attribute for the user's primary group id.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Gecos

Default: null

The LDAP attribute for the user's gecos field.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Home Directory

Default: null

The LDAP attribute for the user's home directory.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### User Shell

Default: null

The LDAP attribute for the path to the user's default shell.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### LDAPMapShadow

Type: object
Default:
{ "shadow_last_change": null, "shadow_min": null, "shadow_max": null, "shadow_warning": null, "shadow_inactive": null, "shadow_expire": null }

LDAP attribute mappings for shadow password entries.

No Additional Properties

##

#### Shadow Last Change

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (date of the last password change).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Min

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (minimum password age).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Max

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (maximum password age).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Warning

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (password warning period).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Inactive

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (password inactivity period).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Shadow Expire

Default: null

This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (account expiration date).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### LDAPMapGroup

Type: object
Default:
{ "group_object_class": null, "group_gid": null, "group_member": null }

LDAP attribute mappings for group entries.

No Additional Properties

##

#### Group Object Class

Default: null

The LDAP object class for group entries.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group Gid

Default: null

The LDAP attribute for the group's id.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group Member

Default: null

The LDAP attribute for the names of the group's members.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### LDAPMapNetgroup

Type: object
Default:
{ "netgroup_object_class": null, "netgroup_member": null, "netgroup_triple": null }

LDAP attribute mappings for netgroup entries.

No Additional Properties

##

#### Netgroup Object Class

Default: null

The LDAP object class for netgroup entries.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Netgroup Member

Default: null

The LDAP attribute for the netgroup's members.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Netgroup Triple

Default: null

The LDAP attribute for netgroup triples (host, user, domain).

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Auxiliary Parameters

Default: null

Additional paramaters to add to the SSSD configuration.

WARNING: TrueNAS does not check the validity of these parameters. Incorrect values can cause production outages when they are applied or after an operating system upgrade.

## Any of

Type: string

Must be at least `1` characters long

Type: null
Type: null
Examples:

    {
        "computer_account_ou": "TRUENAS_SERVERS",
        "domain": "ACME.INTERNAL",
        "hostname": "TRUENASZ356"
    }

    {
        "basedn": "dc=ipadom,dc=internal",
        "domain": "ipadom.internal",
        "hostname": "TRUENASZ345",
        "target_server": "ipasrv5.ipadom.internal"
    }

    {
        "basedn": "dc=ipadom,dc=internal",
        "server_urls": [
            "ldap.ipadom.internal"
        ]
    }

Required roles: DIRECTORY_SERVICE_WRITE