TweetFollow Us on Twitter

Troubleshooting Directory Services

Volume Number: 23 (2007)
Issue Number: 06
Column Tag: MacEnterprise

Troubleshooting Directory Services

The basics

By Philip Rinehart, Yale University

Directory Services

One of the most common questions that are discussed on the MacEnterpise mailing list is the diagnosis and analysis of integration of OS X with Directory Services. While most commonly talked about in reference to Active Directory, many of the tools that can be used are applicable to any Directory Service, as most rely on the same core foundation. The first step of any analysis and troubleshooting is based on having a solid Domain Naming System, commonly known as DNS.

DNS problems

How does one go about troubleshooting DNS on OS X? More importantly, what should be tested and in what order? Checking forward and reverse DNS records usually makes the most sense initially. Misconfigured DNS information can often be the root of Directory Service problems. If the administrator configuring DNS has not correctly set both the forward and reverse DNS records, any attempt to bind or use a Directory Service becomes incrementally difficult.

Testing forward DNS

The first step is to test forward DNS records. As a brief reminder, forward DNS is the process of looking up a domain name and having the IP address returned. There are many tools to test this functionality, but one that can quickly test forward DNS resolution is the command line tool, host. Open a terminal, and type in host name.domain.com. If the forward DNS record is properly set up, the return should be: host name.domain.com has address 111.222.333.444. Easy, right?

Testing reverse DNS

Next, test reverse DNS records. Reverse DNS is the process of taking an IP address, and resolving it to a domain name. As before, using the host command line tool is easiest. Open a terminal, and type in host 111.222.333.444. If the reverse DNS record is properly set up, the return should be: host 444.333.222.111.in-addr.arpa domain name pointer name.domain.com. It cannot be emphasized enough how important it is to have correctly configured forward and reverse DNS records. In particular, the Active Directory plug-in can be very sensitive to incorrect DNS configuration. Generally, if DNS is functioning correctly, binding to any Directory Service should be trivial. So, if DNS is working, what should be the next step?

Network problems

At times, testing DNS using host can point to the cause of Directory Service problems. However, it is very important to note that testing this is only testing servers providing the DNS records, not necessarily the resolution by the client machine.

The first, and most obvious way to test network connectivity is with the use of ping. Ping the server providing directory services, and determine whether the client has connectivity with the provider. Silly as it sounds, check the cable or IP address being provided by a wireless server. Often the simple things are the solution!

Next, using the tool lookupd, client side DNS resolution can be tested. Testing reverse DNS, using the interactive debug mode, can verify that the results returned by using host are what the client is using as well. Invoke the debugger with lookupd -d. Following the same testing procedure, first enter:

hostWithName: hostname.domain.com

Next, enter:

hostWithInternetAddress: 111.222.333.444

Both commands will return a lot of information, including the agent that is being used by the client, as well as cache information, and how many hits have occurred by the operating system. This information can point to subtle DNS problems if it is different from the information returned by the host command.

Authentication problems

If a machine is successfully bound, the next most common problem that is reported is the inability to authenticate to a directory service exhibited by a shaking login window. Let's tackle the simplest way to test authentication first.

Dirt

Dirt? Never heard of the tool? It is a lesser-known tool that can be used to test Directory Services from the command line. It is particularly useful when used to test authentication against a bound Directory Service. The syntax can be a little tricky, but when used, it can be quite powerful. The first test is to check that the user exists in the Directory Services node. Here's how, open a terminal and type:

dirt -u username -n

The return value should be:

User username was found in:
/DSNode

This test simply does a quick verification of the username that is being used to login, and makes sure that the OS X client can see the information contained by the Directory Node. Next, test user authentication using the node name as follows:

dirt -m "/Active Directory/All Domains" ¬
-u activedirectoryusername -p activedirectorypassword

The command above specifically tests Active Directory, but any valid domain node can be tested. Some important notes:

The -u flag uses the username from the node you are testing against, in the above example it is the Active Directory username

The -p flag uses the password from the username that is being tested. In the above example, it is the Active Directory account password

The node is the Search node as referenced in Directory Access. In the above example, all Active Directory domains are searched.

Local administrative privileges are not required to use this tool.

Currently, the password must be entered with the -p option, as omitting it does not work as documented in the manual page. The return value can provide very useful troubleshooting information. As an example, this output is returned with a bad password:

Call to dsGetRecordList returned count = 1 with Status : eDSNoErr : (0)
Username: username
Password: password
Error : eDSAuthFailed : (-14090)

This return status very clearly reflects the failed password authentication. Let's dive even deeper.

Kerberos

Kerberos is increasingly being used for authentication for many Directory Services. If the password is correct, but the shaking login window is still occurring, the next area to focus on, especially for Active Directory and Open Directory, is Kerberos troubleshooting. Fortunately, testing is painless using the command tool, kinit. Type in the following:

kinit username

On failure, a very understandable error message is displayed:

Kerberos Login Failed: Clock skew too big. 
Please check your time, time zone and daylight savings settings.

From this error message, it is clear that Kerberos is failing because the clock differential, referred to as skew, is too great. While many administrators set the clock to use a network timeserver, it is not uncommon for OS X to drift by more than five minutes; this is usually greater than the allowable clock skew. Adjust the date and time to be within five minutes of the Directory Services authentication source, and this problem is solved!

These problems are the 'low-hanging' fruit, and can usually quickly solve Directory Service problems. What about problems that are more difficult?

Bringing in the Big guns

What if none of these troubleshooting steps works? There are three ways to log information, one for Directory Services, one for Managed Client (MCX), and one for Portable Home Directories.

Directory Services

If none of the quick steps provides an answer, debugging Directory Services is often needed to troubleshoot particularly complex problems. There are two different levels of logging which can be invoked on demand USR1, and USR2. Both are turned on similarly, with the command:

killall -USR1 DirectoryService

USR1 will log information to

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

USR2 sends all information to the system.log file. One last thing, both levels can also be set by touching a file in the following directory as follows:

touch /Library/Preferences/DirectoryService/.DSLogDebugAtStart (USR1)
touch /Library/Preferences/DirectoryService/.DSLogAPIAtStart (USR2)

Reboot the client, and debugging will begin at boot time.

Managed Client Services (MCX)

Debugging information can be collected and set using a command line only option:

defaults write /Library/Preferences/com.apple.MCXDebug debugOutput 3

Writing this preference will log all information relating to client management to the system.log file. Three is the maximum value that can be set. Using this value, a tremendous amount of information can be seen in the client log, and may point to managed client problems.

Portable Home Directories

Portable home directories can also be logged with a hidden preference:

defaults write com.apple.MirrorAgent debugOutput 4

This preference will log all portable home directory information to ~/Library/Logs/MirrorAgent.log. Again, though not fun, this information can often point to the source of trouble when attempting to diagnose a sticky Portable Home Directory problem.

Conclusion

Diagnosing and troubleshooting can be one of the most complex issues in the integration of OS X clients into heterogeneous network infrastructures. Remember to always start from the simplest explanation, as it often is the source of the problem. It is easy to errantly assume a much larger problem, when, in fact, the problem may be quite simple. However, with the above techniques and tools, bending Directory Services to your will should be far simpler.


Philip Rinehart is co-chair of the steering committee leading the Mac OS X Enterprise Project (macenterprise.org) and is the Lead Mac Analyst at Yale University. He has been using Macintosh Computers since the days of the Macintosh SE, and Mac OS X since its Developer Preview Release. Before coming to Yale, he worked as a Unix system administrator for a dot-com company. He can be reached at: philip.rinehart@yale.edu.

The MacEnterprise project is a community of IT professionals sharing information and solutions to support Macs in an enterprise. We collaborate on the deployment, management, and integration of Mac OS X client and server computers into multi-platform computing environments

 
AAPL
$97.67
Apple Inc.
+0.64
MSFT
$44.50
Microsoft Corpora
+0.10
GOOG
$589.02
Google Inc.
-4.33

MacTech Search:
Community Search:

Software Updates via MacUpdate

TinkerTool 5.3 - Expanded preference set...
TinkerTool is an application that gives you access to additional preference settings Apple has built into Mac OS X. This allows to activate hidden features in the operating system and in some of the... Read more
Audio Hijack Pro 2.11.0 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Intermission 1.1.1 - Pause and rewind li...
Intermission allows you to pause and rewind live audio from any application on your Mac. Intermission will buffer up to 3 hours of audio, allowing users to skip through any assortment of audio... Read more
Autopano Giga 3.6 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more
Airfoil 4.8.7 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Microsoft Remote Desktop 8.0.8 - Connect...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
xACT 2.30 - Audio compression toolkit. (...
xACT stands for X Aaudio Compression Toolkit, an application that encodes and decodes FLAC, SHN, Monkey’s Audio, TTA, Wavpack, and Apple Lossless files. It also can encode these formats to MP3, AAC... Read more
Firefox 31.0 - Fast, safe Web browser. (...
Firefox for Mac offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals... Read more
Little Snitch 3.3.3 - Alerts you to outg...
Little Snitch gives you control over your private outgoing data. Track background activityAs soon as your computer connects to the Internet, applications often have permission to send any... Read more
Thunderbird 31.0 - Email client from Moz...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more

Latest Forum Discussions

See All

Reddme for iPhone - The Reddit Client (...
Reddme for iPhone - The Reddit Client 1.0 Device: iOS iPhone Category: News Price: $.99, Version: 1.0 (iTunes) Description: Reddme for iPhone is an iOS 7-optimized Reddit client that offers a refreshing new way to experience Reddit... | Read more »
Jacob Jones and the Bigfoot Mystery : Ep...
Jacob Jones and the Bigfoot Mystery : Episode 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Jacob Jones is back in Episode 2 of one of Apples 'Best of 2013' games and an App Store... | Read more »
New Trailer For Outcast Odyssey, A New K...
New Trailer For Outcast Odyssey, A New Kind of Card Battler Posted by Jennifer Allen on July 25th, 2014 [ permalink ] Out this Fall is a new kind of card battle game: Outcast Odyssey. | Read more »
Garfield: Survival of the Fattest Coming...
Garfield: Survival of the Fattest Coming to iOS this Fall Posted by Jennifer Allen on July 25th, 2014 [ permalink ] Who loves lasagna? Me. Also everyone’s favorite grumpy fat cat, Garfield. | Read more »
Happy Flock Review
Happy Flock Review By Andrew Fisher on July 25th, 2014 Our Rating: :: HERD IT ALL BEFOREUniversal App - Designed for iPhone and iPad Underneath the gloss of Happy Flock’s visuals is a game of very little substance. It’s cute, but... | Read more »
Square Register Updates Adds Offline Pay...
Square Register Updates Adds Offline Payments Posted by Ellis Spice on July 25th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Looking For Group – Hearthstone’s Curse...
For the first time since its release (which has thankfully been a much shorter window for iPad players than their PC counterparts), Blizzard’s wildly successful Hearthstone: Heroes of Warcraft CCG is sporting some brand new content: the single... | Read more »
Poptile Review
Poptile Review By Jennifer Allen on July 25th, 2014 Our Rating: :: SIMPLY FUNUniversal App - Designed for iPhone and iPad Simple yet a little bit glorious, Poptile is a satisfying entertaining puzzle game with oodles of the ‘one... | Read more »
Modern Combat 5: Blackout Review
Modern Combat 5: Blackout Review By Brittany Vincent on July 25th, 2014 Our Rating: :: LESS QQ, MORE PEW PEWUniversal App - Designed for iPhone and iPad The fifth entry into the blockbuster Modern Combat series is what mobile... | Read more »
Watch and Share Mobile Gameplay Videos W...
Watch and Share Mobile Gameplay Videos With Kamcord Posted by Jennifer Allen on July 25th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »

Price Scanner via MacPrices.net

Apple’s 2014 Back to School promotion: $100 g...
 Apple’s 2014 Back to School promotion includes a free $100 App Store Gift Card with the purchase of any new Mac (Mac mini excluded), or a $50 Gift Card with the purchase of an iPad or iPhone,... Read more
iMacs on sale for $150 off MSRP, $250 off for...
Best Buy has iMacs on sale for up to $160 off MSRP for a limited time. Choose free home shipping or free instant local store pickup (if available). Prices are valid for online orders only, in-store... Read more
Mac minis on sale for $100 off MSRP, starting...
Best Buy has Mac minis on sale for $100 off MSRP. Choose free shipping or free instant local store pickup. Prices are for online orders only, in-store prices may vary: 2.5GHz Mac mini: $499.99 2.3GHz... Read more
Global Tablet Market Grows 11% in Q2/14 Notwi...
Worldwide tablet sales grew 11.0 percent year over year in the second quarter of 2014, with shipments reaching 49.3 million units according to preliminary data from the International Data Corporation... Read more
New iPhone 6 Models to Have Staggered Release...
Digitimes’ Cage Chao and Steve Shen report that according to unnamed sources in Apple’s upstream iPhone supply chain, the new 5.5-inch iPhone will be released several months later than the new 4.7-... Read more
New iOS App Helps People Feel Good About thei...
Mobile shoppers looking for big savings at their favorite stores can turn to the Goodshop app, a new iOS app with the latest coupons and deals at more than 5,000 online stores. In addition to being a... Read more
Save on 5th generation refurbished iPod touch...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Many, but not all... Read more
What Should Apple’s Next MacBook Priority Be;...
Stabley Times’ Phil Moore says that after expanding its iMac lineup with a new low end model, Apple’s next Mac hardware decision will be how it wants to approach expanding its MacBook lineup as well... Read more
ArtRage For iPhone Painting App Free During C...
ArtRage for iPhone is currently being offered for free (regularly $1.99) during Comic-Con San Diego #SDCC, July 24-27, in celebration of the upcoming ArtRage 4.5 and other 64-bit versions of the... Read more
With The Apple/IBM Alliance, Is The iPad Now...
Almost since the iPad was rolled out in 2010, and especially after Apple made a 128 GB storage configuration available in 2012, there’s been debate over whether the iPad is a serious tool for... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.