12. Directory Services¶
FreeNAS® supports integration with these directory services:
- Active Directory (for Windows 2000 and higher networks)
- LDAP
- NIS
FreeNAS® also supports Kerberos Realms, Kerberos Keytabs, and the ability to add more parameters to Kerberos Settings.
This section summarizes each of these services and the available configuration options within the FreeNAS® web interface. After successfully enabling a directory service, appears in the top toolbar row. Click to show the Directory Services Monitor menu. This menu shows the name and status of each directory service.
12.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 the same user accounts on the FreeNAS® system. Instead, configure the Active Directory service so 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.3 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 FreeNAS® system. If the ping fails, check the DNS server and default gateway settings in on the FreeNAS® system.
By default, Allow DNS updates in the Active Directory options is enabled. This adds FreeNAS® 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. During the domain join process the PDC emulator FSMO role server is added as the preferred NTP server. The time on the FreeNAS® system and the Active Directory Domain Controller cannot be out of sync by more than five minutes in a default Active Directory environment. An Alert is sent when the time is out of sync.
To ensure both systems are set to the same time:
- use the same NTP server (set in on the FreeNAS® system)
- set the same timezone
- set either localtime or universal time at the BIOS level
Figure 12.1.1 shows settings.
Fig. 12.1.1 Configuring Active Directory
Table 12.1.1 describes the configurable options. Some settings are only available in Advanced Mode. Click the ADVANCED MODE button to show the Advanced Mode settings. Go to and set the Show advanced fields by default option to always show advanced options.
| Setting | Value | Advanced Mode | Description |
|---|---|---|---|
| Domain Name | string | Name of the Active Directory domain (example.com) or child domain (sales.example.com). This field is mandatory. Save will be inactive until valid input is entered. Hidden when a Kerberos Principal is selected. | |
| Domain Account Name | string | Name of the Active Directory administrator account. This field is mandatory. Save will be inactive until valid input is entered. Hidden when a Kerberos Principal is selected. | |
| Domain Account Password | string | Password for the Active Directory administrator account. Required the first time a domain is configured. After initial configuration, the password is not needed to edit, start, or stop the 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 or import a Certificate Authority, then create a certificate on the Active Directory server. Import the certificate to the FreeNAS® system using the Certificates menu. It is recommended to leave this drop-down unset when configuring LDAPs. To clear a saved certificate, choose the blank entry and click SAVE. |
| Validate Certificate | checkbox | ✓ | Check server certificates in a TLS session. |
| Verbose logging | checkbox | ✓ | Set to log attempts to join the domain to /var/log/messages. |
| 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. Unset to prevent name collisions when Allow Trusted Domains is set and multiple domains use the same username. |
| Allow DNS updates | checkbox | ✓ | Set to enable Samba to do DNS updates when joining a domain. |
| Disable FreeNAS 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. |
| Kerberos Realm | drop-down menu | ✓ | Select the realm created using the instructions in Kerberos Realms. |
| Kerberos Principal | drop-down menu | ✓ | Select a keytab created using the instructions in Kerberos Keytabs. Selecting a principal hides the Domain Account Name and Domain Account Password fields. An existing account name is not overwritten by the principal. |
| Computer Account OU | string | ✓ | The OU in which new computer accounts are created. The OU string is read from top to bottom without RDNs. Slashes
(/) are used as delimiters, like Computers/Servers/NAS. The backslash (\) is used to escape
characters but not as a separator. Backslashes are interpreted at multiple levels and might require doubling or even
quadrupling to take effect. When this field is blank, new computer accounts are created in the Active Directory default OU. |
| AD Timeout | integer | ✓ | Increase the number of seconds before timeout if the AD service does not immediately start after connecting to the domain. |
| DNS Timeout | integer | ✓ | Increase the number of seconds before a timeout occurs if AD DNS queries timeout. |
| Idmap backend | drop-down menu and Edit Idmap button | ✓ | Choose the backend to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs. See Table 12.1.2 for a summary of the available backends. Click Edit Idmap to configure the selected backend. |
| Windbind NSS Info | drop-down menu | ✓ | Choose the schema to use when querying AD for user/group information. rfc2307 uses the RFC2307 schema support included in Windows 2003 R2, sfu is for Services For Unix 3.0 or 3.5, and sfu20 is for Services For Unix 2.0. |
| SASL wrapping | drop-down menu | ✓ | Choose 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. This should be set to PLAIN when using Microsft Active Directory. This can be set to SIGN or SEAL when using Samba Active Directory if allow sasl over tls has been explicitly enabled in the Samba Domain Controller configuration. |
| Enable (requires password or Kerberos principal) | checkbox | Activate the Active Directory service. | |
| Netbios Name | 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 alias | string | ✓ | Limited to 15 characters. |
Table 12.1.2 summarizes the backends which are available in the Idmap backend drop-down menu. Each backend has its own man page that gives implementation details.
Changing idmap backends automatically refreshes 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 FreeNAS® system and enter
service samba_server status. To manually send the SIGHUP,
enter kill -HUP pid, where pid is the parent process ID.
| 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 or GIDs to use for user and group mappings and an optional size for the ranges. |
| 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 the winbind_cache tdb. |
| tdb | Default backend used by winbindd for storing mapping tables. |
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.
It can take a few minutes after configuring the Active Directory service for the AD information to be populated to the FreeNAS® system. To check the AD join progress, open the web interface Task Manager in the upper-right corner. Any errors during the join process are also displayed in the Task Manager.
Once populated, the AD users and groups will be available in the drop-down menus of the Permissions screen of a dataset.
The Active Directory users and groups that are imported to the FreeNAS® system are shown by typing commands in the FreeNAS® 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 FreeNAS® system taking longer than the default ten seconds to join Active Directory. Increase the value of AD timeout to 60 seconds.
12.1.1. Leaving the Domain¶
A Leave Domain button appears on the service dialog when a domain is connected. To leave the domain, click the button and enter credentials with privileges sufficient to permit leaving.
12.1.2. Troubleshooting Tips¶
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 Technet article
How DNS Support for Active Directory Works.
The realm used depends on 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.
An expired password for the administrator account will cause kinit to fail. Ensure the password is still valid and 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 Organizational Unit (OU). When creating this entry, enter the FreeNAS® hostname in the name field. Make sure it is under 15 characters, the same name as the one set in the Hostname field in , and the same NetBIOS alias in settings.
If the cache becomes out of sync due to an AD server being taken off and back online, resync the cache using .
If any of the commands fail or result in a traceback, create a bug report at https://bugs.ixsystems.com. Include the commands in the order in which they were run and the exact wording of the error message or traceback.
12.2. LDAP¶
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 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 FreeNAS® LDAP service so network users can authenticate to the LDAP server and have authorized access to the data stored on the FreeNAS® system.
Note
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. The LDAP server must support SSL/TLS and the certificate for the LDAP server CA must be imported with . Non-CA certificates are not currently supported.
Tip
Apple’s Open Directory is an LDAP-compatible directory service into which FreeNAS® can be integrated. The forum post FreeNAS with Open Directory in Mac OS X environments has more information.
Figure 12.2.1 shows the LDAP Configuration section from .
Fig. 12.2.1 Configuring LDAP
Table 12.2.1 summarizes the available configuration options. Some settings are only available in Advanced Mode. Click the ADVANCED MODE button to show the Advanced Mode settings. Go to and set the Show advanced fields by default option to always show advanced options.
Those new to LDAP terminology should read the OpenLDAP Software 2.4 Administrator’s Guide.
| Setting | Value | Advanced Mode | Description |
|---|---|---|---|
| Hostname | string | LDAP server hostnames or IP addresses. Separate entries with an empty space. Multiple hostnames or IP addresses can be entered to create an LDAP failover priority list. If a host does not respond, the next host in the list is tried until a new connection is established. | |
| 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 | Administrative account name on the LDAP server (Example: cn=Manager,dc=test,dc=org). | |
| Bind Password | string | Password for the Bind DN. Click SHOW/HIDE PASSWORDS to view or obscure the password characters. | |
| Allow Anonymous Binding | checkbox | ✓ | Instruct the LDAP server to disable authentication and allow read and write access to any client. |
| Kerberos Realm | drop-down menu | ✓ | The realm created using the instructions in Kerberos Realms. |
| Kerberos Principal | drop-down menu | ✓ | The location of the principal in the keytab created as described in Kerberos Keytabs. |
| Encryption Mode | drop-down menu | ✓ | Options for encrypting the LDAP connection:
|
| Certificate | drop-down menu | ✓ | Certificate to use when performing LDAP certificate-based authentication. To configure LDAP certificate-based authentication, create a Certificate Signing Request for the LDAP provider to sign. A certificate is not required when using username/password or Kerberos authentication. |
| Validate Certificate | checkbox | ✓ | Verify certificate authenticity. |
| Disable LDAP User/Group Cache | checkbox | ✓ | Disable caching LDAP users and groups in large LDAP environments. When caching is disabled, LDAP users and groups do not appear in dropdown menus, but are still accepted when manually entered. |
| 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 | ✓ | Backend used to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs. See Table 12.1.2 for a summary of the available backends. To configure the selected backend, click EDIT IDMAP. |
| Samba Schema | checkbox | ✓ | Set if LDAP authentication for SMB shares is required and the LDAP server is already configured with Samba attributes. |
| Auxiliary Parameters | string | ✓ | Additional options for nslcd.conf. |
| 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. |
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 in the FreeNAS® Shell to verify the users have been imported. Type getent group to verify the groups have been imported. When the Samba Schema is enabled, LDAP users also appear in the output of pdbedit -L.
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.
Any LDAP bind errors are displayed during the LDAP bind process. When
troubleshooting LDAP, you can open the FreeNAS® Shell and find
nslcd.conf errors in /var/log/messages. When
Samba schema is enabled, any Samba errors are recorded in
/var/log/samba4/log.smbd. Additional details are saved in
/var/log/middlewared.log.
To clear LDAP users and groups from FreeNAS®, go to , clear the Hostname field, unset Enable, and click SAVE. Confirm LDAP users and groups are cleared by going to the and viewing the output of the getent passwd and getent group commands.
12.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 FreeNAS® system can be configured to import the users and groups from the NIS directory.
Click the Rebuild Directory Service Cache button if a new NIS user needs immediate access to FreeNAS®. This occurs automatically once a day as a cron job.
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 12.3.1 shows the section. Table 12.3.1 summarizes the configuration options.
Fig. 12.3.1 NIS Configuration
| Setting | Value | Description |
|---|---|---|
| NIS domain | string | Name of NIS domain. |
| NIS servers | string | Comma-delimited list of hostnames or IP addresses. |
| Secure mode | checkbox | Set to have ypbind(8) refuse to bind to any NIS server not running as root on a TCP port over 1024. |
| Manycast | checkbox | Set to have ypbind to 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. |
12.4. Kerberos Realms¶
A default Kerberos realm is created for the local system in FreeNAS®. can be used to view and add Kerberos realms. If the network contains a Key Distribution Center (KDC), click ADD to add the realm. The configuration screen is shown in Figure 12.4.1.
Fig. 12.4.1 Adding a Kerberos Realm
Table 12.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 setting Show advanced fields by default in .
| Setting | Value | Advanced Mode | Description |
|---|---|---|---|
| Realm | string | 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. |
12.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 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 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.keytabis the file to upload to the FreeNAS® server.useraccountis the name of the user account for the FreeNAS® server generated in Active Directory Users and Computers.http/useraccount@EXAMPLE.COMis 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/princfor more details.userpassis the password associated withuseraccount.
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, add it to the FreeNAS® system using .
To instruct the Active Directory service to use the keytab, select the installed keytab using the drop-down Kerberos Principal menu in Advanced Mode. When using a keytab with Active Directory, make sure that 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 Advanced Mode.
12.6. Kerberos Settings¶
Configure additional Kerberos parameters in the section. Figure 12.6.1 shows the fields available:
Fig. 12.6.1 Additional Kerberos Settings
- Appdefaults Auxiliary Parameters: Define any additional settings for use by some Kerberos applications. The available settings and syntax is listed in the [appdefaults] section of krb.conf(5).
- Libdefaults Auxiliary Parameters: Define any settings used by the Kerberos library. The available settings and their syntax are listed in the [libdefaults] section of krb.conf(5).