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

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

NetNewsWire 6.1.1 - RSS and Atom news re...
NetNewsWire is the best way to keep up with the sites and authors you read most regularly. Let NetNewsWire pull down the latest articles, and read them in a distraction-free and Mac-like way. Native... Read more
ScreenFlow 10.0.9 - Create screen record...
ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire monitor while also capturing your video camera, microphone and your... Read more
OnyX 4.3.8 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
MacFamilyTree 10.2 - Create and explore...
MacFamilyTree gives genealogy a facelift: modern, interactive, convenient and fast. Explore your family tree and your family history in a way generations of chroniclers before you would have loved.... Read more
Viber 19.7.0 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
HoudahSpot 6.3 - Advanced file-search to...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot is a productivity tool. It is the hub where all the... Read more
Transmit 5.9.2 - Excellent FTP/SFTP clie...
Transmit is an excellent FTP (file transfer protocol), SFTP, S3 (Amazon.com file hosting) and iDisk/WebDAV client that allows you to upload, download, and delete files over the internet. With the... Read more
TeamViewer 15.40.8 - Establish remote co...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
ffWorks 3.3.5 - A Comprehensive Video Co...
ffWorks, focused on simplicity, brings a fresh approach to the use of FFmpeg, allowing you to create ultra-high-quality movies without the need to write a single line of code on the command-line.... Read more
Arq 7.19.11 - Online backup to Google Dr...
Arq is super-easy online backup for Mac and Windows computers. Back up to your own cloud account (Amazon Cloud Drive, Google Drive, Dropbox, OneDrive, Google Cloud Storage, any S3-compatible server... Read more

Latest Forum Discussions

See All

Bleach: Brave Souls has released a colla...
Starting March 31st, Bleach: Brave Souls will be holding their Spirits Are Forever With You collaboration campaign, or SAFWY for short. You will be able to get your hands on some exclusive SAFWY versions of some iconic Bleach characters, including... | Read more »
Out Now: ‘Brotato’, ‘Slime Labs 3’, ‘Ter...
Each and every day new mobile games are hitting the App Store, and so each week we put together a big old list of all the best new releases of the past seven days. Back in the day the App Store would showcase the same games for a week, and then... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for March 29th, 2023. In today’s article, we briefly go over that fancy Tears of the Kingdom preview from yesterday then head right into a review of the action bop Kraino Origins. After... | Read more »
‘Terra Nil’ Review – A Netflix Games Ess...
When Terra Nil (Free) from Devolver Digital and Free Lives was revealed, the striking aesthetic and premise had my attention. Devolver is known to publish interesting games, even if I don’t enjoy every release from them, but Terra Nil looked like... | Read more »
A Look Back at the ‘Final Fantasy’ Pixel...
Ooh, he said the thing. No, my dearest of long-time readers, the RPG Reload isn’t making a regular comeback. But with Square Enix’s Final Fantasy Pixel Remaster series about to make the hop to consoles sometime in the next month or two, I thought it... | Read more »
Smilehate and VA Games announce upcoming...
It is exciting times for mobile RPG fans, as Smilegate and VA Games have unveiled the brand page and first look at its upcoming game Outerplane. With a tentative global launch at the end of May, we can get our first look at the characters and... | Read more »
‘Skullgirls Mobile’ Major Update 5.3 Out...
Following the December version 5.2 update, developer Hidden Variable pushed out a major update for Skullgirls Mobile (Free) a few hours ago. Skullgirls Mobile 5.3 brings in Black Dahlia’s full release, XP boosts, fighter tuning, free gifts, and a... | Read more »
Classic Sports Game ‘Baseball Stars Prof...
Following last week’s ACA NeoGeo mobile release of Stakes Winner, Hamster and SNK have released the classic sports game Baseball Stars Professional on iOS and Android worldwide. Baseball Stars Professional debuted in 1990, and the classic sports... | Read more »
“Age of Falling Towers” Major Update Arr...
Well we’re about 9 months out from the launch of Diablo Immortal in June of last year, and at the time of its launch I was pretty heavily into the game for the first month or so. Then I just sort of churned out and haven’t really been keeping tabs... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for March 28th, 2023. In today’s article, we’ve got full reviews of both MLB The Show 23 and Atelier Ryza 3: Alchemist of the End and the Secret Key. After that, we’ve got a handful of... | Read more »

Price Scanner via MacPrices.net

New low price: Apple AirPods Pro for $194, sa...
Verizon has Apple AirPods Pro on sale for $194.99 on their online store for a limited time. Their price is $55 (22%) off Apple’s MSRP, and it’s the lowest price currently available for AirPods Pro.... Read more
Open-box 13-inch M2 MacBook Pros available fo...
QuickShip Electronics has open-box return 13″ M2 MacBook Pros in stock and on sale for $300-$350 off MSRP on their eBay store right now, each with free express delivery. According to QuickShip, “The... Read more
Take $100 off the price of an iPad with Apple...
Apple will take $100 off 12″ M2 iPad Pros, $50-$100 off 11″ M2 iPad Pros, $50 off iPad Airs, $50 off 8.3″ iPad minis, & $20-$40 off 10″ iPads for all teachers, students, and staff of any... Read more
Deal Alert! Apple Studio Display with Nano Gl...
Amazon has the Apple Studio Display with Nano-Texture Glass (Tilt-Adjustable Stand) on sale for $400 (21%) off MSRP for a limited time. Shipping is free: – Studio Display (Nano glass): $1499 $400 off... Read more
Clearance 2020 13″ M1 MacBook Pros available...
Apple has clearance, previous-generation, 13″ M1 MacBook Pros available in their Certified Refurbished section for $1059. These are the cheapest 13″ MacBook Pros for sale today at Apple, and all... Read more
Amazon continues to offer $799 13-inch M1 Mac...
Amazon has Apple 13″ M1 MacBook Airs on sale for $200 off MSRP, only $799.99. Their prices are the lowest available for new MacBooks today among the retailers we track. Stock may come and go, so... Read more
Find the lowest prices on Apple iPads using o...
Our Apple award-winning iPad Price Trackers are the best place to find the latest information on iPad sales and deals. Current sales, as of this post, range up to $200 off MSRP depending on the model... Read more
Apple’s Reality Pro VR headset one step close...
Mark Gurman, in this weeks’s Power On newsletter, stated that last week, Apple held an important assembly of its highest ranking executives at the Steve Jobs Theater in Cupertino. The gathering,... Read more
Apple 16-inch M2 Pro MacBook Pros on sale for...
The first major sales on Apple’s 16-inch M2 Pro MacBook Pros arrived this month. B&H Photo has Space Gray 16″ M2 Pro MacBook Pros in stock and on sale today for $200 off Apple’s MSRP, starting at... Read more
Apple 14-inch M2 Pro MacBook Pros on sale for...
B&H Photo has Apple 14″ M2 Pro MacBook Pros in stock today and on sale for $100-$200 off MSRP, each including free 1-2 day delivery to most US addresses. Their prices are the among the lowest... Read more

Jobs Board

MacOS X / *Apple* Support Engineer - Royal...
MacOS X / Apple Desktop Support Engineer, on-site in New York, NY The Desktop Support Group is looking for an endpoint engineer with a focus on supporting MacOS and Read more
Wireless Device Portfolio Manager - *Apple*...
…in our Retail Wireless journey. The successful Device Portfolio Manager - Apple will work cross-functionally to develop, oversee and execute a device roadmap Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.