8. Directory Services¶

TrueNAS^® supports integration with these directory services:

Active Directory (for Windows 2000 and higher networks)
LDAP
NIS

It also supports Kerberos Realms, Kerberos Keytabs, and the ability to add more parameters to Kerberos Settings.

This section summarizes each of these services and their available configurations within the TrueNAS^® web interface.

8.1. Active Directory¶

Active Directory (AD) is a service for sharing resources in a Windows network. AD can be configured on a Windows server that is running Windows Server 2000 or higher or on a Unix-like operating system that is running Samba version 4. Since AD provides authentication and authorization services for the users in a network, it is not necessary to recreate these user accounts on the TrueNAS^® system. Instead, configure the Active Directory service so that it can import the account information and imported users can be authorized to access the SMB shares on the TrueNAS^® system.

Many changes and improvements have been made to Active Directory support within TrueNAS^®. It is strongly recommended to update the system to the latest TrueNAS^® 11.2 before attempting Active Directory integration.

Ensure name resolution is properly configured before configuring the Active Directory service. ping the domain name of the Active Directory domain controller from Shell on the TrueNAS^® system. If the ping fails, check the DNS server and default gateway settings in Network ➞ Global Configuration on the TrueNAS^® system.

By default, Allow DNS updates in the Active Directory options is enabled. This adds TrueNAS^® SMB ‘Bind IP Addresses’ DNS records to the Active Directory DNS when the domain is joined. Disabling Allow DNS updates means that the Active Directory DNS records must be updated manually.

Active Directory relies on Kerberos, a time-sensitive protocol. The time on the TrueNAS^® system and the Active Directory Domain Controller cannot be out of sync by more than five minutes in a default Active Directory environment.

To ensure both systems are set to the same time:

use the same NTP server (set in System ➞ General ➞ NTP Servers on the TrueNAS^® system)
have the same timezone
be set to either localtime or universal time at the BIOS level

Using a TrueNAS^® system as an AD server and connecting to it with a TrueNAS^® client requires additional configuration. On the AD server, go to System ➞ CAs and create a new internal or intermediate Certificate Authority (CA). Highlight the created CA and click Export Certificate and Export Private Key to save these values.

On the client web interface, select Directory Service ➞ Active Directory ➞ Advanced Mode. Set Encryption Mode to TLS and SASL wrapping to sign. Go to System ➞ CAs and click Import CA. Create a unique Identifier and paste the AD server CA certificate and private keys in those fields. Click OK and continue configuring AD.

Figure 8.1.1 shows the screen that appears when Directory Service ➞ Active Directory is chosen. Table 8.1.1 describes the configurable options. Some settings are only available in Advanced Mode. To see these settings, either click Advanced Mode or configure the system to always display these settings by checking Show advanced fields by default in System ➞ Advanced.

Fig. 8.1.1 Configuring Active Directory

Table 8.1.1 Active Directory Configuration Options¶
Setting	Value	Advanced Mode	Description
Domain Name (DNS/Realm-Name)	string		Name of Active Directory domain (example.com) or child domain (sales.example.com). This setting is mandatory and the GUI will refuse to save the settings if the domain controller for the specified domain cannot be found.
Domain Account Name	string		Name of the Active Directory administrator account. This setting is mandatory and the GUI will refuse to save the settings if it cannot connect to the domain controller using this account name.
Domain Account Password	string		Password for the Active Directory administrator account. This setting is mandatory and the GUI will refuse to save the settings if it cannot connect to the domain controller using this password.
AD check connectivity frequency (seconds)	integer		How often to verify that Active Directory services are active.
How many recovery attempts	integer		Number of times to attempt reconnecting to the Active Directory server. Tries forever when set to 0.
Enable Monitoring	checkbox		Restart Active Directory automatically if the service is disconnected. Setting this prevents configuring the Domain Controller service.
Encryption Mode	drop-down	✓	Choices are Off, SSL (LDAPS protocol port 636), or TLS (LDAP protocol port 389). See http://info.ssl.com/article.aspx?id=10241 and https://hpbn.co/transport-layer-security-tls/ for more information about SSL and TLS.
Certificate	drop-down menu	✓	Select the Active Directory server certificate if SSL connections are used. If a certificate does not exist, create a Certificate Authority, then create a certificate on the Active Directory server. Import the certificate to the TrueNAS^® system using the Certificates menu. To clear a saved certificate, choose the blank entry and click Save.
Verbose logging	checkbox	✓	Set to log attempts to join the domain to `/var/log/messages`.
UNIX extensions	checkbox	✓	Deprecated. Use the System Security Services Daemon (SSSD) for retrieving RFC2307 extensions from an Active Directory domain. Use the ad idmap backend to enable this feature.
Allow Trusted Domains	checkbox	✓	Do not set this unless the network has active domain/forest trusts and managing files on multiple domains is required. Setting this option generates more winbindd traffic and slows down filtering with user and group information. If enabled, also configuring the idmap ranges and a backend for each trusted domain in the environment is recommended.
Use Default Domain	checkbox	✓	Unset to prepend the domain name to the username. If Allow Trusted Domains is set and multiple domains use the same usernames, unset to prevent name collisions.
Allow DNS updates	checkbox	✓	Unset to disable Samba from doing DNS updates when joining a domain.
Disable Active Directory user/group cache	checkbox	✓	Disable caching AD users and groups. Setting this hides all AD users and groups from web interface drop-down menus and auto-completion suggestions, but manually entering names is still allowed. This can help when unable to bind to a domain with a large number of users or groups.
Site Name	string	✓	Auto-detected site name. Do not change this unless the detected site name is incorrect for the particular AD environment.
Domain Controller	string	✓	The server that manages user authentication and security as part of a Windows domain. Leave empty for TrueNAS^® to use the DNS SRV records to automatically detect and connect to the domain controller. If the domain controller must be set manually, enter the server hostname or IP address.
Global Catalog Server	string	✓	The global catalog server holds a full set of attributes for the domain in which it resides and a subset of attributes for all objects in the Microsoft Active Directory Forest. See the IBM Knowledge Center. Leave empty for TrueNAS^® to use the DNS SRV records to automatically detect and connect to the server. If the global catalog server must be entered manually, enter the server hostname or IP address.
Kerberos Realm	drop-down menu	✓	Select the realm created using the instructions in Kerberos Realms.
Kerberos Principal	drop-down menu	✓	Browse to the location of the keytab created using the instructions in Kerberos Keytabs.
AD timeout	integer	✓	In seconds, increase if the AD service does not start after connecting to the domain.
DNS timeout	integer	✓	In seconds, increase if AD DNS queries timeout.
Idmap backend	drop-down menu and Edit	✓	Select the backend to use to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs. See Table 8.1.2 for a summary of the available backends. Click Edit to configure the backend.
Windbind NSS Info	drop-down menu	✓	Defines the schema to use when querying AD for user/group info. rfc2307 uses the RFC2307 schema included in Windows 2003 R2, sfu20 is for Services For Unix 3.0 or 3.5, and sfu is for Services For Unix 2.0.
SASL wrapping	drop-down menu	✓	Defines how LDAP traffic is transmitted. Choices are plain (plain text), sign (signed only), or seal (signed and encrypted). Windows 2000 SP3 and newer can be configured to enforce signed LDAP connections.
Enable	checkbox		Activate the Active Directory service.
NetBIOS Name (This Node)	string	✓	Name for the computer object generated in AD. Limited to 15 characters. Automatically populated with the original hostname of the system. This must be different from the Workgroup name.
NetBIOS Name (Node A/B)	string	✓	Name for the computer object generated in AD. Limited to 15 characters. When using Failover, set a unique NetBIOS name for the standby node.
NetBIOS Alias	string	✓	Limited to 15 characters. When using Failover, this is the NetBIOS name that resolves to either node.

Table 8.1.2 summarizes the backends which are available in the Idmap backend drop-down menu. Each backend has its own man page which gives implementation details.

Changing idmap backends requires refreshing the windbind resolver cache by sending SIGHUP (signal hang up) to the parent windbindd process. To find this parent process, start an SSH session with the TrueNAS^® system and enter service samba_server status. To send the SIGHUP, enter kill -HUP pid, where pid is the parent process ID.

Table 8.1.2 ID Mapping Backends¶
Value	Description
ad	AD server uses RFC2307 or Services For Unix schema extensions. Mappings must be provided in advance by adding the uidNumber attributes for users and gidNumber attributes for groups in the AD.
autorid	Similar to rid, but automatically configures the range to be used for each domain, so there is no need to specify a specific range for each domain in the forest. The only needed configuration is the range of UID/GIDs to use for user/group mappings and an optional size for the ranges.
fruit	Generate IDs the way Apple Mac OS X does, so UID and GID can be identical on all TrueNAS^® servers on the network. For use in LDAP environments where Apple Open Directory is the authoritative LDAP server.
ldap	Stores and retrieves mapping tables in an LDAP directory service. Default for LDAP directory service.
nss	Provides a simple means of ensuring that the SID for a Unix user is reported as the one assigned to the corresponding domain user.
rfc2307	IDs for AD users stored as RFC2307 ldap schema extensions. This module can either look up the IDs in the AD LDAP servers or an external (non-AD) LDAP server.
rid	Default for AD. Requires an explicit idmap configuration for each domain, using disjoint ranges where a writeable default idmap range is to be defined, using a backend like tdb or ldap.
script	Stores mapping tables for clustered environments in `winbind_cache.tdb`.
tdb	Default backend used by winbindd for storing mapping tables.
tdb2	Substitute for tdb used by winbindd in clustered environments.

Rebuild Directory Service Cache immediately refreshes the web interface directory service cache. This occurs automatically once a day as a cron job.

If there are problems connecting to the realm, verify the settings do not include any disallowed characters. Active Directory does not allow $ characters in Domain or NetBIOS names. The length of those names is also limited to 15 characters. The Administrator account password cannot contain the $ character. If a $ exists in the domain administrator password, kinit reports a Password Incorrect error and ldap_bind reports an Invalid credentials (49) error.

It can take a few minutes after configuring the Active Directory service for the AD information to be populated to the TrueNAS^® system. Once populated, the AD users and groups will be available in the drop-down menus of the Permissions screen of a volume/dataset. For performance reasons, every available user may not show in the listing. However, it will autocomplete all applicable users when typing in a username.

The Active Directory users and groups that are imported to the TrueNAS^® system are shown by typing commands in the TrueNAS^® Shell:

View users: wbinfo -u
View groups: wbinfo -g

In addition, wbinfo -m shows the domains and wbinfo -t tests the connection. When successful, wbinfo -t shows a message similar to:

checking the trust secret for domain YOURDOMAIN via RPC calls succeeded

To manually check that a specified user can authenticate, open the Shell and enter smbclient//127.0.0.1/SHARE -U DOMAIN\username, where SHARE is the SMB share name, DOMAIN is the name of the trusted domain, and username is the user account for authentication testing.

getent passwd and getent group can provide more troubleshooting information if no users or groups are listed in the output.

Tip

Sometimes network users do not appear in the drop-down menu of a Permissions screen but the wbinfo commands display these users. This is typically due to the TrueNAS^® system taking longer than the default ten seconds to join Active Directory. Increase the value of AD timeout to 60 seconds.

To change a certificate, set the Encryption Mode to Off and unset Enable to disable AD. Click Save. Select the new Certificate, set the Encryption Mode as desired, set Enable to re-enable AD, and click Save to restart AD.

8.1.1. Troubleshooting Tips¶

When running AD in a 2003/2008 mixed domain, see this posting for instructions to prevent the secure channel key from becoming corrupt.

Active Directory uses DNS to determine the location of the domain controllers and global catalog servers in the network. Use host -t srv _ldap._tcp.domainname.com to determine the SRV records of the network and change the weight and/or priority of the SRV record to reflect the fastest server. More information about SRV records can be found in the Microsoft article How DNS Support for Active Directory Works.

The realm used depends upon the priority in the SRV DNS record. DNS can override the system Active Directory settings. When unable to connect to the correct realm, check the SRV records on the DNS server.

If the cache becomes out of sync due to an AD server being taken off and back online, resync the cache using Directory Service ➞ Active Directory ➞ Rebuild Directory Service Cache.

An expired password for the administrator account will cause kinit to fail. Ensure the password is still valid. Also, double-check the password on the AD account being used does not include any spaces, special symbols, and is not unusually long.

If the Windows server version is lower than 2008 R2, try creating a Computer entry on the Windows server’s OU. When creating this entry, enter the TrueNAS^® hostname in the name field. Make sure it is under 15 characters, the same name as the one set in the Hostname field in Network ➞ Global Configuration, and the same NetBIOS Name in Directory Service ➞ Active Directory settings. Make sure the hostname of the domain controller is set in the Domain Controller field of Directory Service ➞ Active Directory.

8.1.2. If the System Does not Join the Domain¶

If the system will not join the Active Directory domain, run these commands in the order listed. klist will show a Kerberos ticket:

If the cache becomes out of sync due to an AD server being taken off and back online, resync the cache using Directory Service ➞ Active Directory ➞ Rebuild Directory Service Cache.

If any of the commands fail or result in a traceback, create a bug report at https://bugs.ixsystems.com that includes the commands in the order in which they were run and the exact wording of the error message or traceback.

sqlite3 /data/freenas-v1.db "UPDATE directoryservice_activedirectory SET ad_enable=1"
service ix-hostname start
service ix-kerberos start
service ix-kinit start
klist
service ix-pre-samba start
net -k -d 5 ads join [this generates verbose output of the domain join]
service samba_server restart
service ix-nsswitch start
service ix-pam start
service ix-cache start

Next, only run these two commands if UNIX extensions is set in Advanced Mode and a keytab has been uploaded using Kerberos Keytabs:

service ix-sssd start
service sssd start

Finally, run these commands. echo returns a 0 unless something has gone wrong:

python /usr/local/www/freenasUI/middleware/notifier.py start cifs
service ix-activedirectory start
service ix-activedirectory status
echo $?
python /usr/local/www/freenasUI/middleware/notifier.py restart cifs
service ix-pam start
service ix-cache start &

8.2. LDAP¶

TrueNAS^® includes an OpenLDAP client for accessing information from an LDAP server. An LDAP server provides directory services for finding network resources such as users and their associated permissions. Examples of LDAP servers include Microsoft Server (2000 and newer), Mac OS X Server, Novell eDirectory, and OpenLDAP running on a BSD or Linux system. If an LDAP server is running on the network, configure the TrueNAS^® LDAP service so network users can authenticate to the LDAP server and have authorized access to the data stored on the TrueNAS^® system.

Tip

TrueNAS^® can also integrate with the Apple Open Directory LDAP-compatible directory service. See FreeNAS with Open Directory in Mac OS X environments.

LDAP authentication for SMB shares is disabled unless the LDAP directory has been configured for and populated with Samba attributes. The most popular script for performing this task is smbldap-tools. In addition, the LDAP server must support SSL/TLS and the certificate for the LDAP server CA must be imported with System ➞ CAs ➞ Import CA. Note that non-CA certificates are not supported at this time.

Figure 8.2.1 shows the LDAP Configuration screen that is seen after clicking Directory Service ➞ LDAP.

Fig. 8.2.1 Configuring LDAP

Table 8.2.1 summarizes the available configuration options. Some settings are only available in Advanced Mode. To see these settings, either click the Advanced Mode button or configure the system to always display these settings by checking the box Show advanced fields by default in System ➞ Advanced.

Those new to LDAP terminology should read the OpenLDAP Software 2.4 Administrator’s Guide.

Table 8.2.1 LDAP Configuration Options¶
Setting	Value	Advanced Mode	Description
Hostname	string		Hostname or IP address of the LDAP server.
Base DN	string		Top level of the LDAP directory tree to be used when searching for resources. Example: dc=test,dc=org.
Bind DN	string		Name of administrative account on the LDAP server. Example: cn=Manager,dc=test,dc=org.
Bind password	string		Password for Root bind DN.
Allow Anonymous Binding	checkbox	✓	Instructs the LDAP server to not provide authentication and to allow read and write access to any client.
User Suffix	string	✓	Optional. Can be added to the name when the user account is added to the LDAP directory. Example: dept. or company name.
Group Suffix	string	✓	Optional. Can be added to the name when the group is added to the LDAP directory. Example: dept. or company name.
Password Suffix	string	✓	Optional. Can be added to the password when the password is added to LDAP directory.
Machine Suffix	string	✓	Optional. Can be added to the name when the system added to the LDAP directory. Example: server, accounting.
SUDO Suffix	string	✓	Use if LDAP-based users need superuser access.
Kerberos Realm	drop-down menu	✓	Select the realm created using the instructions in Kerberos Realms.
Kerberos Principal	drop-down menu	✓	Browse to the location of the principal in the keytab created as described in Kerberos Keytabs.
Encryption Mode	drop-down menu	✓	Choices are Off, SSL (LDAPS, port 636), or TLS (LDAP, port 389). Note that either SSL or TLS and a Certificate must be selected for authentication to work.
Certificate	drop-down menu	✓	Select the certificate of the LDAP CA (required if authentication is used). The certificate for the LDAP server CA must first be imported with System ➞ Certificates ➞ Import Certificate.
LDAP timeout	integer	✓	Increase this value (in seconds) if obtaining a Kerberos ticket times out.
DNS timeout	integer	✓	Increase this value (in seconds) if DNS queries timeout.
Idmap Backend	drop-down menu and Edit button	✓	Select the backend to use to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs. See Table 8.1.2 for a summary of the available backends. Click Edit to configure the selected backend.
Samba Schema	checkbox	✓	Set if LDAP authentication for SMB shares is needed and the LDAP server is already configured with Samba attributes.
Auxiliary Parameters	string	✓	Additional options for sssd.conf(5).
Schema	drop-down menu	✓	If Samba Schema is set, select the schema to use. Choices are rfc2307 and rfc2307bis.
Enable	checkbox		Unset to disable the configuration without deleting it.
NetBIOS name (This Node)	string	✓	Limited to 15 characters. Automatically populated with the original hostname of the system. This must be different from the Workgroup name.
NetBIOS name (Node A/B)	string	✓	Limited to 15 characters. When using Failover, set a unique NetBIOS name for the standby node.
NetBIOS alias	string	✓	Limited to 15 characters. When using Failover, this is the NetBIOS name that resolves to either node.

Click the Rebuild Directory Service Cache button after adding a user to LDAP who needs immediate access to TrueNAS^®. Otherwise this occurs automatically once a day as a cron job.

Note

TrueNAS^® automatically appends the root DN. This means the scope and root DN are not to be included when configuring the user, group, password, and machine suffixes.

LDAP users and groups appear in the drop-down menus of the Permissions screen of a dataset after configuring the LDAP service. Type getent passwd from Shell to verify the users have been imported. Type getent group to verify the groups have been imported.

If the users and groups are not listed, refer to Common errors encountered when using OpenLDAP Software for common errors and how to fix them. When troubleshooting LDAP, open Shell and look for error messages in /var/log/auth.log.

To clear LDAP users and groups from TrueNAS^®, go to Directory Service ➞ LDAP, clear the Hostname field, unset Enable, and click Save. Confirm LDAP users and groups are cleared by going to the Shell and viewing the output of the getent passwd and getent group commands.

8.3. NIS¶

The Network Information Service (NIS) maintains and distributes a central directory of Unix user and group information, hostnames, email aliases, and other text-based tables of information. If an NIS server is running on the network, the TrueNAS^® system can be configured to import the users and groups from the NIS directory.

Note

In Windows Server 2016, Microsoft removed the Identity Management for Unix (IDMU) and NIS Server Role. See Clarification regarding the status of Identity Management for Unix (IDMU) & NIS Server Role in Windows Server 2016 Technical Preview and beyond.

Figure 8.3.1 shows the configuration screen which opens after going to Directory Service ➞ NIS. Table 8.3.1 summarizes the configuration options.

Fig. 8.3.1 NIS Configuration

Table 8.3.1 NIS Configuration Options¶
Setting	Value	Description
NIS domain	string	Name of NIS domain.
NIS servers	string	Comma-delimited list of hostnames or IP addresses.
Secure mode	checkbox	If set, ypbind(8) will refuse to bind to any NIS server that is not running as root on a TCP port number over 1024.
Manycast	checkbox	If set, ypbind will bind to the server that responds the fastest. This is useful when no local NIS server is available on the same subnet
Enable	checkbox	Unset to disable the configuration without deleting it.

Click the Rebuild Directory Service Cache button after adding a user to NIS who needs immediate access to TrueNAS^®. Otherwise this occurs automatically once a day as a cron job.

8.4. Kerberos Realms¶

A default Kerberos realm is created for the local system in TrueNAS^®. Directory Service ➞ Kerberos Realms can be used to view and add Kerberos realms. If the network contains a Key Distribution Center (KDC), click Add kerberos realm to add the realm. This configuration screen is shown in Figure 8.4.1.

Fig. 8.4.1 Adding a Kerberos Realm

Table 8.4.1 summarizes the configurable options. Some settings are only available in Advanced Mode. To see these settings, either click Advanced Mode or configure the system to always display these settings by checking the box Show advanced fields by default in System ➞ Advanced.

Table 8.4.1 Kerberos Realm Options¶
Setting	Value	Advanced Mode	Description
Realm	string		Mandatory. Name of the Kerberos realm.
KDC	string	✓	Name of the Key Distribution Center.
Admin Server	string	✓	Server where all changes to the database are performed.
Password Server	string	✓	Server where all password changes are performed.

8.5. Kerberos Keytabs¶

Kerberos keytabs are used to do Active Directory or LDAP joins without a password. This means the password for the Active Directory or LDAP administrator account does not need to be saved into the TrueNAS^® configuration database, which is a security risk in some environments.

When using a keytab, it is recommended to create and use a less privileged account for performing the required queries as the password for that account will be stored in the TrueNAS^® configuration database. To create the keytab on a Windows system, use the ktpass command:

ktpass.exe /out freenas.keytab /princ http/useraccount@EXAMPLE.COM /mapuser useraccount /ptype KRB5_NT_PRINCIPAL /crypto ALL /pass userpass

where:

freenas.keytab is the file to upload to the TrueNAS^® server.
http/useraccount@EXAMPLE.COM is the principal name written in the format host/user.account@KERBEROS.REALM. By convention, the kerberos realm is written in all caps, but make sure the case used for the Kerberos Realm matches the realm name. See this note about using /princ for more details.
useraccount is the name of the user account for the TrueNAS^® server generated in Active Directory Users and Computers.
userpass is the password associated with useraccount.

Setting /crypto to ALL allows using all supported cryptographic types. These keys can be specified instead of ALL:

DES-CBC-CRC is used for compatibility.
DES-CBC-MD5 adheres more closely to the MIT implementation and is used for compatibility.
RC4-HMAC-NT uses 128-bit encryption.
AES256-SHA1 uses AES256-CTS-HMAC-SHA1-96 encryption.
AES128-SHA1 uses AES128-CTS-HMAC-SHA1-96 encryption.

This will create a keytab with sufficient privileges to grant tickets.

After the keytab is generated, use Directory Service ➞ Kerberos Keytabs ➞ Add kerberos keytab to add it to the TrueNAS^® system.

To instruct the Active Directory service to use the keytab, select the installed keytab using the drop-down Kerberos keytab menu in Directory Service ➞ Active Directory. When using a keytab with Active Directory, make sure that the username and userpass in the keytab matches the Domain Account Name and Domain Account Password fields in Directory Service ➞ Active Directory.

To instruct LDAP to use a principal from the keytab, select the principal from the drop-down Kerberos Principal menu in Directory Service ➞ LDAP.

8.6. Kerberos Settings¶

To configure additional Kerberos parameters, use Directory Service ➞ Kerberos Settings. Figure 8.6.1 shows the fields available:

Appdefaults auxiliary parameters: contains settings used by some Kerberos applications. The available settings and their syntax are listed in the [appdefaults] section of krb.conf(5).
Libdefaults auxiliary parameters: contains settings used by the Kerberos library. The available settings and their syntax are listed in the [libdefaults] section of krb.conf(5).

_images/directoryservice-kerberos-settings.png

Fig. 8.6.1 Additional Kerberos Settings