CSS: Providing seven essential vitamins and minerals since 1996.

Have a steaming hot, delicious slice of Standards.

A Closer Look at Mac OS X's dscl Command

November 5, 2011 by Richard

dscl is a directory utility included in both Mac OS X client and server. You'll find a great deal of information about this command simply reading the man page:


    man dscl

Following are my personal notes on this command.

Creating a new user


 # dscl . -create /Users/username

Immediately following the call to the dscl command is the path argument.

When the directory path is a dot, the user is created on the local Mac OS X instance only. (the user will not be a network user)

Creating a new user requires an administrator's account. To automate this process, you may include an administrator's username and password directly in the call to the command.


 # dscl -u username -P password . -create /Users/username

Including the username and password in the command call will allow you to create scripts to create useres without a password prompt. If you do not wish to include the username and password in the command call, you can use sudo instead.

Creating a network user

Mac OS X provides excellent integration with both Open Directory and Microsoft Active Directory networks. Creating a network user requires only slight modifications to the dscl command.

Working with Open Directory

If joined to open directory, and you you wish to create a user in open directory, the command line call will look something like this:


 # dscl -u username -P password /LDAPv3/moria.deadmarshes.com -create /Users/username

moria.deadmarshes.com is the hostname I use for my own Open Directory server, if you're running the command on the same server Open Directory resides, you might need to change the path argument to /LDAPv3/127.0.0.1

When working with Open Directory, the username and password that you provide will be that of an Open Directory administrator.

Working with Active Directory

If joined to a Microsoft Active Directory domain, the directory path should be something like /Active Directory/All Domains


 # dscl -u username -P password '/Active Directory/All Domains' -create /Users/username

This command will create a new user in the Microsoft Active Directory domain controller provided that the username and password that you provide to the argument is an Active Directory network user with privileges to do so.

The Mac OS X client or server instance MUST be joined to Active Directory prior to attempting to manipulate data in Active Directory.

Complete Creation of the User Account

Before the account will be created, you'll now need to run a series of commands to append additional meta data to the account. This will be done by specifying key value pairs for the new user account. Each of the following calls to the dscl command will need to be modified appropriately depending on whether you are working with a local user, an open directory user, or an active directory user. To keep things simple, I'll just stick with the syntax used to create a local user.

Set the user's default shell

The following command set's the user's default shell to bash.


 # dscl . -create /Users/username UserShell /bin/bash

Set the user's full name

Aside from the shortname that you assigned to the user, the user's 'RealName' attribute can also be used at the login prompt to login to Mac OS X.


 # dscl . -create /Users/username RealName "Dr. First Last"

Note that any time spaces or special characters appear in an argument, that argument can be enclosed with either single or double quotes, or the spaces can be escaped using the backslash character.

Set the user's unique user id

The user's unique user id will be a unique number assigned to the user. To find out what user ids are already used you can run the following command:


 # dscacheutil -q user

The unique id will be the uid value, you'll want to create a new uid that's not already in use. To assign a new uid run the following:


 # dscl . -create /Users/username UniqueID 506

Set the user's primary group id

Each user will need to have a primary group. On Mac OS X systems, usually you want each user's primary group to be the 'staff' group. In order to assign a group id, you need to know the gid value, like the uid, the gid is a unique number assigned to each group. You can list all groups using the following command:


 # dscacheutil -q group

In my case, the gid of the group staff is 20, so I now run the following command to assign that gid to become my user's primary group id.


 # dscl . -create /Users/username PrimaryGroupID 20

Set the user's home directory

Upon logging into Mac OS X, each user will need his or her own home folder on the system. Setting a user's home directory can be done with the following command:


 # dscl . -create /Users/username NFSHomeDirectory /Users/username

Setting the user's password

This one is easy enough. Again, if special characters are involved, simply enclose the password in quotations marks or escape using the backslash character.


 # dscl . -passwd /Users/username newPassword

Making a user an admin

If you would like a user to have admin privileges on the machine, that can be done with the following command:


 # dscl . -append /Groups/admin GroupMembership username

Giving a user SSH access

If you would like a user to have the ability to login remotely via SSH, that can be done with the following command:


 # dscl . -append /Groups/com.apple.access_ssh GroupMembership username

Updating Records in either Open Directory or Active Directory

To get an idea of what you can modify in either Open Directory or Active Directory user accounts, first, it is useful to be able to list a user's entire account. That can be done with the following command:


 # dscl '/Active Directory/All Domains' -read /Users/username

This command will print a very long list of information associated with a user account, including useful things you might need to modify, such as:

City
Comment
Company
EMailAddress
JobTitle
FirstName
LastName
NickName
PostalCode
PhoneNumber
RealName
State
Street
And many others...

To create a key for a user account when the key does not already exist, you use the following command:


 # dscl

    -u authorizedDomainUser

    -P authorizedDomainPassword

     '/Active Directory/All Domains'

     -merge

     /Users/username

     RealName

     'My Name'

To update a key for a user account when the key already exists, you use the following command:


 # dscl

    -u authorizedDomainUser

    -P authorizedDomainPassword

     '/Active Directory/All Domains'

     -change

     /Users/username

     RealName

     'My Name'

To remove a key from a user account, you use the following command:


 # dscl

    -u authorizedDomainUser

    -P authorizedDomainPassword

     '/Active Directory/All Domains'

     -delete

     /Users/username

     RealName

Reading Keys

Finally, it is also useful to read a single key value pair for a given user account. That can be done using the following command:


 # dscl

    -u authorizedDomainUser

    -P authorizedDomainPassword

     '/Active Directory/All Domains'

     -read

     /Users/username

     RealName

If the key does not exist, the result will contain the string 'No such key', which you can then use to determine whether or not you need to update a key that already exists or create a new key.

Authenticating Users

The dscl command can also be used to authenticate users. This is done with the following command:


 # dscl "/Active Directory/All Domains" -authonly 'username' 'password'

If authentication is successful, there will be NULL output to the terminal, if authentication was not successful, something along the lines of:


Authentication for node /Local/Default failed. (-14090, eDSAuthFailed)
 DS Error: -14090 (eDSAuthFailed)

...will be output to stderr.

Name:Required
Email:Required, but won't be published with your comment.
Website:Not Required
Comment:	Simple HTML is allowed: <code>, <b>, <i>, <u>, <var>, <strong>, <em>, <blockquote>, <ul>, <ol>, <li>, <p> (no attributes). All spacing and line breaks in your comment will be preserved.
What Year is it?
Remember My Information:

* All comments are moderated and are subject to approval.
Your comment will appear once it has been approved.
Posting multiple times will not expedite the approval process.

Subscribe to Feed

A Closer Look at Mac OS X's dscl Command