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

Google Chrome 96.0.4664.55 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Bartender 4.1.21 - Organize your menu-ba...
Bartender lets you organize your menu-bar apps by hiding them, rearranging them, or moving them to Bartender's Bar. You can display the full menu bar, set options to have menu-bar items show in the... Read more
CleanMyMac X 4.9.3 - Delete files that w...
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
ffWorks 2.6.4 - Convert multimedia files...
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
Thunderbird 91.3.2 - Email client from M...
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
Adobe Photoshop 23.0.2 - Professional im...
You can download Photoshop for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have purchased an earlier software version). Adobe Photoshop is a recognized classic of... Read more
VirtualBox 6.1.30 - x86 virtualization s...
VirtualBox is a family of powerful x86 virtualization products for enterprise as well as home use. Not only is VirtualBox an extremely feature rich, high performance product for enterprise customers... Read more
Merlin Project 8.0.2 - Project managemen...
Merlin Project is the leading professional project management software for OS X. If you plan complex projects on your Mac, you won’t get far with a simple list of tasks. Good planning raises... Read more
XMind 11.1.2 - Mind mapping and project...
XMind is a mind-mapping tool based off of the same open-source project as XMind Pro. It supports the same map structures and 100% compatible with XMind. It has new themes, some with more muted tones... Read more
WiFiSpoof 3.7 - Change your WiFi MAC add...
WiFiSpoof quickly and easily allows you to change your WiFi MAC address via hot-key or the system menu bar. Version 3.7: Fixed a potential issue with displaying current network on macOS Monterey... Read more

Latest Forum Discussions

See All

5 futuristic games like PUBG New State
The biggest flex of PUBG New State is its futuristic background. The new battle royale game is set in 2051. It has a new map, Troi, and also has a future version of Erangel. The weapon customization, drones, and other new features make it a new-... | Read more »
TouchArcade Game of the Week: ‘Jump Jerb...
I love games that don’t mess around. No frills or fluff, just “Here’s what I am and here’s what you get." That’s the vibe I get from Jump Jerboa from self-described “mostly solo" developer Chinykian. This is a minimalist one-button platformer that... | Read more »
SwitchArcade Round-Up: ‘Date Night Bowli...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for November 26th, 2021. In today’s article, we look at the rest of the releases for the week. There are a couple of good games in today’s batch, and we’ve got summaries of the whole lot... | Read more »
Musical 2D Platformer ‘One Hand Clapping...
Bad Dream Games’ One Hand Clapping was originally a project demo at the University of Southern California and it has evolved into a full game that blends music with 2D platforming. It was previously revealed for PC and consoles and it is also now... | Read more »
Best Black Friday 2021 iPhone and iPad G...
Just like last year, many retailers have been discounting and price matching games and hardware well before Black Friday. The App Store has some great deals on iOS games that are available right now and more that will likely start showing up in the... | Read more »
SwitchArcade Round-Up: ‘DoDonPachi Resur...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for November 25th, 2021. Today is Thanksgiving in America, so many of you will be off work or school. In Japan, it is just Thursday, so I must work as usual. In spite of the holiday,... | Read more »
The Best Black Friday Nintendo Switch eS...
Hello, friends. It’s that time of the year again. The most magical of times, when over a thousand Nintendo Switch games get discounts on the eShop that make them very hard to resist. Unless you’re enormously wealthy, you’re going to have to make... | Read more »
Lineage2M: 4 Reasons to Be Excited About...
With staggeringly beautiful visuals and fast-paced gameplay, Lineage2M is high on everyone’s list of most anticipated mobile games before the end of the year. The upcoming Lineage title is set to land for PC and mobile devices on December 2nd so,... | Read more »
New ‘My Time at Portia’ Update Adds Supp...
Last week, a new content update for My Time at Portia ($7.99) from Pathea Games was announced. The game released on mobile a few months ago thanks to Pixmain and it is a pretty great conversion. | Read more »
Out Now: ‘Super String’, ‘Ghostbusters A...
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 »

Price Scanner via MacPrices.net

Black Friday Sale: Get an 11″ M1 2TB WiFi iPa...
Amazon has the 11″ M1 2TB WiFi iPad Pro, in Space Gray, on sale for $1648.99 shipped as part of their Black Friday/Cyber Monday 2021 sale. Amazon’s price is $250 off MSRP, and it’s the lowest price... Read more
The best Black Friday/Cyber Monday 2021 deal...
Apple has a full line of 2020 13″ M1 MacBook Airs available and in stock today, Certified Refurbished, starting at only $849 and up to $190 off original MSRP. These are the best deals on 13″ MacBook... Read more
Expercom offers $40 discount on AppleCare+ wi...
Take $40 off 3-year AppleCare+ Plans ($209, regularly $249) when purchased alongside new 13″ M1 MacBook Pros at Apple reseller Expercom. All models are in stock today: – 2020 13″ MacBook Pro M1 CPU/... Read more
Black Friday Clearance Deal: 21″ iMacs for on...
Amazon has recently-discontinued 2020 21″ 2.3GHz Intel-based dual-core i5 iMacs (8GB RAM/256GB SSD) on clearance sale for only $879 shipped. Their price is $220 off original MSRP, and it’s the lowest... Read more
These wireless carriers will give you a free...
Apple’s wireless partners are offering several deals on iPhone 13 orders right now. If you’re an existing customer or willing to switch carriers, you can get a free iPhone 13 this Black Friday/Cyber... Read more
This 10.2″ Apple iPad is on sale for $319 for...
Apple’s new 9th generation 10.2″ is in short supply this Black Friday 2021 weekend, largely due to global supply constraints. Of all the Apple resellers we track, only one is reporting stock of the... Read more
The best Black Friday 2021 Apple Pencil sales...
Apple resellers are offing Apple Pencil models for 20%-23% off MSRP as part of their Black Friday 2021 sales. These are the cheapest Apple Pencils for sale this weekend: 1 – Amazon has Apple Pencils... Read more
Black Friday 2021: Take $20 off Apple Watch S...
Amazon has Apple Watch Series 7 models on sale today for $20 off MSRP including free shipping. Their prices are the lowest currently available for Series 7 Watches for Black Friday 2021: – 41mm Apple... Read more
Black Friday Only! Get last year’s 4-core Mac...
B&H Photo has last year’s Intel-based 3.6GHz 4-core Mac mini on clearance sale for only $429 for Black Friday 2021 only. Their price is $370 off original MSRP for this mini, and it’s the lowest... Read more
Black Friday 2021: Get an M1 Mac mini for as...
Looking for the cheapest Mac with an Apple M1 processor this Black Friday 2021? Apple’s Mac mini starts at $699, and resellers are offering models on sale this weekend for as low as $589 and up to $... Read more

Jobs Board

*Apple* Mac IT Support Specialist - Randstad...
Apple Mac IT Support Specialist **job details:** + location:Worcester, MA + salary:$40 - $45 per hour + date posted:Thursday, November 11, 2021 + job type:Contract + Read more
Senior Software Developer - *Apple* (iOS/tv...
**SUMMARY** Hulu's Apple team is seeking an experienced Senior Software Engineer with a passion for mobile applications to join our team in Seattle. Our highly Read more
*Apple* Management Engineer | Information Te...
Job postings Apple Management Engineer | Information Technologist II Share this: + + + + + | More (http://www.addthis.com/bookmark.php?v=250&username=pageup) Back to Read more
Department Manager- Tech Store (Full-time, Ge...
…+ Provide on-site support for in-shop repair on a variety of Apple computers and peripherals using advanced computer and electronic repair techniques and Read more
*Apple* / Macintosh / Jamf / Adm Systems Adm...
…Administration **Duties and Responsibilities** + Configure and maintain the client's Apple Device Management (ADM) solution. The current solution is JAMF supporting Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.