1.4. Troubleshooting Directory Services

1.4.1. Directory Services Debug Logs

When you're trying to troubleshoot issues with Directory Services on Mac OS X sometimes the best thing you can do is put the directoryservices daemon into debug mode. To do so, we must send a USR1 signal to the daemon using the following command:

killall -USR1 DirectoryService

By default errors get trapped into this file:

/Library/Logs/DirectoryService/DirectoryService.error.log

But when in debug mode using -USR1, you can see more specific errors here:

/Library/Logs/DirectoryService/DirectoryService.debug.log

You can then use commands such as tail and more in conjunction with grep to isolate issues to specific strings such as ADPlugin. Alternatively, you can enable API logging if you choose to send the -USR2 signal. For debugging then, the logs will get written into the /var/log/system.log file.

To disable verbose logging, you can just restart the Directory Services daemon if you originally sent a -USR1 signal to DirectoryService. If you used -USR2, debugging information will automatically stop writing to the log after 5 minutes.

1.4.2. Cache

In some cases, you may find that certain lookup tools, such as id, return data which differs from what is stored in the directory. This is typically caused by stale data stored in the local machine's cache. While this cache will eventually expire and update, it may be desirable to manually flush the cache. In version 10.4, this was accomplished using lookupd:

lookupd -flushcache

Unfortunately, lookupd has gone to tech heaven, abandoned after 10.4. Introduced with 10.5, the tool dscacheutil allows for more cache-specific functionality than lookupd. For example, using -cachedump allows you to dump an overview of the cache contents. The -cachedump command has a slew of flags to get pretty granular with the output, such as -entries and -buckets. The -configuration command allows you to access detailed information about your search policy, and -statistics allows you to view detailed information on the statistics of calls.

Here are some examples of using these commands:

dscacheutil -flushcache to empty the DNS Cache Resolver;

dscacheutil -cachedump -entries user to dump cache with user entries;

dscacheutil -q user to look up all users on a system;

dscacheutil -q user -a name jdoe to look up data for user jdoe.

The dscacheutil tool is also one of two command-line utilities that allow you to query a group for direct membership (querying raw membership attributes with dscl is the other). However, this functionality is somewhat limited as dscacheutil does not consistently recurse through nested group membership. It does, however, work with basic membership. For instance, to list members of the group admin, you could use:

dscacheutil -q group -a name admin

1.4.3. Verifying Authentication

There are a number of ways that you can test authentication in OS X, and the exact process will vary based upon the version of the OS that you are running. Naturally, you can verify authentication for a user by attempting to login to a bound Mac OS client. The main problem with this type of testing is that it is fairly inefficient; if you don't have a spare client to test with, a trip to the login window likely requires you to logout. On top of this, home directory problems can prevent a successful login, so it is not always an accurate test.

If the target user has a default shell assigned, you can test authentication using the su command in any version of OS X. Simply open up a new shell and type su testuser. You will be prompted to enter the user's password. Provided that you entered in accurate credentials, you will be granted a shell under the new user. You can use the id tool to verify.

bash-3.2$ su testuser
Password:
bash-3.2$ id
uid=1078(testuser)

This is not the only means to do this, however. In 10.5 a new utility, dirt, was introduced solely for the purpose of testing authentication. The dirt utility is unique to Leopard and can be used to test Directory Service user resolution and authentication. You can use dirt to test authentication for users residing in local, LDAP, or Active Directory nodes. The -u flag uses the username from the node you are testing against. The dirt command tests whether an account exists in any node and can be used with the following structure:

dirt -u corpadmin -n '/Active Directory/domainname'

This would result in the following output if the account is located in Active Directory:

User username was found in:
/Active Directory/domainname

In addition to lookups, the dirt tool can be used to test authentication. For instance, to test authentication for user jdoe, use the following command:

dirt -u jdoe

After running this command, you will be prompted for the password, which can also be specified when invoking the command using the -p flag. Once you provide a password, the tool will output whether or not authentication succeeded, as well as some user data.

Unfortunately, the dirt utility is not included with 10.6. Not all is lost, though: this functionality was rolled into Apple's other directory services tool, dscl. To test authentication using dscl, 10.6 introduces the -authonly flag, which must be called with at least a username. The password can be supplied optionally after the username:

$ dscl /Search -authonly testuser "MySuperSecretPassword"
Password:
$

As this shows, if you provide the correct password, the dscl utility will exit with a 0 status and will return you directly to your shell prompt with no feedback. This indicates a successful authentication. If authentication is not successful, you will be greeted with an eDSAuthFailed error:

$ dscl /Search -authonly testuser "MySuperPass"
Authentication for node /Search failed. (-14090, eDSAuthFailed)
<dscl_cmd> DS Error: −14090 (eDSAuthFailed)

Notice also in the previous example that we are calling dscl specifically with the /Search search path. We could specify an explicit node to authenticate against:

$ dscl /LDAPv3/odm.myco.com -authonly testuser "MySuperSecretPassword"