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

 
AAPL
$94.72
Apple Inc.
+0.78
MSFT
$44.83
Microsoft Corpora
-0.01
GOOG
$594.74
Google Inc.
+5.27

MacTech Search:
Community Search:

Software Updates via MacUpdate

Airmail 1.4 - Powerful, minimal email cl...
Airmail is a powerful, minimal mail client.It was designed to retain the same experience with a single or multiple accounts and provide a quick, modern and easy-to-use user experience. Airmail... Read more
Macs Fan Control 1.1.12 - Monitor and co...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
A Better Finder Rename 9.37 - File, phot...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
MacBook Air EFI Firmware Update 2.9 - Fo...
MacBook Air EFI Firmware Update is recommended for MacBook Air (Mid 2011) models. This update addresses an issue where systems may take longer to wake from sleep than expected and fixes a rare issue... Read more
FileZilla 3.9.0.1 - Fast and reliable FT...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface.Version 3.9.0.1: MSW: Fix installation issue with locked DLLs... Read more
OS X Yosemite 10.10 DP4 - Developer Prev...
Note: This is a Developer Preview. You must be a registered Apple Mac Developer to download this update. OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels... Read more
FinderPop 2.5.6 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more
SpiderOak 5.1.7 - Secure cloud backup, s...
SpiderOak is a multi-platform secure online backup, storage, access, and sharing solution engineered for the consumer and small businesses. You must first sign up to use SpiderOak. Running natively... Read more
Espionage 3.6 - Simple, state of the art...
Espionage offers state-of-the-art encryption and plausible deniability for your confidential data. Sometimes, encrypting your data isn't enough to protect it. That's why Espionage 3 goes beyond data... Read more
calibre 1.45.0 - Complete e-library mana...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more

Latest Forum Discussions

See All

Celebrate Summer With a Cat in the Hat L...
Celebrate Summer With a Cat in the Hat Learning Library Sale Posted by Ellis Spice on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
MyTaskList Review
MyTaskList Review By Jennifer Allen on July 22nd, 2014 Our Rating: :: EFFECTIVE IF PLAINUniversal App - Designed for iPhone and iPad It’s not the most stylish of task management apps, but MyTaskList has all the features you could... | Read more »
FlyCraft Herbie: Crazy Machines Review
FlyCraft Herbie: Crazy Machines Review By Jennifer Allen on July 22nd, 2014 Our Rating: :: TRICKY FLYINGUniversal App - Designed for iPhone and iPad A tough game of careful thrusting and navigation, FlyCraft Herbie: Crazy Machines... | Read more »
MTN Review
MTN Review By Jessica Fisher on July 22nd, 2014 Our Rating: :: ADORABLE, SERENE, AND AMUSINGUniversal App - Designed for iPhone and iPad MTN is an adorable, talking pet mountain that is less game and more zen garden.   | Read more »
Fly High with Ninja UP! Now Available o...
Fly High with Ninja UP! Now Available on the App Store Posted by Jessica Fisher on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Bio Inc. Review
Bio Inc. Review By Nadia Oxford on July 22nd, 2014 Our Rating: :: SICKENING - IN A COMPELLING WAYUniversal App - Designed for iPhone and iPad Bio Inc is about orchestrating the medical destruction of a single person. If that doesn’... | Read more »
HELMUT Review
HELMUT Review By Andrew Fisher on July 21st, 2014 Our Rating: :: TRUNDLE SIMULATOR 2014Universal App - Designed for iPhone and iPad HELMUT is a fun, fleeting time-sink that offers a momentary distraction and nothing else.   | Read more »
Walkr Review
Walkr Review By Jennifer Allen on July 21st, 2014 Our Rating: :: ORIGINAL WALKINGiPhone App - Designed for the iPhone, compatible with the iPad Walking is a bit more exciting thanks to this planet building/discovering sim reliant... | Read more »
Zombie Commando Review
Zombie Commando Review By Jennifer Allen on July 21st, 2014 Our Rating: :: MINDLESS SLAUGHTERUniversal App - Designed for iPhone and iPad Briefly fun but ultimately forgettable, Zombie Commando will scratch an itch then be... | Read more »
Swords & Poker Adventures Review
Swords & Poker Adventures Review By Jennifer Allen on July 21st, 2014 Our Rating: :: SOULLESS POKER PLAYUniversal App - Designed for iPhone and iPad Swords & Poker Adventures is a mishmash of Poker and RPGing, but it lacks... | Read more »

Price Scanner via MacPrices.net

15-inch 2.0GHz MacBook Pro Retina on sale for...
B&H Photo has the 15″ 2.0GHz Retina MacBook Pro on sale for $1829 including free shipping plus NY sales tax only. Their price is $170 off MSRP. B&H will also include free copies of Parallels... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished Mac minis for up to $150 off the cost of new models. Apple’s one-year warranty is included with each mini, and shipping is free: - 2.5GHz Mac... Read more
Twelve South HiRise For MacBook – Height-Adju...
If you use your MacBook as a workhorse desktop substitute, as many of us do, a laptop stand combined with an external keyboard and pointing device are pretty much obligatory if you want to avoid... Read more
Why The Mac Was Not Included In The Apple/IBM...
TUAW’s Yoni Heisler cites Fredrick Paul of Network World whoi blogged last week that the Mac’s conspicuous absence from Apple and IBM’s landmark partnership agreement represents a huge squandered... Read more
Save $100 on 13-inch Retina MacBook Pros, plu...
Adorama has 13″ Retina MacBook Pros on sale for $100 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: - 13″ 2.4GHz/128GB MacBook Pro with Retina Display: $1199 - 13″ 2.... Read more
Blurr it 2.3 for iOS – Quickly Blurs Selected...
Hyderabad, India based TouchLabs has announced a new update of Blurr it 2.3, their photography app for iOS users. Blurr it allows you to blur part of the image to hide potentially sensitive or... Read more
MacBook Airs on sale for $100 off MSRP, start...
Best Buy has the new 2014 MacBook Airs on sale for up to $100 off MSRP on their online store. Choose free home shipping or free local store pickup (if available). Prices valid for online orders only... Read more
Amazon Announces Kindle Unlimited: Unlimited...
Amazon.com has introduced Kindle Unlimited — a new subscription service which allows customers to freely read as much as they want from over 600,000 Kindle books, and listen as much as they want to... Read more
New Linksys Wireless Range Extenders Boost Wi...
Linksys has announced its new lineup of Linksys Wi-Fi Range Extenders. Consumers often experience a weak wireless signal in some parts of their house or apartment caused by blocking elements such as... Read more
MacBook Airs available starting at $719
The Apple Store has Apple Certified Refurbished 2013 & 2012 MacBook Airs in stock today starting at $719. An Apple one-year warranty is included with each MacBook, and shipping is free: 2013... Read more

Jobs Board

*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
*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
Sr *Apple* Engineer - IT - Requisition #: -...
For more information about TIAA-CREF, visit our website . The Apple Engineer will provide engineering and third-level incident support for 300- 500 MacOS desktop/laptop Read more
*Apple* Systems Administrator - DISH (United...
…satellite service provider, and Dish is currently looking for an experienced Apple /Mac Systems Administrator. Apple systems administrator will be responsible for Read more
*Apple* Systems Administrator - DISH (United...
…satellite service provider, and Dish is currently looking for an experienced Apple /Mac Systems Administrator. Apple systems administrator will be responsible for Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.