8. Directory Services¶

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.0 before attempting Active Directory integration.

Before configuring the Active Directory service, ensure name resolution is properly configured by ping ing 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.

Next, add a DNS record for the TrueNAS^® system on the Windows server and verify that the hostname of the TrueNAS^® system can be pinged from the domain controller.

Active Directory relies on Kerberos, which is a time sensitive protocol. The time on both the TrueNAS^® system and the Active Directory Domain Controller cannot be out of sync by more than a few minutes. The best way to ensure that the same time is running on both systems is to configure both systems to:

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

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

Fig. 8.1.1 Configuring Active Directory

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. Since selecting the wrong backend will break Active Directory integration, a pop-up menu will appear whenever changes are made to this setting.

Click the Rebuild Directory Service Cache button if a new Active Directory user needs immediate access to TrueNAS^®. This occurs automatically once a day as a cron job.

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 have been imported to the TrueNAS^® system can be shown by using these commands from the TrueNAS^® Shell. To view users:

wbinfo -u

To view groups:

wbinfo -g

In addition, wbinfo -t will test the connection and, if successful, will show a message similar to:

checking the trust secret for domain YOURDOMAIN via RPC calls succeeded

To manually check that a specified user can authenticate:

net ads join -S dcname -U username

If no users or groups are listed in the output, these commands can provide more troubleshooting information:

getent passwd

getent group

If the wbinfo commands display the network users, but they do not show up in the drop-down menu of a Permissions screen, it may be because it is taking longer than the default ten seconds for the TrueNAS^® system to join Active Directory. Try bumping up the value of AD timeout to 60 seconds.

sqlite3 /data/freenas-v1.db "update directoryservice_activedirectory set ad_enable=1;"
echo $?
service ix-kerberos start
service ix-nsswitch start
service ix-kinit start
service ix-kinit status
echo $?
klist

service ix-sssd start
service sssd start

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

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 who are new to LDAP terminology should skim through the OpenLDAP Software 2.4 Administrator’s Guide.

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.

LDAP users and groups appear in the drop-down menus of the Permissions screen of a volume/dataset after configuring the LDAP service. Type getent passwd from Shell to verify that the users have been imported. Type getent group to verify that 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.

8.3. NIS¶

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

Figure 8.3.1 shows the configuration screen which opens when you click Directory Service → NIS. Table 8.3.1 summarizes the configuration options.

Fig. 8.3.1 NIS Configuration

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 KDC, click the Add kerberos realm button to add the Kerberos 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 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.

8.5. Kerberos Keytabs¶

Kerberos keytabs are used to do Active Directory or LDAP joins without a password. This means that 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 these commands:

ktpass.exe -out hostname.keytab host/ hostname@DOMAINNAME -ptype KRB5_NT_PRINCIPAL -mapuser DOMAIN\username -pass userpass

setspn -A host/ hostname@DOMAINNAME DOMAIN\username

where:

• hostname is the fully qualified hostname of the domain controller
• DOMAINNAME is the domain name in all caps
• DOMAIN is the pre-Windows 2000 short name for the domain
• username is the privileged account name
• userpass is the password associated with username

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

Fig. 8.6.1 Additional Kerberos Settings