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.
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.
"KERBEROS_USER" 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
The password for the user account that will obtain the kerberos ticket.
Must be at least 1 characters long
"KERBEROS_PRINCIPAL" 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
"LDAP_PLAIN" Must be at least 1 characters long
"LDAP_ANONYMOUS" "LDAP_MTLS" The client certificate name used for mutual TLS authentication to the remote LDAP server.
Must be at least 1 characters long
{
"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 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 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 automatic DNS updates for the TrueNAS server in the domain via nsupdate and gssapi / TSIG.
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 40
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.
Must be at least 1 characters long
The service_type specific configuration for the directory sevices plugin.
Hostname of TrueNAS server to register in Active Directory. Example: "truenasnyc".
Must be at least 1 characters long
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
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{
"builtin": {
"range_high": 100000000,
"range_low": 90000001
},
"idmap_domain": {
"idmap_backend": "RID",
"name": "MYDOMAIN",
"range_high": 200000000,
"range_low": 100000001
}
}
UID and GID range configuration for automatically generated accounts linked to well-known and BUILTIN accounts on Windows servers.
No Additional PropertiesShort 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.
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
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
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.
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 PropertiesShort 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.
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
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
"AD" 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.
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.
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.
The LDAP backend reads and writes UID / GID mapping tables from an external LDAP server.
No Additional PropertiesShort 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.
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
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
"LDAP" Directory base suffix to use for mapping UIDs and GIDs to SIDs.
Defines the user DN to be used for authentication to the LDAP server.
Secret to use for authenticating the user specified by ldap_user_dn.
Must be at least 1 characters long
LDAP server to use for the idmap entries.
If readonly is set to True then TrueNAS will not attempt to write new idmap entries.
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.
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.
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.
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
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
"RFC2307" The LDAP URL used to access the LDAP server.
Defines the DN used to authenticate to the LDAP server.
The password used to authenticate the account specified in ldapuserdn.
Must be at least 1 characters long
The search base that contains user objects in the LDAP server.
The search base that contains group objects in the LDAP server.
If set, query the CN attribute instead of the UID attribute for the user name in LDAP.
Append @realm to the CN for groups. Also append it to users if user_cn is specified.
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.
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 PropertiesShort 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.
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
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
"RID" 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.
The Active Directory site where the TrueNAS server is located. TrueNAS detects this automatically during the domain join process.
Must be at least 1 characters long
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.
Must be at least 1 characters long
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 support for trusted domains. If True, then separate trusted domain configuration must be set for all trusted domains.
Configuration for trusted domains.
No Additional ItemsThe 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 PropertiesShort 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.
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
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
"AD" 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.
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.
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.
The LDAP backend reads and writes UID / GID mapping tables from an external LDAP server.
No Additional PropertiesShort 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.
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
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
"LDAP" Directory base suffix to use for mapping UIDs and GIDs to SIDs.
Defines the user DN to be used for authentication to the LDAP server.
Secret to use for authenticating the user specified by ldap_user_dn.
Must be at least 1 characters long
LDAP server to use for the idmap entries.
If readonly is set to True then TrueNAS will not attempt to write new idmap entries.
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.
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.
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.
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
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
"RFC2307" The LDAP URL used to access the LDAP server.
Defines the DN used to authenticate to the LDAP server.
The password used to authenticate the account specified in ldapuserdn.
Must be at least 1 characters long
The search base that contains user objects in the LDAP server.
The search base that contains group objects in the LDAP server.
If set, query the CN attribute instead of the UID attribute for the user name in LDAP.
Append @realm to the CN for groups. Also append it to users if user_cn is specified.
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.
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 PropertiesShort 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.
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
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
"RID" 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.
{
"idmap_backend": "RID",
"name": "BROOK",
"range_high": 300000000,
"range_low": 200000001
}
{
"idmap_backend": "RID",
"name": "DARVO",
"range_high": 400000000,
"range_low": 300000001
}
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 of TrueNAS server to register in IPA during the join process. Example: "truenasnyc".
Must be at least 1 characters long
The domain of the IPA server. Example "ipa.internal".
Must be at least 1 characters long
The base DN to use when performing LDAP operations. Example: "dc=example,dc=internal".
Settings for the IPA SMB domain. TrueNAS detects these settings during IPA join. Some IPA domains may not include SMB schema configuration.
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 PropertiesShort 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.
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
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
"SSS" Name of the SMB domain as defined in the IPA configuration for the IPA domain to which TrueNAS is joined.
Must be at least 1 characters long
The domain SID for the IPA domain to which TrueNAS is joined.
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.
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'].
The base DN to use when performing LDAP operations. Example: "dc=domain,dc=internal".
Establish TLS by transmitting a StartTLS request to the server.
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.
The type of LDAP attribute schema that the remote LDAP server uses.
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.
Optional base DN to limit LDAP user searches. If null (default) then the base_dn is used.
Optional base DN to limit LDAP group searches. If null (default) then the base_dn is used.
Optional base DN to limit LDAP netgroup searches. If null (default) then the base_dn is used.
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 PropertiesOptional attribute mappings for non-compliant LDAP servers to generate passwd entries. A value of null means to use the default according to the selected LDAP schema.
The user entry object class in LDAP.
The LDAP attribute for the user's login name.
The LDAP attribute for the user's id.
The LDAP attribute for the user's primary group id.
The LDAP attribute for the user's gecos field.
The LDAP attribute for the user's home directory.
The LDAP attribute for the path to the user's default shell.
Optional attribute mappings for non-compliant LDAP servers to generate shadow entries. A value of null means to use the default according to the selected LDAP schema.
This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (date of the last password change).
This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (minimum password age).
This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (maximum password age).
This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (password warning period).
This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (password inactivity period).
This parameter contains the name of an LDAP attribute for its shadow(5) counterpart (account expiration date).
Optional attribute mappings for non-compliant LDAP servers to generate group entries. A value of null means to use the default according to the selected LDAP schema.
The LDAP object class for group entries.
The LDAP attribute for the group's id.
The LDAP attribute for the names of the group's members.
Optional attribute mappings for non-compliant LDAP servers to generate netgroup entries
No Additional PropertiesThe LDAP object class for netgroup entries.
The LDAP attribute for the netgroup's members.
The LDAP attribute for netgroup triples (host, user, domain).
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.
Must be at least 1 characters long
{
"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"
]
}