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

Evernote 6.13.2 - Create searchable note...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
calibre 3.14.0 - Complete e-book library...
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
HoudahSpot 4.3.4 - 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
Hopper Disassembler 4.3.10- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
Hopper Disassembler 4.3.10- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
Paparazzi! 1.0b7 - Make user-defined siz...
Paparazzi! is a small utility for OS X that makes screenshots of webpages. This very simple tool takes screenshots of websites which do not fit on one screen. You specify the desired width, minimal... Read more
Amadeus Pro 2.4.4 - Multitrack sound rec...
Amadeus Pro lets you use your Mac for any audio-related task, such as live audio recording, digitizing tapes and records, converting between a variety of sound formats, etc. Thanks to its outstanding... Read more
Google Chrome 63.0.3239.108 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Apple Configurator 2.6 - Configure and d...
Apple Configurator makes it easy to deploy iPad, iPhone, iPod touch, and Apple TV devices in your school or business. Use Apple Configurator to quickly configure large numbers of devices connected to... Read more
WhatRoute 2.0.26 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more

Latest Forum Discussions

See All

WWE Mayhem guide - beginner tips and tri...
WWE Mayhem brings all of the familiar faces from your favorite wrestling league to mobile in this exciting new fighting game. Build up a team of your favorite WWE superstars and fight your way to the championship title, or battle against your... | Read more »
The best new games we played this week -...
We've made it through another week, so let's treat ourselves to some of the best new games to launch in the past few days. It was another exciting week with some long-awaited indie games making their debut, and some big console titles making the... | Read more »
Match blocks to pull off dance moves in...
Ferdinand: Unstoppabull is a brand new match three puzzler based on the animated movie of (almost) the same name. As you can expect, you have to match blocks together to complete a bunch of puzzling levels and earn a high score. [Read more] | Read more »
Lineage 2: Revolution’s end of year upda...
Now available in 54 countries worldwide, Lineage 2: Revolution is continuing its global quest to be the most popular mobile MMORPG by launching a jam-packed end of year update. Complete with many subtle tweaks to help improve users’ online... | Read more »
The 5 best Star Wars games on iOS
The time has almost come.Star Wars: The Last Jedifinally hits theaters in the cinematic event that might be bigger than Christmas. To celebrate, we're taking a look at the best--and only the best--Star Warsmobile games to date. [Read more] | Read more »
Life Is Strange (Games)
Life Is Strange 1.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1 (iTunes) Description: Life Is Strange is a five part episodic game that sets out to revolutionize story-based choice and consequence games by... | Read more »
Oddworld: New 'n' Tasty (Game...
Oddworld: New 'n' Tasty 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: ** PLEASE NOTE: Requires 3.6GB free space to install. Runs at variable resolutions based on device capabilities.... | Read more »
Gorogoa (Games)
Gorogoa 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Gorogoa is an elegant evolution of the puzzle genre, told through a beautifully hand-drawn story designed and illustrated by Jason... | Read more »
Why Guns of Boom will be big for mobile...
Earlier this week, Game Insight, the minds that brought you Guns of Boom, revealed plans for an esports mode in the popular FPS title, with big implications for the game's future. Guns of Boom has been quite popular for some time now, so it's... | Read more »
The best mobile games to play on lazy ho...
With the holidays in full swing, there's hopefully going to be a lot of time off work lazing around the house. With all of that free time, it's a perfect opportunity to catch up on some mobile games that you might have missed out on earlier this... | Read more »

Price Scanner via MacPrices.net

Sunday flash sale: Beats Solo3 Wireless On-Ea...
Amazon has Beats Solo3 Wireless On-Ear Headphones on sale for $199.99 including free shipping. Their price is $100 off MSRP, and it’s the lowest price available for Beats Solo3. Multiple colors are... Read more
B&H Holiday sale: MacBooks for up to $300...
B&H Photo has Apple MacBook Pros, MacBook Airs, and 12″ MacBooks on sale for up to $300 off MSRP as part of their Holiday sale. B&H charges sales tax in NY & NJ only, and overnight... Read more
The lowest prices on Apple 13″ MacBook Pros t...
Save $300-$300 on the purchase of a 2017 13″ MacBook Pro this weekend with Certified Refurbished models at Apple. In many cases, Apple’s refurbished prices are the lowest available for each model... Read more
Lowest prices of the Holiday season: 15″ Appl...
Save $360-$420 on the purchase of a 2017 15″ MacBook Pro with Certified Refurbished models at Apple. In many cases, Apple’s refurbished prices are the lowest available for each model from any... Read more
Apple discounts Beats products by up to 30% t...
Apple has Beats by Dr. Dre (BeatsX, Powerbeats3 Wireless, and Beats Solo3 Wireless) on sale for up to 30% off their retail price from now until December 26th: – BeatsX: Was $149.95, now $99 –... Read more
Updated Price Trackers: Macs, iPads, iPhones,...
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: – 15″... Read more
How to preorder a new iMac Pro and pay zero s...
B&H Photo and Adorama are accepting preorders on multiple configurations of the new Apple iMac Pro. Both resellers charge sales tax for residents of NY & NJ only, and shipping is free.... Read more
Apple Macs back in stock at Amazon with model...
Amazon has MacBook Pros, MacBook Airs, MacBooks, and iMacs on sale for up to $200 off MSRP as part of their Holiday/Christmas sale. Shipping is free. Note that stock of some Macs may come and go (and... Read more
Apple offering free overnight delivery on all...
Apple is now offering free overnight delivery on all in stock products until 3pm local time on December 22nd. This includes new as well as refurbished computers. Click here for more information. Read more
Beats Holiday sale at B&H, headphones and...
B&H Photo has Beats by Dr. Dre headphones, earphones, and speakers on sale for up to $80 off MSRP as part of their Holiday sale. Expedited shipping is free, and B&H charges sales tax to NY... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.