9. Directory Services¶
FreeNAS® supports integration with these directory services:
This section summarizes each of these services and their available configurations within the FreeNAS® GUI.
9.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 FreeNAS® 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 FreeNAS® system.
Many changes and improvements have been made to Active Directory support within FreeNAS®. It is strongly recommended to update the system to the latest FreeNAS® 11.1 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 FreeNAS® system. If the ping fails, check the DNS server and default gateway settings in on the FreeNAS® system.
Next, add a DNS record for the FreeNAS® system on the Windows server and verify that the hostname of the FreeNAS® system can be pinged from the domain controller.
Active Directory relies on Kerberos, which is a time sensitive protocol. The time on both the FreeNAS® 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 on the FreeNAS® system)
- have the same timezone
- be set to either localtime or universal time at the BIOS level
Figure 9.1.1 shows the screen that appears when is chosen. Table 9.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 .
|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|
|Encryption Mode||drop-down menu||✓||choices are Off, SSL, or TLS|
|Certificate||drop-down menu||✓||select the certificate of the Active Directory server if SSL connections are used; if a certificate does not exist yet, create a CA, then create a certificate on the Active Directory server and import it to the FreeNAS® system with Certificates|
|Verbose logging||checkbox||✓||when checked, logs attempts to join the domain to
|UNIX extensions||checkbox||✓||only check this box if the AD server has been explicitly configured to map permissions for UNIX users; checking this box provides persistent UIDs and GUIDs, otherwise, users/groups are mapped to the UID/GUID range configured in Samba|
|Allow Trusted Domains||checkbox||✓||should only be enabled if network has active domain/forest trusts and you need to manage files on multiple domains; use with caution as it will generate more winbindd traffic, slowing down the ability to filter through user/group information|
|Use Default Domain||checkbox||✓||when unchecked, the domain name is prepended to the username; if Allow Trusted Domains is checked and multiple domains use the same usernames, uncheck this box to prevent name collisions|
|Allow DNS updates||checkbox||✓||when unchecked, disables Samba from doing DNS updates when joining a domain|
|Disable Active Directory user/group cache||checkbox||✓||when checked, disables caching AD users and groups; useful if you cannot bind to a domain with a large number of users or groups|
|User Base||string||✓||distinguished name (DN) of the user container in Active Directory|
|Group Base||string||✓||distinguished name (DN) of the group container in Active Directory|
|Site Name||string||✓||the relative distinguished name of the site object in Active Directory|
|Domain Controller||string||✓||will automatically be added to the SRV record for the domain and, when multiple controllers are specified, FreeNAS® selects the closest DC which responds; use the short form of the FQDN (Example: sampleserver)|
|Global Catalog Server||string||✓||if the hostname of the global catalog server to use is specified, make sure it is resolvable|
|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 9.1.2 for a summary of the available backends; click the Edit link to configure that backend’s editable options|
|Windbind NSS Info||drop-down menu||✓||defines the schema to use when querying AD for user/group info; rfc2307 uses the RFC2307 schema support 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 higher can be configured to enforce signed LDAP connections|
|Enable||checkbox||Enable the Active Directory service|
|NetBIOS name||string||✓||limited to 15 characters; automatically populated with the system’s original hostname; it must be different from the Workgroup name|
|NetBIOS alias||string||✓||limited to 15 characters|
Table 9.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.
|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 FreeNAS® servers on the network; for use in LDAP environments where Apple’s 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||an AD server is required to provide the mapping between the name and SID and an LDAP server is required to provide the mapping between the name and the UID/GID|
|rid||default for AD; requires an explicit idmap configuration for each domain, using disjoint ranges where a writeable default idmap range should be defined, using a backend like tdb or ldap|
|script||stores mapping tables for clustered environments in the winbind_cache tdb|
|tdb||default backend used by winbindd for storing mapping tables|
|tdb2||substitute for tdb used by winbindd in clustered environments|
Click the Rebuild Directory Service Cache button if a new Active Directory user needs immediate access to FreeNAS®. This occurs automatically once a day as a cron job.
Active Directory places restrictions on which characters are allowed in Domain and NetBIOS names, a limits the length of those names to 15 characters. If there are problems connecting to the realm, verify that your settings do not include any disallowed characters. Also, the Administrator account password cannot contain the $ character. If a $ exists in the domain administrator’s password, kinit will report a “Password Incorrect” error and ldap_bind will report 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 FreeNAS® 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 FreeNAS® system can be shown by using these commands from the FreeNAS® Shell. To view users:
To view groups:
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 FreeNAS® system to join Active Directory. Try bumping up the value of AD timeout to 60 seconds.
To change a certificate, set the Encryption Mode to Off, then disable AD by unchecking Enable. Click the Save button. Select the new Certificate, set the Encryption Mode as desired, set the Enable checkbox to re-enable AD, and click the Save button to restart AD.
9.1.1. Troubleshooting Tips¶
When running AD in a 2003/2008 mixed domain, refer to for instructions on how 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 the
host -t srv _ldap._tcp.domainname.com command to determine
the network’s SRV records and, if necessary, 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 Technet article
How DNS Support for Active Directory Works.
The realm that is used depends upon the priority in the SRV DNS record, meaning that DNS can override your Active Directory settings. When unable to connect to the correct realm, check the SRV records on the DNS server. This article describes how to configure KDC discovery over DNS and provides some examples of records with differing priorities.
If the cache becomes out of sync due to an AD server being taken off and back online, resync the cache using.
An expired password for the administrator account will cause kinit to fail, so ensure that the password is still valid. Also, double-check that the password on the AD account being used does not include any spaces or 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 FreeNAS® hostname in the name field. Make sure that it is under 15 characters and that it is the same name as the one set in the Hostname field in and the NetBIOS Name in settings. Make sure the hostname of the domain controller is set in the Domain Controller field of .
9.1.2. If the System Will not Join the Domain¶
If the system will not join the Active Directory domain, run these commands in the order listed. If any of the commands fail or result in a traceback, create a bug report at https://redmine.ixsystems.com/projects/freenas/issues that includes the commands in the order in which they were run and the exact wording of the error message or traceback.
Start with these commands, where the echo commands should return a value of 0 and the klist command should show a Kerberos ticket:
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
Next, only run these two commands if the Unix extensions box is checked in Advanced Mode and a keytab has been uploaded using Kerberos Keytabs:
service ix-sssd start service sssd start
Finally, run these commands. Again, the echo command should return a 0:
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 &
FreeNAS® 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 FreeNAS® LDAP service so network users can authenticate to the LDAP server and have authorized access to the data stored on the FreeNAS® system.
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 and instructions for using it can be found at The Linux Samba-OpenLDAP Howto. In addition, the LDAP server must support SSL/TLS and the certificate for the LDAP server CA must be imported with . Note that non-CA certificates are not supported at this time.
Apple’s Open Directory is an LDAP-compatible directory service into which FreeNAS® can be integrated. See FreeNAS with Open Directory in Mac OS X environments.
Figure 9.2.1 shows the LDAP Configuration screen that is seen after clicking .
Table 9.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 .
Those who are new to LDAP terminology should skim through the OpenLDAP Software 2.4 Administrator’s Guide.
|Hostname||string||hostname or IP address of LDAP server|
|Base DN||string||top level of the LDAP directory tree to be used when searching for resources (e.g. dc=test,dc=org)|
|Bind DN||string||name of administrative account on LDAP server (e.g. cn=Manager,dc=test,dc=org)|
|Bind password||string||password for Root bind DN|
|Allow Anonymous Binding||checkbox||✓||instructs LDAP server to not provide authentication and to allow read and write access to any client|
|User Suffix||string||✓||optional; can be added to name when user account added to LDAP directory (e.g. dept. or company name)|
|Group Suffix||string||✓||optional; can be added to name when group added to LDAP directory (e.g. dept. or company name)|
|Password Suffix||string||✓||optional; can be added to password when password added to LDAP directory|
|Machine Suffix||string||✓||optional; can be added to name when system added to LDAP directory (e.g. 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, or TLS; note that either SSL or TLS and a Certificate must be selected in order 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|
|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||✓||select the backend to use to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs; see Table 9.1.2 for a summary of the available backends; click the Edit link to configure the backend’s editable options|
|Samba Schema||checkbox||✓||only check this box if you need LDAP authentication for SMB shares and have already configured the LDAP server with Samba attributes|
|Auxiliary Parameters||string||✓||additional options for sssd.conf(5)|
|Schema||drop-down menu||✓||if Samba Schema is checked, select the schema to use; choices are rfc2307 and rfc2307bis|
|Enable||checkbox||uncheck to disable the configuration without deleting it|
|NetBIOS Name||string||✓||limited to 15 characters; automatically populated with the system’s original hostname; must be different from the Workgroup name|
|NetBIOS Alias||string||✓||limited to 15 characters|
Click the Rebuild Directory Service Cache button after adding a user to LDAP who needs immediate access to FreeNAS®. Otherwise this occurs automatically once a day as a cron job.
FreeNAS® automatically appends the root DN. This means that the scope and root DN should not 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 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
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 FreeNAS® system can be configured to import the users and groups from the NIS directory.
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.
|NIS domain||string||name of NIS domain|
|NIS servers||string||comma delimited list of hostnames or IP addresses|
|Secure mode||checkbox||if checked, 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 checked, 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||uncheck 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 FreeNAS®. Otherwise this occurs automatically once a day as a cron job.
9.4. Kerberos Realms¶
A default Kerberos realm is created for the local system in FreeNAS®. Add kerberos realm button to add the Kerberos realm. This configuration screen is shown in Figure 9.4.1.can be used to view and add Kerberos realms. If the network contains a KDC, click the
Table 9.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 .
|Realm||string||mandatory; name of the 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|
9.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 FreeNAS® 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 FreeNAS® 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
- 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, useto add it to the FreeNAS® system.
To instruct the Active Directory service to use the keytab, select the installed keytab using the drop-down Kerberos keytab menu in . 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 .
To instruct LDAP to use a principal from the keytab, select the principal from the drop-down Kerberos Principal menu in .
9.6. Kerberos Settings¶
To configure additional Kerberos parameters, use Figure 9.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).