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

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.

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, 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.

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.

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).

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.

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:

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:

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:

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.

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

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.

Netscape Directory Project: <http://www.mozilla.org/directory/>

dscl man page

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