Active Directory Connector Troubleshooting

Typical problems with using the AD Connector are improper settings and improper connectivity. This guide will cover validation and discovery of how to set up both items and also will contain some best practices to ensure proper operation throughout the continual use of the product. You should already be familiar with the User Guide for the Active Directory Connector.

The typical reasons why ClearOS will fail to join an AD domain are:

  • Improper Connectivity
    • DNS issues
    • Time issues
  • Improper Settings
    • Bad settings for domain, realm and/or server
    • Trusted Domain issues

Basic Troubleshooting

Try to see if you can get the list of domain users and groups via command line with these layers…

PAM layer

getent passwd
getent group

If everything is working you should see all your AD users and groups when running these two command. If it is not working through PAM, your local accounts and groups will only appear.

Winbind objects layer

wbinfo -u
wbinfo -g

If you are getting users and groups here but not in the previous, then the interactions and configurations of PAM need to be investigated. If you are getting partials, you may have an object in AD that doesn't translate well. This can also be indicative of a domain trust in existence that was not accounted for in the smb.conf files. If you get no data then dig deeper:

Winbind Trust layer

wbinfo -t

Either trust is there or it is not. If trust exists, we need to search higher. If trust is failiing, dig deeper.

Domain Join

Sometimes small hiccups in things like DNS and time can cause a join to not work. It is also possible that a machine account already exists in the domain from a previous install. If this is the case locate the object in AD for the ClearOS server and delete it. Then manually join the domain with:

net ads join -U administrator

It will prompt with a password. The account you use (administrator in example) is the AD account with rights to join the domain. If your configuration of time and DNS are proper, you should join ok and then proceed back up the stack to see if all things are coming into focus. If not have a look for error messages.

If you get something like:

# net ads join -U administrator
Enter administrator's password:
Using short domain name -- SAMDOM
Joined 'AD-Member' to dns domain ''
No DNS domain configured for AD-Member. Unable to perform DNS Update.

Then the join has succeeded and only the DNS updated failed. You need to add “Server Name”.“ADS REALM” and “Server Name” pointing to your ClearOS LAN IP in the DNS Server then run the:

net ads join -U administrator


Gateway Management

If you have installed and activated Gateway Management you must configure a Rainbow List for your AD DC's. Please see the “Active Directory Considerations” section of Gateway Management Documentation which takes you to this DNSThingy support article. The Rainbow list must be enabled for each rule set.

Fixing Improper Connectivity

ClearOS requires at least two very important things (other than the correct server, username and password) to make a proper Kerberos connection. Specifically, the DNS and time must be correct between the ClearOS server and the Active Directory environment. The settings must also conform and if there are or were trusted domains to the AD realm, they need to be accounted for.


It is crucial that the DNS is configured properly on the ClearOS server. Specifically, ClearOS needs to know about SRV and other records related to the domain that are only to be had via DNS. If ClearOS is using an external DNS server for resolution of your internal domain, you will frequently fail to make a connection. This means that even if you have your AD server in the mix of other DNS servers, you will frequently fail if those other DNS servers tell ClearOS that the DNS query is invalid.

It is wrong to have your AD domain controller as one among several public DNS servers listed for your DNS settings. That is because the public servers will not know the AD DNS entries, so your query will fail anytime they respond before your AD server will.

There are two solutions to this problem, you can either set your AD server or servers as your only DNS provider. Or, you can have local ClearOS DNS caching server use the AD server exclusively for all queries of your AD domain zone. Either way, when the question of the domain comes up, ClearOS will ALWAYS get the right answer.

Exclusive for all queries (easy to configure, not as scalable)

This method is simple. Navigate to the IP Settings module in ClearOS under the Network category. Remove all entries except for the IP address(es) of the AD DNS server(s).

Split Horizon DNS - Exclusive for zone only queries (robust and scalable, requires command line to configure)

The next method is recommended and can now be done through the Active Directory Connector app. This method has you set your optimal DNS servers in the IP Settings, which exclude your AD servers (for example, the DNS servers of your ISP) and then specify queries for your AD DNS zone to go directly to the internal AD DNS server. The advantage to this is that the caching DNS server of ClearOS is very fast and can supply the answers for not only its own queries but also for any hosts on the network. Because it knows the fastest way to get the right answers, it is best all around.

You must not use a Split DNS Cache configured either manually or through the Active Directory Connector app when using Gateway Management. Instead, use a Rainbow/Forwarding List in Gateway Management
Quick DNS Test

If you are having difficulty connecting to Active Directory initially or perhaps you have lost connectivity, you can try the following:

dig @localhost srv _ldap._tcp.dc._msdcs.$(egrep "^realm" /etc/samba/smb.conf | awk -F" = " '{ print$2 }') | \
  egrep "^_ldap\._tcp\.dc\._msdcs\.$(egrep "^realm" /etc/samba/smb.conf | \
  awk -F" = " '{ print$2 }')\.\s[0-9]+\sIN\sSRV\s[0-9]+\s[0-9]+\s[0-9]+\s$(egrep "^password server" /etc/samba/smb.conf | \
  awk -F" = " '{ print$2 }')\.$"

This should tell you the domain that is covered by your AD DNS and will let you know what parameters you can add to the /etc/dnsmasq.conf for your servers.

Implementing Exclusive DNS

Open this guide and use the information you collected for the Domain Name.

Recommended DNS Configuration Guide for AD Connector (without Gateway Management).

While you are at it, you can improve DNS performance for a nominal cost in used bandwidth by implementing parallel instead of serial queries to external DNS sources. This means that if there is a query, it will request all DNS servers for a response simultaneously instead of processing them one at a time.

DNS with Gateway Management

If you are using Gateway Management you have to use ClearOS as your Primary DNS server and use Active Directory to only do the DNS name resolution for the internal DNS. To do this you have to use Rainbow Lists in Gateway Management rather than the “Implementing Exclusive DNS” article.


The Kerberos system of your Active Directory is very particular about time. That is because in the authentication request sensitivity to time is important for security. Because of this, the time on your AD server and the time on your ClearOS server must match.

Is this the problem?

One way to test the drift in your time between your AD server and your local computer is to use the following command:

abs () { [ $1 -lt 0 ] && echo $((-$1)) || echo $1; } && abs \
  $(expr $(date -d "$(net time -S $(egrep "^password server" /etc/samba/smb.conf | awk -F" = " '{ print$2 }'))" "+%s") - $(date "+%s"))

If the result is greater then 60 then there is a problem. Check your time zones and make sure your servers are in the same time zone.

Changing Time

You can manually override the time on the ClearOS server using the command:

date -s "2 SEP 2015 08:57:45"

Doing this will only temporarily change the time because ClearOS, by default, will sync the time back slowly to its time source. When this happens, if it is different than your AD Server, your connection via the AD Connector will break again.

When joining or authenticating to the AD Server you can be off by a little bit but it is better to have a mechanism in place for them to be the same. There are two ways to do this the first is dependent on connectivity to the Internet always being present. The second, which is recommended, keeps the ClearOS server's time set to the same of the AD server, even if the AD server is wrong. But that is OK and preferred because it is better for them both to be wrong together than just have one of them right.

Using the same time source

By default, ClearOS will set its time to synchronize with the external time source of:

You can change ClearOS to use the time server that your Windows Server uses, or you can change the time server that your Windows Server uses to be ''.

To change the time server on ClearOS, modify the file '/etc/clearos/date.conf'

To change the time servers used by Windows, consult this guide.

By far, the best solution for time is to have Active Directory server dish up time to ClearOS and all your workstations. Using this method, your AD server can still sync it's time from a clock on the Internet but all the workstations and other servers will get their time from your central time server.

As stated previously, the advantage to this structure is that your servers and workstations will have the same time as the server even if you experience and extended disconnect from the Internet. Again, it is more important for Kerberos that the time is the same across access devices than that the time is accurate.

To set up Windows Server as a time server, please consult your Server's documentation or any other trusted userguide for the process of setting up NTP under windows. Here is one such guide.

Once this is accomplished, update the /etc/clearos/date.conf file on ClearOS to point to the IP address or hostname of your Windows Server. Restart your ClearOS server and then validate that the time is the same or that it is slowly getting closer and closer to being in sync with the Windows server. You can issue the date command from your command prompt to see what the time is or to speed up the drift towards an accurate time.

Fixing Improper Settings

Configuration Fields

Another common mistake in setting up the Active Directory Connector is the use of settings in the interface. These settings are required and have to follow a particular standard for an AD domain.

The 5 pieces of information required are:

  • Windows Domain
  • ADS Realm
  • Domain Controller
  • Administrator Account
  • Administrator Account Password
Windows Domain

This setting is the short name for your LanManager Domain. Before Windows adopted an LDAP-based backend for their directory, they had developed a network operating system platform in conjunction with 3com called LAN Manager. On top of this design, they layered the Server Message Block (SMB) protocol on top of the NetBIOS Frames protocol (NBF). There have been many, many improvements over the years to their methods and abilities but there are some legacy things that are required in order for ClearOS to ALSO provide backwards and extend compatibility to subsystems that will use the authentication hooks within ClearOS. To that end, you will need the old-style NT domain name of your Windows AD domain. What you are looking for here is what is called the 'Domain Name (pre-Windows 2000):' setting.

On your domain controller, open up the Active Directory Users and Computers MMC (dsa.msc). Right click on your domain, choose Properties. Click the General tab and look for the entry 'Domain Name (pre-Windows 2000):'. You should see a name for your domain that is 15 or less characters that is all upper-case. Insert this name into the Active Directory Connector module of ClearOS for the 'Domain Name' setting.

For more information, please read this article.

ADS Realm

While you have the Active Directory Users and Computers MMC (dsa.msc) open, you can get your ADS Realm here as well. In the same properties sheet, it will list your ADS Realm on the General page at the top. This can be your domain name, or internal domain name or some other convention. Common examples may end in '.local' or some other scheme.

When inserting this information, try using all uppercase characters if you encounter any issues.

For more information, please read this article.

Windows Server

This is the hostname of your Active Directory Global Catalog server. It can be ANY of your global catalog servers but it should be one of your most reliable ones. The entry here should be the hostname and NOT the IP address of the server. You should already be resolving DNS properly to this hostname before attempting to join the domain. If your Active Directory Global Catalog server's name was ad1.example.local you should be able to ping the following from the command line of ClearOS:

ping ad1.example.local

Entries in this field should be in lower case.


This is an account that has authorization to join workstations to the domain. Typically the account is named Administrator but it is possible for additional administrators or alternately named administrator accounts to be entered here. You should NOT use the 'domain\username' or the 'username@domain-name 'form of the user account.

Trusted Domain Issues

If your AD forest trusts another domain or forest then you will need to account for this. This happens because ClearOS is converting the way that Microsoft does things into POSIX (Linux, Unix, MacOSX, et al.) way of doing things. To do this, it creates a map. By default, ClearOS maps connectivity based on the 'resource ID' used by windows to a specific algorithm. But, by default, this is pegged to a single domain forest. If you use or have used other forests, those 'resource IDs' will be duplicated which means that ClearOS must have another algorithm to account for those other domains.

If this is your case, please review this document

Wrapping it all up

If this fails, review the process again. Please also review the documentation listed at the top of this article for the appropriate userguide.

If you have an error after using these methods, please contact support by opening a ClearCARE ticket.

Once your server is joined to the domain, user accounts and groups should start to appear under the Users and Groups modules. Please note that these are read-only objects and if you want to add a user or group account, you will need to do that under your Active Directory or Samba Directory server.

Various services use 'plugin' groups for access. You will need to make groups under Active Directory with the correct username to allow for access to the service associated under ClearOS. Consult the userguides at the top of this article for information on those exact names.

content/en_us/kb_troubleshooting_the_ad_connector.txt · Last modified: 2019/08/27 09:54 by nickh