Get a Quote   (408) 943-4100               TrueNAS Discord      VendOp_Icon_15x15px   Commercial Support Toggle between Light and Dark mode
TrueNAS.com Software Systems Company Community Security iX Portal Download

  1. Documentation Hub
  2. /
  3. TrueNAS CORE and Enterprise
  4. /
  5. Configuration Tutorials
  6. /
  7. Directory Services
  8. /
  9. Setting Up Active Directory
Edit this page

Setting Up Active Directory

  6 minute read.

Last Modified 2022-05-18 14:44 EDT

The Active Directory (AD) service shares resources in a Windows network. AD provides authentication and authorization services for the users in a network, eliminating the need to recreate the user accounts on TrueNAS.

Once joined to an AD domain, you can use domain users and groups in local ACLs on files and directories. You can also set up shares to act as a file server.

Joining an AD domain also configures the Privileged Access Manager (PAM) to let domain users log on via SSH or authenticate to local services.

Users can configure AD services on Windows or Unix-like operating systems running Samba version 4.

To configure a connection, you need to know the Active Directory domain controller domain and the account credentials for that system.

Preparation

Users can take a few steps before configuring Active Directory to ensure the connection process goes smoothly.

To confirm that name resolution is functioning, go to the Shell and use ping to check the connection to the AD domain controller.

ShellDomainControllerPing

When packets are sent and received without loss, the connection is verified. Press Ctrl + C to cancel the ping.

Another option is to use the command host -t srv _ldap._tcp.domainname.com to check the network SRV records and verify DNS resolution.

If the ping fails, go to Network > Global Configuration and update the DNS Servers and Default Gateway settings so the connection to your Active Directory Domain Controller can start. Enter more than one value in Nameserver for the AD domain controllers so DNS queries for requisite SRV records can succeed. Using more than one name server helps maintain the AD connection whenever a domain controller becomes unavailable.

Active Directory relies on Kerberos, a time-sensitive protocol. During the domain join process, the AD domain controller with the PDC Emulator FSMO Role is added as the preferred NTP server. If your environment requires something different, you can change NTP server settings in System > NTP Servers.

The local system time cannot be out of sync by more than five minutes with the AD domain controller time in a default AD environment. Use an external time source when configuring a virtualized domain controller. TrueNAS creates an Alert if the system time gets out of sync with the AD domain controller time.

There are a few options in TrueNAS to ensure both systems are synchronized:

  • Go to System > General and make sure the value in Timezone matches the AD Domain Controller.

SystemGeneralTimezoneOptions

  • Select either localtime or universal time in the system BIOS.

Connect to the Active Directory Domain

To connect to Active Directory, go to Directory Services > Active Directory and enter the AD Domain Name and account credentials. Set Enable to attempt to join the AD domain immediately after saving the configuration.

DirectoryServicesActiveDirectoryExample

Advanced options are available for fine-tuning the AD configuration, but the preconfigured defaults are generally suitable.

TrueNAS can take a few minutes to populate the AD information after configuring the Active Directory service. To check the AD join progress, open the Task Manager in the upper-right corner. TrueNAS displays any errors during the join process in the Task Manager.

When the import completes, AD users and groups become available while configuring basic dataset permissions or an Access Control List (ACL) with TrueNAS cache enabled (which is the default setting).

Joining AD also adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT keytab. TrueNAS automatically begins using this default keytab and removes any administrator credentials stored in the TrueNAS configuration file.

FTP Access

While SFTP is recommended over FTP, joined systems do allow FTP access. Keep these caveats in mind:

  • Authentication uses DOMAIN\username as the user name by default.
  • A user home directory needs to exist before joining.
  • An AD user cannot be added to the FTP group. Enable local user auth for FTP instead.
  • An existing samba homes share created in the GUI is set as the template homedir for AD users. This means that AD user home directories are set inside that path. Proper permissions are vital.
  • There are no guarantees about how proftpd handles ACLs.
  • The admin (or pam_mkhomedir) must ensure that paths exist when AD users have populated homedir information in their LDAP schema.
  • When the admin is pulling home directories from their LDAP schema, take extra caution to insure that users aren’t writing files to the boot device.

Troubleshooting

If the cache becomes out of sync or fewer users than expected are available in the permissions editors, resync it using Directory Service > Active Directory > REBUILD DIRECTORY SERVICE CACHE.

If you are using Windows Server with 2008 R2 or older, try creating a Computer entry on the Windows server Organizational Unit (OU). When creating this entry, enter the TrueNAS hostname in the name field. Make sure it is the same name as the one set in the Hostname field in Network > Global Configuration, and the NetBIOS alias from Directory Service > Active Directory > Advanced Options.

You can go to the Shell and enter various commands to get more details about the AD connection and users:

  • AD current state: midclt call activedirectory.get_state.
  • Details about the currently connected Lightweight Directory Access Protocol (LDAP) server: midclt call activedirectory.domain_info | jq. Example:
    truenas# midclt call activedirectory.domain_info | jq
{
  "LDAP server": "192.168.1.125",
  "LDAP server name": "DC01.HOMEDOM.FUN",
  "Realm": "HOMEDOM.FUN",
  "Bind Path": "dc=HOMEDOM,dc=FUN",
  "LDAP port": 389,
  "Server time": 1593026080,
  "KDC server": "192.168.1.125",
  "Server time offset": 5,
  "Last machine account password change": 1592423446
}
  • View AD users: wbinfo -u. To see more details about a user, enter getent passwd DOMAIN\\<user>, replacing <user> with the desired user name. If wbinfo -u shows more users than appear to be available when configuring permissions and the TrueNAS cache is enabled, go to Directory Services > Active Directory and increase the AD Timeout value.
  • View AD groups: wbinfo -g. To see more details, enter getent group DOMAIN\\domain\ users.
  • View domains: wbinfo -m.
  • Test AD connection: wbinfo -t. A successful test shows a message similar to checking the trust secret for domain YOURDOMAIN via RPC calls succeeded.
  • User connection test to an SMB share: smbclient '//127.0.0.1/smbshare -U AD01.LAB.IXSYSTEMS.COM\ixuser, replacing 127.0.0.1 with your server address, smbshare with the SMB share name, AD01.LAB.IXSYSTEMS.COM with your trusted domain, and ixuser with the user account name for authentication testing.

Additional Information

Active Directory Screen