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

OS X Yosemite 10.10.2 - Apple's lat...
OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels entirely fresh, yet inherently familiar. The apps you use every day, enhanced with new features. And a... Read more
Apple iOS 8.1.3 - The latest version of...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more
SpamSieve 2.9.19 - 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
RapidWeaver 6.0.5 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
Duet 1.2.2 - Use your iPad as an externa...
Duet is the first app that allows you to use your iDevice as an extra display for your Mac using the Lightning or 30-pin cable. Note: This app requires a $14.99 iOS companion app. Version 1.2.2:... Read more
Alfred 2.6 - Quick launcher for apps and...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more
1Password 5.1 - Powerful password manage...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
GarageSale 6.9.2 - Create outstanding eB...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
calibre 2.17 - Complete e-library manage...
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 librarian... Read more
OmniGraffle Pro 6.1.2 - Create diagrams,...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more

New WOTA: U-Boat Compass ‘Wets’ Your App...
New WOTA: U-Boat Compass ‘Wets’ Your Appetite for WOTA: Wolves of the Atlantic. Posted by Jessica Fisher on January 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Warship Solitaire Review
Warship Solitaire Review By Nadia Oxford on January 27th, 2015 Our Rating: :: A WAR OF NUMBERSUniversal App - Designed for iPhone and iPad Warship Solitaire might lack frills and looks, but it offers some thought provoking... | Read more »
Keep Track of Your Hectic Work Schedule...
Keep Track of Your Hectic Work Schedule With Shifts Posted by Jessica Fisher on January 27th, 2015 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
All Star Quarterback Review
All Star Quarterback Review By Campbell Bird on January 27th, 2015 Our Rating: :: PLAY YOUR PARTUniversal App - Designed for iPhone and iPad Train your way to the Super Bowl in this free-to-play sports management game.   | Read more »
Sentinel 4: Dark Star Adds New Campaign...
Sentinel 4: Dark Star Adds New Campaign and More Posted by Ellis Spice on January 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Wheel & Deal Review
Wheel & Deal Review By Tre Lawrence on January 27th, 2015 Our Rating: :: SIMPLE FUNUniversal App - Designed for iPhone and iPad A simple arcade shooter that has a retro feel.   | Read more »
Join the NAVY in a Big New Update for WW...
Join the NAVY in a Big New Update for WW2: Sandbox. Strategy & Tactics Posted by Jessica Fisher on January 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Earthworm Alchemy Review
Earthworm Alchemy Review By Campbell Bird on January 27th, 2015 Our Rating: :: FEED THE WORMUniversal App - Designed for iPhone and iPad Feed this funny looking worm and dodge bombs in this charming, free-to-play arcade game.   | Read more »
Graphic Novel App netwars – The Butterfl...
Graphic Novel App netwars – The Butterfly Attack has Received Some New Episodes Posted by Jessica Fisher on January 27th, 2015 [ permalink ] | Read more »
DataVault Password Manager Review
DataVault Password Manager Review By Jennifer Allen on January 27th, 2015 Our Rating: :: SECURE DATA STORAGEUniversal App - Designed for iPhone and iPad Store your passwords and other sensitive information safely, thanks to... | Read more »

Price Scanner via MacPrices.net

Apple Releases New Tranche Of OS Updates For...
Apple has released incremental bugfix and security updates for its most recent Mac and iOS versions. OS X Yosemite 10.10.2 Update Apple says this update includes the following improvements: Resolves... Read more
Samsung To Be Main Supplier Of A9 Chips For i...
Korea’s Maeil Business Newspaper reports that Samsung has beat out its chipmaking rivals, Taiwan’s Qualcomm and TSMC, as supplier of chipsets for the next generations of both its own Galaxy S6 and... Read more
Save up to $340 on iMacs with Apple Certified...
The Apple Store has Apple Certified Refurbished iMacs available for up to $340 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
AppleCare Protection Plans on sale for up to...
B&H Photo has 3-Year AppleCare Warranties on sale for up to $105 off MSRP including free shipping plus NY sales tax only: - Mac Laptops 15″ and Above: $244 $105 off MSRP - Mac Laptops 13″ and... Read more
Apple refurbished Time Capsules available sta...
The Apple Store has certified refurbished Time Capsules available for up to $60 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $255... Read more
3TB AirPort Time Capsule on sale for $349, $5...
B&H Photo has 3TB AirPort Time Capsules on sale for $349 including free shipping plus NY sales tax only. Their price is $50 off MSRP, and it’s the lowest price available for this model (except... Read more
16GB iPad Air 2 on sale for $446, save $53
Walmart has 16GB WiFi iPad Air 2s on sale for $53 off MSRP on their online store. Choose free shipping or free local store pickup (if available). Sale prices available for online orders only, in-... Read more
Save up to $300 on a new Mac, $30 on an iPad,...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
MasterCard Brings Contactless Payment, Apple...
MasterCard, the official card of the Waste Management Phoenix Open, and the PGA TOUR are bringing the latest payment technology to the spectator experience with the introduction of contactless... Read more
Petitioning Dropbox For Mac OS X 10.4 and 10....
Last week Dropbox announced to its users that app support for Mac OS X 10.4 and 10.5 will end May 18 — disappointing news for those of us who are still getting useful service out of older PPC Macs... Read more

Jobs Board

*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Solutions Consultant - Retail Sales...
As an ambassador of the Apple brand, the ASC is accountable for driving sales performance by: Connecting with customers. Discovering customers' needs and values. Showing Read more
*Apple* Solutions Consultant- Retail Sales -...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Resellers store. The ASCs role is to grow Apple product Read more
Detailer *Apple* Ford Body Shop / Collision...
Apple Automotive is one of the fastest growing dealer…and it shows. Consider making the switch to the Apple Automotive Group today! At Apple Automotive , Read more
*Apple* Acura/Subaru Service Technicians - A...
Apple Automotive is one of the fastest growing dealer…and it shows. Consider making the switch to the Apple Automotive Group today! At Apple Automotive , Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.