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

SpamSieve 2.9.38 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
TeamViewer 15.0.8397 - Establish remote...
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 non... Read more
SteerMouse 5.4.3 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. SteerMouse can assign various functions to buttons that Apple's software does not allow, including double-clicks, modifier clicks,... Read more
Toast Titanium 18.2.1 - The ultimate med...
Roxio Toast Titanium, the leading DVD burner for Mac, makes burning even better, adding Roxio Secure Burn to protect your files on disc and USB in Mac- or Windows-compatible formats. Get more style... Read more
HoudahSpot 5.0.11 - Advanced file-search...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the... Read more
ClipGrab 3.8.6 - Download videos from Yo...
ClipGrab is a free downloader and converter for YouTube, Vimeo, Facebook and many other online video sites. It converts downloaded videos to MPEG4, MP3 or other formats in just one easy step Version... Read more
ExpanDrive 7.4.0 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe Dreamweaver CC 2020 20.0 - Build w...
Dreamweaver CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2020 allows you to... Read more
Eye Candy 7.2.3.85 - 30 professional Pho...
Eye Candy renders realistic effects that are difficult or impossible to achieve in Photoshop alone, such as Fire, Chrome, and the new Lightning. Effects like Animal Fur, Smoke, and Reptile Skin are... Read more
Sparkle Pro 2.8.5 - Visual website creat...
Sparkle Pro will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more

Latest Forum Discussions

See All

Pre-register for Hello Kitty AR: Kawaii...
Hello Kitty — the cute cat that launched a multi-billion-pound franchise — has been brought to life… sort of. Sanrio has teamed up with the Bublar Group to create a new mobile game that uses AR tech to turn the real world into Hello Kitty’s... | Read more »
Gorgeous and tranquil puzzler Spring Fal...
One-man indie studio SPARSE//GameDev has now launched its tranquil puzzler, Spring Falls. It's described as "a peaceful puzzle game about water, erosion, and watching things grow". [Read more] | Read more »
Black Desert Mobile gets an official rel...
Pearl Abyss has just announced that its highly-anticipated MMO, Black Desert Mobile, will launch globally for iOS and Android on December 11th. [Read more] | Read more »
Another Eden receives new a episode, cha...
Another Eden, WFS' popular RPG, has received another update that brings new story content to the game alongside a few new heroes to discover. [Read more] | Read more »
Overdox guide - Tips and tricks for begi...
Overdox is a clever battle royale that changes things up by adding MOBA mechanics and melee combat to the mix. This new hybrid game can be quite a bit to take in at first, so we’ve put together a list of tips to help you get a leg up on the... | Read more »
Roterra Extreme - Great Escape is a pers...
Roterra Extreme – Great Escape has been described by developers Dig-It Games as a mini-sequel to their acclaimed title Roterra: Flip the Fairytale. It continues that game's tradition of messing with which way is up, tasking you with solving... | Read more »
Hearthstone: Battlegrounds open beta lau...
Remember earlier this year when auto battlers were the latest hotness? We had Auto Chess, DOTA Underlords, Chess Rush, and more all gunning for our attention. They all had their own reasons to play, but, at least from where I'm standing, most... | Read more »
The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »
Arcade classic R-Type Dimensions EX blas...
If you're a long time fan of shmups and have been looking for something to play lately, Tozai Games may have just released an ideal game for you on iOS. R-Type Dimensions EX brings the first R-Type and its sequel to iOS devices. [Read more] | Read more »

Price Scanner via MacPrices.net

13″ 2.4GHz MacBook Pros available for up to $...
Apple has a full line of Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros available starting at $1529 and up to $300 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
New at T-Mobile: Switch to T-Mobile, and get...
T-Mobile is offering a free 64GB iPhone 8 for new customers who switch to T-Mobile and open a new line of service. Eligible trade-in required, and discount applied over a 24 month period. The fine... Read more
Xfinity Mobile’s Black Friday Apple savings:...
Take $250 off the purchase of any iPhone at Xfinity Mobile with a new line activation, and transfer of phone number to Xfinity Mobile, through December 8, 2019. This includes Apple’s new iPhone 11... Read more
2019 13″ 1.4GHz MacBook Pros available starti...
Apple has a full line of Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros available starting at $1099 and up to $230 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
Save up to $350 on a 21″ or 27″ iMac with the...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
Early Holiday 2019 Sale: B&H again offers...
B&H Photo has 10.2″ iPads on sale again for $30 off Apple’s MSRP, starting at $299, as part of their early Holiday 2019 sale. Overnight shipping is free to many addresses in the US: – 10.2″ 32GB... Read more
Apple iMacs on sale today at B&H Photo fo...
B&H Photo has new 2019 21″ and 27″ 5K iMacs on stock today and on sale for up to $150 off Apple’s MSRP. Overnight shipping is free to many locations in the US. These are the same iMacs sold by... Read more
2018 4 and 6-Core Mac minis on sale today for...
Apple resellers are offering new 2018 4-Core and 6-Core Mac minis for $80-$100 off MSRP for a limited time. B&H Photo has the new 2018 4-Core and 6-Core Mac minis on sale for up to $100 off Apple... Read more
Early Holiday 2019 sale at B&H Photo: 12....
B&H Photo has new 12.9″ iPad Pros on sale for up to $120 off Apple’s MSRP as part of their early Holiday 2019 sale. Overnight shipping is free to many addresses in the US: – 12.9″ 64GB WiFi iPad... Read more
8-Core iMac Pro on sale today for $4499 at B...
B&H Photo has the base 8-Core 3.2GHz 32GB/1TB iMac Pro on sale today for $4499 — $500 off Apple’s MSRP. Shipping is free. Their price is the lowest available for a new iMac Pro from any Apple... Read more

Jobs Board

*Apple* Health Benefit Specialist - Call Cen...
Description ** Apple Health Benefit Specialist - Call Center (MAS 3/MACSC)** **Olympia, WA Multiple Positions** *The ideal candidate for this position will have Read more
Hair Stylist - *Apple* Blossom Mall - JCPen...
Hair Stylist - Apple Blossom Mall Location:Winchester, VA, United States- Apple Blossom Mall 1850 Apple Blossom Dr Job ID:1065040Salon Professionals Job Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**747088BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000297-Reston-Store **Job Description:** At Best Read more
Nurse Practitioner - Field Based (San Bernard...
Nurse Practitioner - Field Based (San Bernardino, CA, Apple Valley, Hesperia) **Location:** **United States** **Requisition #:** PS30312 **Post Date:** Nov 11, 2019 Read more
Best Buy *Apple* Computing Master - Best Bu...
**747061BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 000647-Kildeer-Store **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.