Apple ® section

Leopard Directory Services - dscl and related commands

I was no great fan of Netinfo, and I think it's great that Apple has gone to XML driven Directory Services as a replacement. It turns out that modifying "niutil" scripts isn't too painful; Apple has a post about Converting Scripts for Leopard, but it doesn't give many examples.

Let's look at adding a user to a group. With "niutil", we would have done something like:

sudo niutil -readprop / /groups/uucp users | grep tom
 

to see if "tom" was already in "uucp", and

sudo niutil -mergeprop / /groups/uucp users tom
 

to add "tom" to "uucp". How would you do that with Leopard?

First, there are a number of "ds" commands. If you type "ds" in a Terminal window and then hit TAB twice, you'll see these:

dscacheutil    dsconfigldap   dserr          dsmemberutil   
dscl           dseditgroup    dsexport       dsperfmonitor  
dsconfigad     dsenableroot   dsimport       dsymutil 
 

Note the "dsenableroot" - if I want to give root a password so that I can actually login, I can do:

dsenableroot -u apl 
 

("apl" is an account with admin privileges)

That will ask me for my password, and then a password for "root". We don't need this (or even "sudo") to add "tom" to "uucp", but I thought I'd mention it in passing.

After reading the various man pages, it looks like "dseditgroup" is the right tool to use, but first I need to check to see if "tom" is already a member, and "dsmemberutil" seems to be the easy way to do that:

$ dsmemberutil checkmembership -U tom -G uucp
user is not a member of the group
$ dsmemberutil checkmembership -U tom -G tom
user is a member of the group
 

OK, good so far. Well, semi-good so far. Let's take a closer look:

$ dsmemberutil checkmembership -U tom -G uucp
user is not a member of the group
$ echo $?
0  
$ dsmemberutil checkmembership -U tom -G tom
user is a member of the group
$ echo $?
0

Ugh. It would have been nicer for scripting if dsmemberutil returned 1 on failure. But actually, there's an even nastier problem here..

There is no "uucp" group.

You can verify that by asking dscl to list out the groups for you:

$ dscl . -list  /Groups | grep uucp
_uucp 
 

No, it's not that all groups have been replaced with these underscored versions:

$ dscl . -read  /Groups/uucp
AppleMetaNodeLocation: /Local/Default
GeneratedUID: ABCDEFAB-CDEF-ABCD-EFAB-CDEF00000042
Password: *
PrimaryGroupID: 66
RecordName: _uucp uucp
RecordType: dsRecTypeStandard:Groups
SMBSID: S-1-5-21-166
 

Notice the "RecordName: _uucp uucp"? It seems like groups can have multiple names? Indeed, that is true. If we had really used a nonexistent group name, we would have got an error:

dsmemberutil checkmembership -U tom -G foo
The group foo cannot be found
There was an unknown error.
Group not found
 

Ok, here we are, we know "tom" is not a member of "uucp" (or "_uucp"), and we'd like to add that. The man pages seems pretty straightforward; "dseditgroup " seems like the easiest thing to use. The man page even has a very similar example:

     dseditgroup -o edit -n /LDAPv3/ldap.company.com -u myusername -p -a
              username -t user extragroup

                    The group extragroup from the node
                    /LDAPv3/ldap.company.com will have the username added if
                    the username is in a user record on the search policy and
                    if the correct password is presented interactively for the
                    user myusername which also need to have write access.
 

So, since I am already a member of the admin group, I would do this:

dseditgroup -n . -u apl  -a tom -t user uucp
$ dsmemberutil checkmembership -U tom -G uucp
user is a member of the group
 

That will ask me for my password, and will add the record. I could do the same thing with "dscl":

$ dscl -u apl . -merge  /Groups/uucp GroupMembership tom
$ dsmemberutil checkmembership -U tom -G uucp
user is a member of the group
 

Or, I could do:

sudo dscl . -append /Groups/uucp GroupMembership tom
 

Two changes there: I used "sudo" instead of "-u apl", and I also used -append instead of -merge.

Well, that's good.. at least I can do this. Unfortunately, without checking back with "checkmembership", you'd never know it: if you try to add a user to a group that doesn't exist, "dscl" makes no complaint and returns no error. The "dseditgroup" will complain (as it should).

I really suggest playing around with this stuff before you get too cocky. It's easy enough to create a test group to play with:

sudo dseditgroup -o create -n . foo
 

You can then practise adding and removing users:

$ dsmemberutil checkmembership -U dean -G foo
user is not a member of the group
$ dscl -u apl . -append /Groups/foo GroupMembership dean
Password: 
$ dsmemberutil checkmembership -U dean -G foo
user is a member of the group
$ dscl -u apl . -delete /Groups/foo GroupMembership dean
Password: 
$ dsmemberutil checkmembership -U dean -G foo
user is not a member of the group
 

The actual files are in /var/db/dslocal/nodes/Default (you will need to have enabled root to poke around here). For example, here's the file "foo.plist" in /var/db/dslocal/nodes/Default/groups:

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DT
Ds/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>        <key>generateduid</key>
        <array>
                <string>35E0E4DD-2660-44C6-87F8-043672BD386E</string>
        </array>
        <key>gid</key>
        <array>
                <string>500</string>
        </array>
        <key>name</key>
        <array>
                <string>foo</string>
        </array>
        <key>users</key>
        <array>
                <string>apl</string>
        </array>
</dict>
</plist>
 

As "dscl" really gives you everything you need to manipulate these files, you shouldn't need to look at them directly, but it's nice to know that you can, isn't it?

4 comments

More Articles by Anthony Lawrence - Find me on Google+

Click here to add your comments




Sat May 31 06:02:27 2008:   andre


Very helpful, thank you very much!



Thu Oct 16 10:30:31 2008:   peter


I'm new to directory services and found this article very clear and succinct - better than anything I found on Apple's support pages



Fri Nov 6 02:26:55 2009:   Janus


Thank you for a very nice introduction to directory services!

Playing around I stumbled over the following:
160-233:~ janus$ dsmemberutil checkmembership -U janus -G staff
user is a member of the group
160-233:~ janus$ dscl . -read /Groups/staff GroupMembership
GroupMembership: root

There is clearly something I haven't understood, because I expected the user 'janus' to be listed in the last line. Would you care to comment?



Fri Nov 6 03:31:19 2009:   TonyLawrence


I don't know:

 

$ dsmemberutil checkmembership -U apl -G foo 

user is a member of the group 

$ dscl . -read /Groups/foo GroupMembership  

GroupMembership: apl dean 

 

Don't miss responses! Subscribe to Comments by RSS or by Email

Click here to add your comments

If you want a picture to show with your comment, go get a Gravatar

Jump to Comments

Many of the products and books I review are things I purchased for my own use. Some were given to me specifically for the purpose of reviewing them. I resell or can earn commissions from the sale of some of these items. Links within these pages may be affiliate links that pay me for referring you to them. That's mostly insignificant amounts of money; whenever it is not I have made my relationship plain. I also may own stock in companies mentioned here. If you have any question, please do feel free to contact me.

Specific links that take you to pages that allow you to purchase the item I reviewed are very likely to pay me a commission. Many of the books I review were given to me by the publishers specifically for the purpose of writing a review. These gifts and referral fees do not affect my opinions; I often give bad reviews anyway.

We use Google third-party advertising companies to serve ads when you visit our website. These companies may use information (not including your name, address, email address, or telephone number) about your visits to this and other websites in order to provide advertisements about goods and services of interest to you. If you would like more information about this practice and to know your choices about not having this information used by these companies, click here.