TweetFollow Us on Twitter

Easing Into dscl

Volume Number: 22 (2006)
Issue Number: 10
Column Tag: Mac In The Shell

Easing Into dscl

Manipulating Directory Services via the Command Line

by Edward Marczak

Introduction

Once, centralized directories were a lofty corporate goal. Now, however, they increasingly play an important role - even with a single machine. dscl, the directory services command line, is a new, all in one way to access and manipulate directory services information. This month, we'll delve in worlds outside of the shell proper, but see how we can manipulate and interact with those other realms via command-line tools. This month will focus mainly on explaining directory service concepts.

Directory Services

To explain dscl, I also need to explain directory services. The term itself has no specific technical definition - kind of like "web services" or "web 2-point-oh." You know them when you see them, however, two web 2.0 sites can use different technology altogether. Directory services is a concept. The concept is that all directory information should have one interface for access. Different applications should be able to access this information for a variety of purposes. This information may be purely centralized, distributed or replicated. NeXT Computers developed a directory service called NetInfo. OS X inherited this directory service for its initial releases. NetInfo was good in its day, but Apple knew a system with more flexibility was needed. Enter OpenDirectory, Apple's current directory service. Like other directory services, such as Novell's eDir, Sun's yp/NIS or Microsoft's ActiveDirectory, OpenDirectory is a modern directory implementation with an LDAP interface. Unlike the other two mentioned, Apple's system is completely standards-based and easily manipulated.

LDAP

LDAP, the Lightweight Directory Access Protocol, surfaced in 1992. It's "lightweight" only in relation to X.500, the Directory Access Protocol. Somewhat like light beer - it needs to be compared to something else to be considered 'lightweight'. It is a protocol, and nothing more. It is not a database in and of itself. It may provide access to one, but doesn't have to. All it must do is accept requests and answer them - whether that answer comes from a database or not is of no concern. LDAP categorizes its information in a hierarchical tree structure. Following most digital trees, the root is visualized at the top, or on the side. Each branch is a container, and each leaf is a record. This is the Directory Information Tree, or, DIT. It's easiest if we visualize this. Figure 1 shows a basic LDAP hierarchy.



Figure 1: A sample (and very basic) Directory Information Tree.

LDAP uses some very specific terminology to designate container and leaf types. One similarity to a relational database is that they are both strongly-typed and use structured information. A distinguished name, or "DN", represents a unique identifier for a record. The top of the tree is called the base DN. This is typically defined as an "O" (Organization), or a series of DC records (Domain Components). "OU" stands for organizational unit. This is a container that allows you to organize other types.

OpenDirectory

Now that we're through the world's briefest introduction to LDAP, let's take a look at Apple's OpenDirectory. OpenDirectory is incredibly interesting because unlike ActiveDirectory and eDir, which are basically 'one thing', OpenDirectory is many things. On its own, it stores information in a BDB database via LDAP. Additionally, it ships with several plug-ins that allow it to access other directory systems such as ActiveDirectory. Finally, you can map OpenDirectory records into attributes provided by other systems that expose their directory through LDAP. What this all means is that when you use a directory tool on OS X to query information from the service, you may not be 100% sure where that data originated, be it native to OpenDirectory, or, pulled from another system over a network.

Some of the early impetus for directory services was simply to have a single place to perform lookups for basic employee information, such as phone numbers, e-mail addresses, etc. This is precisely one of the functions that OpenDirectory provides (easily in Tiger, you have to jump through some hoops in Panther).

A Case for the Shell

As is slightly typical, I feel I have to convince people that there are cases where command-line tools beat out a GUI. Of course, there are GUI tools, such as Workgroup Manager, that manipulate directory information. In many cases, these are the right tools. However, using the shell clearly trumps the GUI in these cases:

  • Automated importing/exporting many users in/out of a directory service.

  • Watching log files while you're in the GUI console. Server Admin's stateless HTTP log polling just doesn't cut it.

  • Troubleshooting while someone else works at the GUI console. I've used this to great effect. Sometimes, a machine is having an issue that make is a little off-kilter, but work can still be accomplished. Fine. Let the end-user get some work done. You can be getting work done on that machine, too, via ssh.

I don't think I've really found anyone, though, who, once shown how the shell can benefit them, thinks that it's a bad idea.

What's all this dscl then?

Onto the real topic of this article! While OS X Server started off with NetInfo as its "native" directory service, OS X still uses a NetInfo database to store all local account information. Despite this, OS X's directory services framework with its ability to use plug-ins opens an API to accessing any directory service set up through the Directory Access application (located in your Utilities folder). The long-standing niutil (NetInfo utility) program, which can only read and write into NetInfo, has been superseded by dscl, which can read and write through the directory services API - in other words, it can read and write into any directory service configured through Directory Access (authorization permitting).

Interestingly, dscl itself provides an interactive shell (with basic tab-completion, too!). Let's get our feet wet there. Open up a shell on the machine you'd like to be working on. This means that you may want to ssh somewhere if you need to. At the prompt, type dscl:



Figure 2: dscl with no arguments defaults to a dscl-shell

Although it's not shown in figure 2, you should note the last line of this output: "Entering interactive mode...", where you are dumped at a prompt. Typing ls lists the subdirectories or objects of the current path:



Fig 3: dscl directory listing

Since we all have a NetInfo directory, I'll start there. Using cd, you can change into the NetInfo directory (cd NetInfo). Doing so will change the prompt to show that you're now out of the root directory and into a subdirectory. Again, typing ls will help you get your bearings. If you've ever used NetInfo Manager, this should look familiar:



Figure 4: Displaying the local NetInfo root

From this point, change into the Users directory (cd Users), ls if you'd like to get a list of users stored in NetInfo, and then change into the user of your choice (cd username). If you're rushing ahead, and type ls, you may be surprised. You don't "list" properties, you read them. So type read, and press return. This will list all attributes for the account in question.



Figure 5: Reading a NetInfo user account.

You can repeat this exercise for the LDAPv3 branch of the tree, if you're fortunate enough to be connected to an LDAP/OD store. Type quit, and you'll leave dscl, and be returned to your Unix shell. Let's see how to drive dscl outside of its interactive shell.

To read the same user information directly, we can use dscl thusly:

dscl localhost -read /NetInfo/root/Users/marczak

If you just want to pick out certain keys you can supply them after the path:

$ dscl localhost -read /NetInfo/root/Users/marczak UniqueID RealName
UniqueID: 501
RealName: Edward R. Marczak

Keeping in mind that we're easing into dscl, I'll save some of the more in-depth information for future months. However, there's still plenty more to note.

We've been using using dscl to look at a NetInfo store on the local host. We can also specify an LDAP store. To get the same information from the LDAv3 node, you need to specify LDAP as the datasource:

dscl /LDAPv3/lycaeum.radiotope.com -read /Users/marczak

If you're running this from a server, as you often may if you have an automated script, you can also use the localhost designation of 127.0.0.1 in place of the node name.

Some operations require authentication, so you'll need to supply that information, too:

dscl -u [directory admin] -P [password] /LDAPv3/127.0.0.1 -delete /Users/marczak

For the security conscious among you, and that's hopefully everyone, instead of using the "-P" switch and specifying the password on the command-line, you can instead use "-p" to have dscl prompt you for the password. Naturally, certain situations call for certain behavior. You can't automate a nightly routine and have the operation halt, waiting for a password. Those scripts need to be protected appropriately.

One underappreciated mode of dscl is "authonly". Says what it does, does what it says: tests authentication of a username/password combination. Watch it in action:

lycaeum:~ root# dscl /LDAPv3/127.0.0.1 authonly marczak asdf
Authentication for node /LDAPv3/127.0.0.1 failed. (-14090, eDSAuthFailed)
lycaeum:~ root# dscl /LDAPv3/127.0.0.1 authonly marczak myrealpass
lycaeum:~ root#

In grand Unix fashion, no news is good news. On the first line, I supply a known-bad password, and get back the appropriate error, authorization failed. On the next line I give the right credentials, and get back....nothing. (Technically, you get a "0" error code, anyone remember where that was covered? echo $?).

Combine dscl with traditional bash scripting and you can automate routines, and do things that can't be done in Workgroup Manager at all! How about a report of all users, listing their full name, short name and home directory?

#!/bin/bash
for i in `dscl /LDAPv3/127.0.0.1 -list /Users` ; do
        dscl /LDAPv3/127.0.0.1 -read /Users/${i} RealName uid homeDirectory | awk 'BEGIN {FS=":"} 
           {print $2}'
        echo
done

Making the file executable and running it produces (partially):

# ./userrep.sh 
 Directory Administrator
 diradmin
 /Users/diradmin
 Dorothy Marczak
 dorothy
 /Network/Servers/lycaeum.radiotope.com/Users/dorothy
 Edward R. Marczak
 marczak /Network/Servers/lycaeum.radiotope.com/Volumes/Data2/Users/marczak

Conclusion

dscl is a powerful, and handy, tool as it will report on and manipulate the information in any accessible Directory Service store. As with many command line utilities, its real power comes when automated as part of a larger script. Data are only useful if they can be used, accessed and reported upon. Sometimes, you need to write your own tools to gather the precise information that you're looking for.

Media of the month: Guy Kawasaki's Art of the Start. Despite being a two year old title, it's still incredibly relevant. If you're sparked by new ideas and want to see them become reality, this is some fantastic reading. Plus, there's the gratuitous Apple tie-in.

Also, it shocks me that, having just returned from WWDC, MacWorld is nigh. Hope everyone is making their plans. For those attending, I'll see you in San Francisco! Of course, I'll see you in print next month.

References:


Ed Marczak owns and operates Radiotope, a technology consulting practice focusing on network integr4tion, overc0ming?technolgy hurdles by 3:44.904780??))http://www.radiotope.com::bactericholiabactericidalbactericidebacteri...NO CARRIER

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

TinkerTool 5.4 - 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
Tinderbox 6.3.1 - Store and organize you...
Tinderbox is a personal content management assistant. It stores your notes, ideas, and plans. It can help you organize and understand them. And Tinderbox helps you share ideas through Web journals... Read more
Parallels Desktop 10.2.2 - Run Windows a...
Parallels Desktop is simply the world's bestselling, top-rated, and most trusted solution for running Windows applications on your Mac. With Parallels Desktop for Mac, you can seamlessly run both... Read more
Adobe Premiere Pro CC 2015 9.0.1 - Digit...
Premiere Pro CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Premiere Pro customer). Premiere Pro CS6 is still available for... Read more
Adobe After Effects CC 2015 13.5.1 - Cre...
After Effects CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). After Effects CS6 is still available... Read more
Adobe Creative Cloud 2.2.0.129 - Access...
Adobe Creative Cloud costs $49.99/month (or less if you're a previous Creative Suite customer). Creative Suite 6 is still available for purchase (without a monthly plan) if you prefer. Introducing... Read more
Tower 2.2.3 - Version control with Git m...
Tower is a powerful Git client for OS X that makes using Git easy and more efficient. Users benefit from its elegant and comprehensive interface and a feature set that lets them enjoy the full power... Read more
Apple Java 2015-001 - For OS X 10.7, 10....
Apple Java for OS X 2015-001 installs the legacy Java 6 runtime for OS X 10.11 El Capitan, OS X 10.10 Yosemite, OS X 10.9 Mavericks, OS X 10.8 Mountain Lion, and OS X 10.7 Lion. This package is... Read more
Adobe Muse CC 2015 2015.0.1 - Design and...
Muse CC 2015 is available as part of Adobe Creative Cloud for as little as $14.99/month (or $9.99/month if you're a previous Muse customer). Muse CS6 is still available for purchase (without a... Read more
Adobe Illustrator CC 2015 19.1.0 - Profe...
Illustrator CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Illustrator customer). Illustrator CS6 is still available for... Read more

This Week at 148Apps: July 20-24, 2015
July is Heating Up With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice, standing out... | Read more »
Red Game Without A Great Name (Games)
Red Game Without A Great Name 1.0.3 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.3 (iTunes) Description: The mechanical bird is flying through an unfriendly, Steampunk world. Help it avoid obstacles and deadly... | Read more »
Warhammer: Arcane Magic (Games)
Warhammer: Arcane Magic 1.0.2 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.2 (iTunes) Description: Engage in epic battles and tactical gameplay that challenge both novice and veteran in Warhammer: Arcane Magic, a... | Read more »
Mazes of Karradash (Games)
Mazes of Karradash 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: The city of Karradash is under attack: the monsters of the Shadow Realms are emerging from the depths.No adventurer is... | Read more »
Battle Golf is the Newest Game from the...
Wrassling was a pretty weird - and equally great - little wressling game. Now the developers, Folmer Kelly and Colin Lane, have turned their attention to a different sport: golfing. This is gonna be weird. [Read more] | Read more »
Qbert Rebooted has the App Store Going...
The weird little orange... whatever... is back, mostly thanks to that movie which shall remain nameless (you know the one). But anyway it's been "rebooted" and now you can play the fancy-looking Qbert Rebooted on iOS devices. [Read more] | Read more »
Giant Monsters Run Amok in The Sandbox...
So The Sandbox has just hit version number 1.99987 (seriously), and it's added a lot more stuff. Just like every other update, really. [Read more] | Read more »
Fish Pond Park (Games)
Fish Pond Park 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: Nurture an idyllic slice of tourist's heaven into the top nature spot of the nation, furnishing it with a variety of... | Read more »
Look after Baby Buddy on your Apple Watc...
Parigami Gold is the new premium version of the match three puzzler that includes Apple Watch support and all new content. You won't simply be sliding tiles around on your wrist, the Apple Watch companion app is an all new mini-game in itself. You'... | Read more »
Swallow all of your opponents as the big...
Eat all of the opposition and become the largest ball in Battle of Balls now available in the App Store and Google Play. Battle of Balls pits you against other opponents in real time and challenges you to eat more balls and grow larger than all of... | Read more »

Price Scanner via MacPrices.net

Sale! 13″ 1.6GHz/256GB MacBook Air for $1099,...
B&H Photo has the 13″ 1.6GHz/256GB MacBook Air on sale for $1099 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model. Read more
iPad mini 4 To Be Upgraded To iPad Air 2 Spec...
There’s a certain inevitability about making Apple product predictions this time of year. Come September, we can pretty reliably count on the release of refreshed iPhones, along with the iOS 9... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz... Read more
13-inch 2.5GHz MacBook Pro on sale for $899,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $899.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $200 off MSRP. Price is... Read more
21-inch 2.9GHz iMac on sale for $1299, save $...
Best Buy has the 21″ 2.9GHz iMac on sale today for $1299.99 on their online store. Choose free shipping or free local store pickup (if available). Their price is $200 off MSRP, and it’s the lowest... Read more
Free Image Sizer 1.3 for iOS Offers Photo Edi...
Xi’An, China based G-Power has announced the release of Image Sizer 1.3 for the iPhone, iPad, and iPod touch, an important update to their free photo editing app. Image Sizer’s collection of easy to... Read more
Sale! 13″ 1.6GHz/128GB MacBook Air for $899,...
B&H Photo has the 13″ 1.6GHz/128GB MacBook Air on sale for $899 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model. Read more
13-inch Retina MacBook Pros on sale for $100...
Best Buy has 13-inch Retina MacBook Pros on sale for $100 off MSRP on their online store. Choose free shipping or free local store pickup (if available). Prices are for online orders only, in-store... Read more
Will BMW’s i3 Electric Vehicle Be The Automo...
The German-language business journal Manager Magazin’s Michael Freitag reports that Apple and the German performance/luxury automaker Bayerishe Motoren Werke (BMW) are back at far-reaching... Read more
Sale! $250 off 15-inch Retina MacBook Pro, $2...
B&H Photo has lowered their price for the 15″ 2.2GHz Retina MacBook Pro to $1749, or $250 off MSRP. Shipping is free, and B&H charges NY sales tax only. They have the 27″ 3.3GHz 5K iMac on... Read more

Jobs Board

*Apple* Customer Experience (ACE) Leader - A...
…management to deliver on business objectives Training partner store staff on Apple products, services, and merchandising guidelines Coaching partner store staff on Read more
Project Manager - *Apple* Pay Security - Ap...
**Job Summary** The Apple Pay Security team is seeking a highly organized, results-driven Project Manager to drive the development of Apple Pay Security. If you are Read more
*Apple* TV Product Design Internship (Spring...
…the mechanical design effort associated with creating world-class products with the Apple TV PD Group. Responsibilities will include working closely with manufacturing, Read more
*Apple* Watch SW Application Project Manager...
**Job Summary** The Apple Watch software team is looking for an Application Engineering Project Manager to work on new projects for Apple . The successful candidate Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.