dscl

DirectoryService

files as of Oct 2007
use dscl instead of netinfo

Directory Service

     dscl [ -u user ][ -p | -P password][ -f filepath] [-raw] [-plist] [-url][ -q ] [datasource [command]]

(v10.5.3)

Creates, reads, and manage Directory Service data.

Without any commands runs in an interactive mode, reading commands from standard input.

dscl (Directory Services Command Line ) is a very basic key access editor for a very flexable and complex datastore. It provides all the basic editor commands like list, search, create, read, append, merge, change and delete, in addition to diff .
It has no knowledge of the particulers of the datastore such as which keys are valid or used for a particular path, nor does it have any rules as to which type of values are valid for particular keys let alone which values are appropriate.
It does seem to be the tool to access the user authorization datastore for OS X.

tab completion: When pathnames are being typed, pressing tab will search to auto-complete the partial name, showing posible matches and attempting to correct capitilization .

Without options enters interactive mode.

options
-u user required when using DS Proxy
-p prompt for password
-P [password  
-f filepath targeted file path for DS daemon running in localonly mode
example: /Volumes/Build100/var/db/dslocal/nodes/Default
Nodename to use is fixed at /Local/Target
-raw don't strip off prefix from DS constants
-plist XML plist format
-url attribute values in URL-style encodin>
-q quiet - no interactive prompt

datasource

localhost default
localonly activates a DirectoryService daemon process with Local node only - daemon quits after use
hostName requires DS proxy support, ( DS-158)
nodeName Directory Service style node name
domainName NetInfo style domain name

Directory Service directory nodes.

dscl operates on a


  Node names
  If hostname or IP address form is used -u and either -P or -p the remote host to authenticate with to the remote host, except for localhost.
For the localonly a separate DirectoryService daemon process is activated which contains only the Local plugin .

If no file path is provided access goes only to the registered local nodes on the system.
With -f access is added to the local node Local/Target which points to the database located at the filepath.
Example: filepath of Volumes/Build100/var/db/dslocal/nodes/Default and then access to that database is provided via the nodename Local/Target

PATH SPECIFICATION

The modes of operation correspond to whether the datasource is a node or a host.
For a node, the top level of paths will be record types.
Example top level paths :
/Users/alice
/Groups/admin

For a host the top level of paths correspond to Open Directory plug-ins and Search Paths. Specify the plug-in to traverse to a node name, after which the paths are equivalent to the former usage. These might be the equivalent paths as the above :

/NetInfo/root/Users/alice
/LDAPv3/10.0.1.42/Groups/admin

If path components contain keys or values with embedded / characters, they must be escaped with a backslash . Since the shell also processes escape characters, an extra backslash is required to correctly specify an escape.
To read a mount record with the name "ldapserver:/Users" in the "/Mounts" path, use:

dscl . read /Mounts/ldaphost:\/Users

Commands

read [path [key …]]
cat .
Displays a directory, properties are displayed one per line, the key is followed by a colon, then a space-separated list of the values.
A value which contains embedded spaces will appear as a pair of value!.??

-raw that read will display the full DirectoryService API constant for record and attribute types.

-url that record path attribute values are encoded in the style of URLs, useful if a script or program is trying to process the output since values will not have any spaces or other control characters.
readpl[i] path key [value_index] plist_path Displays the contents of plist_path,
[with i: for the plist at value_index (index is an integer value, origin 1.) ]
of the key,
followed by a colon, a whitespace, and the value for the path.

If the plist_path is the key for a dictionary or array, the contents of it are displayed in plist form after the plist_path.
If plist_pathis the key for a string, number, bool, date, or data object, only the value is displayed.

readall [path [key ]] Display all the records of a given type, formatted in the same way as read with a "-" on a line as a delimeter between records.
list [path]
ls
Lists subdirectories
In the case of listing a search path, names are preceded by an index shortcut can be used in place of the name when specifying a path.

When used in interactive mode, the path is optional.
With no path given, the current directory will be used.

BSD
Local

Search
Contact
search path key val
Searches for records that match a pattern, rooted at the given path.
The path may be a node path or a record type path.
Valid keys are Directory Service record attribute types.
create record_path [key [val]]
mk
Creates a record, property, or value.
If only a record path is given, create the record if it does not exist.
If a key is given, then a property with that key will be created.
To add values to an existing property, use append or merge .
WARNING - an existing property with the given key will be destroyed.

If values are included, they will be set for the given key.
Not all directory nodes support a property without a value.

createpl[i] record_path key [value_index] plist_path v1 [v2] Creates a string, or array of strings at plist_path.
[with i: for the plist at value_index ]
To create at the root of a plist that is an array, use "0" as the plist_path.
If only v1 is specified, a string will be created at plist_path
If v1 v2 … are specified, an array of strings will be created at plist_path.

WARNING - Existing value with the given plist_path will be destroyed .

append record_path key val Appends one or more val to key in record_path.
The property is created if it does not exist.

merge record_path key val Appends one or more val to a property in record_path.
if the property does not already have those values.
The property is created if it does not exist.

change[i] record_path key [old_val|index] new_val Replaces old_val or
[ with i: the value at index in the list of values of key ]
with the new_val in record_path.
diff path1 path2 [key] Compares the data from path1 and path2
delete path [key [val …]]
rm
Delete a directory, property, or value. If a directory path is given, the delete command will delete the directory.
Can only be used on record type and record paths.
If a key is given, then a property with that key will be deleted.
If one or more values are given, those values will be removed from the property with the key.

deletepl[i] record_path key [index] plist_path [val …] Deletes a value in a plist.
[ with i: the value at index of the key]
If no values are given deletepl deletes plist_path.
If one or more values are given, deletes the values within plist_path.
passwd user_path [new_pasword | old_password new_pasword] Changes a password for a user by full path, not just a username.
If you are authenticated to the node (either by specifying -u and -P or by using the auth command when in interactive node) then
specify a new password.
If you are not authenticated then the user's old password must be specified.

Additional interactive commands

cd dir Sets the current directory
pushd [pathr][
pd
When a path is specified sets the current directory while pushing the previous directory on to the directory stack.
If no path is specified exchanges the top two elements of the directory stack.
Displays the final directory stack.

popd Pops the directory stack, returns to the new top directory and displays the final directory stack.

auth (su)[user [password]] Authenticate as the named user, default root .
If running in host mode, the current directory must be in the subdirectories of a node.

authonly [user [password]] Verify the password of a user, default root.
MCX Extensions:
mcxread record path [optArgs] [appdomain [keyName]]
mcxset record path [optArgs] appdomain keyName [mcxdomain [keyvalue]]
mcxedit record path [optArgs] appdomain keyPath [keyvalue]
mcxdelete record path [optArgs] [appdomain [keyName]]
mcxexport record path [optArgs] [appdomain [keyName]]
mcximport record path [optArgs]
mcxhelp
If dscl is run in host mode, then when this command is run the current directory must be in the subdirectories of a node.

EXAMPLES

View a record in the local directory node
 dscl . read /Users/www
AppleMetaNodeLocation: /Local/Default
GeneratedUID: FFFFEEEE-DDDD-CCCC-BBBB-AAAA00000046
NFSHomeDirectory: /Library/WebServer
Password: *
PrimaryGroupID: 70
RealName:
 World Wide Web Server
RecordName: _www www
RecordType: dsRecTypeStandard:Users
UniqueID: 70
UserShell: /usr/bin/false

> dscl
Entering interactive mode... (type "help" for commands)

 ls
 cd

Create or replace the UserShell attribute value for the www user record
dscl . -create /Users/www UserShell /usr/bin/false

Create or replace the test key of the mcx_application_data:loginwindow plist value for the MCXSettings attribute of the user1 user record
dscl . -createpl /Users/user1 MCXSettings mcx_application_data:loginwindow:test value

List the uniqueID values for all user records on a given node
dscl /LDAPv3/ldap.company.com -list /Users UniqueID

Attempt append a value that has spaces in it
dscl . -append /Users/www Comment "This is a comment"
dscl returns - (255) on error.

> read /Users/dgerman
Cannot open remote host, error: DSOpenDirServiceErr

Don't forget the dot!

dgerman 8/7/12

#  dscl . read /Users/dgerman | cut -c1-120  # don't show ALL the JPEGphoto
dsAttrTypeNative:_writers_hint: dgerman
dsAttrTypeNative:_writers_jpegphoto: dgerman
dsAttrTypeNative:_writers_LinkedIdentity: dgerman
dsAttrTypeNative:_writers_passwd: dgerman
dsAttrTypeNative:_writers_picture: dgerman
dsAttrTypeNative:_writers_realname: dgerman
dsAttrTypeNative:_writers_UserCertificate: dgerman
dsAttrTypeNative:accountPolicyData: <xml version="1.0" encoding="UTF-8">
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>creationTime<key> <real>1453774461.1459241<real>
    <key>failedLoginCount<key> <integer>0<integer>
    <key>failedLoginTimestamp<key> <integer>0<integer>
    <key>lastLoginTimestamp<key> <real>978307200<real>
    <key>passwordLastSetTime<key> <real>1354061376<real>
<dict>
<plist>

dsAttrTypeNative:LinkedIdentity:
 <xml version="1.0" encoding="UTF-8"?>
<DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>appleid.apple.com<key>
    <dict>
        <key>allows password reset<key> <true/>
        <key>linked identities<key>
        <array> <dict> <key>unverified name<key> <string>dgermanapl@real-world-systems.com<string> <dict> <array>
    <dict>
<dict>
<plist>


AppleMetaNodeLocation: /Local/Default
AuthenticationAuthority: ;Kerberosv5;
;dgerman@LKDC:SHA1.E08104A89DD6B9076C3EAFDB36F44C0C27EAB1A3;
LKDC:SHA1.E08104A89DD6B9076C3EAFDB36F44C0C27EAB1A3;
;ShadowHash;HASHLIST:
AuthenticationHint: initals 2x hex
Building: Real-world-Systems.com
GeneratedUID: D974AB7E-DDD1-4F89-823F-B65965D43013
HomePhoneNumber: 973/226-6672
JPEGPhoto: ffd8ffe0 00104a46   … + + + + + + + + + + many words of hex + + + + + + + + + +  …
NFSHomeDirectory: /Users/dgerman       link to /Volumes/DATA/dgerman
Password: ********
Picture: /Library/User Pictures/Animals/Butterfly.tif
PrimaryGroupID: 20
RealName: Dennis German
RecordName: dgerman
RecordType: dsRecTypeStandard:Users
UniqueID: 501
UserShell: /bin/bash 

 
./Default: aliases config groups machines networks users 
                   .plist
./Default/aliases: administrator manager nobody operator  MAILER-AGENT MAILER-DAEMON postmaster dumper 

./Default/config: KerberosKDC SharePoints 

./Default/config/SharePoints:
 Dennis German's Public Folder
 admin's Public Folder
 rut's Public Folder

./Default/groups:
_amavisd        _appowner       _appserveradm   _appserverusr   _ard            _atsserver 
_calendar       _clamav         _cvs
_devdocs        _guest          _installer      _jabber         _keytabusers    
_lp             _lpadmin        _mailman        _mcxalr         _mdnsresponder  _mysql
_pcastagent     _pcastserver    _postdrop       _postfix        _qtss 
_sandbox        _securityagent  _serialnumberd  _spotlight      _sshd           _svn     
_teamsserver    _tokend         _unknown        _update_sharing _uucp           _windowserver _www 
_xgridagent     _xgridcontroller 
 accessibility  admin       authedusers bin     certusers       consoleusers
 daemon         dialer      everyone    group   interactusers   kmem      localaccounts
 mail           netaccounts netusers    network nobody          nogroup   operator        owner
 procmod        procview    smmsp       staff   sys             tty       utmp            wheel

 com.apple.sharepoint.group.1   com.apple.sharepoint.group.2          com.apple.sharepoint.group.3

./Default/machines: broadcasthost localhost 
./Default/networks: loopback

./Default/users:
  _amavisd      _appowner       _appserver      _ard            _atsserver      _calendar   _clamav         _cvs _cyrus     _devdocs   
  _eppc         _installer      _jabber         _lp _mailman    _mcxalr         _mdnsresponder  _mysql      _pcastagent     _pcastserver    
  _postfix      _qtss           _sandbox        _securityagent  _serialnumberd  _spotlight      _sshd _svn  _teamsserver    _tokend
  _unknown      _update_sharing _uucp           _windowserver   _www            _xgridagent _xgridcontroller

  admin     dgerman    root     rut     nobody  daemon  

> dscl . read /users/dgerman | cut-c1-90 # cut to mininize JPG output scl_cmd DS Error: -14009 (eDSUnknownNodeName) oops dscl while interactive

ls xxxxxx (does not report anything) Maybe it's not a directory, try read xxxxxx

See

DirectoryService, DirectoryServiceAttributes(7) mactech.com/articles/mactech/Vol.22/22.10/2210MacInTheShell/index.html

August 25, 2003 Mac OS X


11/29/12
dscl . read /Groups/staff
AppleMetaNodeLocation: /Local/Default
GeneratedUID: ABCDEFAB-CDEF-ABCD-EFAB-CDEF00000014
GroupMembers: FFFFEEEE-DDDD-CCCC-BBBB-AAAA00000000
GroupMembership: root
Password: *
PrimaryGroupID: 20
RealName: Staff
RecordName: staff BUILTIN\Users
RecordType: dsRecTypeStandard:Groups
SMBSID: S-1-5-32-545

MCX Extensions

The record path specifies which record in the directory node is to be operated on (example: /Users/mcx1) (required)
In interactive mode use '.' to mean 'current directory' (the directory that was last set using the 'cd' command).

Example appDomain : 'com.apple.dock'

Example keyName parameter : 'tilesize'

The keyPath parameter is a path to a sub-plist within an existing key value. For example mount-controls:dvd:1 means the 2nd element within the array with the key name dvd within the key called mount-controls (first being 0)

The mcxDomain is the type of management applied to the key: none (not managed), always, once, often or unset.

The keyValue is the new value to be used for a key. Use the same syntax as the defaults command line tool.
When specifying plist or xml values, enclose the parameter in apostrophes.
For example:

    dscl  ...  '(authenticate, eject)'
    dscl  ...  'real64.0/real'
The MCX extensions follow the same syntax as other dscl comamnds, follow the same authentication rules and can be used in both interactive and command-line modes

Local command-line example

$ dscl . mcxread /Users/mcxtest com.apple.dock tilesize
$ dscl -u admin -P apple . mcxset /Users/mcxtest com.apple.dock tilesize always -float 32
Local interactive example
> $ dscl
> cd /NetInfo/Users/mcxtest
> mcxread . com.apple.dock =
** for write-based commands you must first 'cd' to the appropriate node and then issue the 'auth' command **
> cd /NetInfo/Users/mcxtest
> auth admin apple
> mcxset . com.apple.dock tilesize always -float 32
Remote command-line example
$ dscl -u diradmin -P apple 10.0.116.132 mcxread /LDAPv3/127.0.0.1/Users/phd1 = =
It's not possible to use commands that require write access to the node remotely (example mcxset) .

Remote interactive example

$ dscl -u diradmin -P apple 10.0.116.132
> mcxread /LDAPv3/127.0.0.1/Users/phd1 com.apple.SoftwareUpdate CatalogURL
** for write-based commands you must first 'cd' to the appropriate node and then issue the 'auth' command **
> cd /LDAPv3/127.0.0.1
> auth diradmin apple
> mcxset Users/phd1 com.apple.dock tilesize always -float 62.5

Display existing values for MCX preference key(s).
mcxread record path [optArgs] [appDomain [keyName]]

[optArgs]

-v mcxVersion which version of the key should be retrieved. Default version 1 keys are searched for.
-o filePath the output file where results should be written. Default results are written to stdout.
-format xml|plist|text how the output should be formatted. Default text.
appDomain the application domain you want to retrieve keys from.
If omitted or = then all application domains will be dumped for the specified record.

keyName the name of the key you want to retrieve. If omitted or is equal to '=' then all keys will be displayed.

Examples:
Display the value of the 'autohide' key in the 'com.apple.dock' application domain
mcxread /Users/mcx1 com.apple.dock autohide
. Display in XML format, all the keys in the 'com.apple.dock' application domain
mcxread /Users/mcx1 -format xml com.apple.dock =
Display in plist format, all keys for all application domains for the current record
mcxread . -format plist = = mcxset record path [optArgs] appDomain keyName [mcxDomain<[keyValue [UPK]]] [optArgs]
-v mcxVersion version of the key to set. If omitted, version 1 keys will be created.
appDomain application domain in which the key is to be set.
keyName name of the key being set
mcxDomain the type of management to be applied to the key. See above for valid values. Additionally, if this parameter is missing or '.' then an existing key will be searched for and the existing management value will not be changed. Setting management to 'none' is the same as deleting the key (will remove management for that key in the specified record).
keyValuenew value for the specified key. Values can be specified using the same syntax as used by the 'defaults' command line tool. If the existing value for the key will not be updated.
UPK (optional) value for the Union Policy Key. If present, the UPK *must* be specified as a dictionary. The valid keys for the dictionary include:
mcx_input_key_names (single string or array of strings)
mcx_output_key_name (single string)
mcx_remove_duplicates (boolean)
mcx_union_as_dictionary (boolean)
mcx_replace (boolean)

Specify input for mcx_input_key_names, output for mcx_output_key_name.
If either mcx_input_key_names or mcx_output_key_name is omitted, the value of keyName will be used for the missing value(s).

.Examples:

        Set the 'autohide' key in the com.apple.dock domain to a value of TRUE with 'always' management.
    mcxset /Users/mcx1 com.apple.dock autohide always -bool 1
    
        Move the 'autohide' key to 'once' management, preserving the existing value of the key.
    mcxset . com.apple.dock autohide once
        
        Remove management of the autohide key in com.apple.dock domain for the current record.
    mcxset . com.apple.dock autohide none
    
        Set the value of autohide to FALSE, preserving the existing management level
    mcxset . com.apple.dock autohide . -bool 0
    
        Set the tilesize key to the floating point number 64.0
    mcxset . com.apple.dock tilesize . real64.0/real
    
    

Examples specifying UPKs:

mcxset . com.apple.test testkey-Raw always '(1,2,3)' '< input=testkey-Raw; output=testkey; mcx_remove_duplicates=1; mcx_replace=1; mcx_union_as_dictionary=0;}' mcxset . com.apple.test testkey-Raw always '< keya=a; keyb=b; keyc=c; }' '< output=testkey; mcx_union_as_dictionary=1;}'
mcxedit record path [optArgs] appDomain keyPath [keyValue]
update the value of an existing MCX preference key. [optArgs]
-v mcxVersion version of the key to set. default version 1 keys will be edited.
appDomain the application domain in which the key is to be set.
keyPath the path to the EXISTING key to be edited.
keyValue the new value for the specified key path. Values can be specified using the same syntax as used by the 'defaults' command line tool. If the value parameter is omitted, then the key path will be deleted. NOTE: It is not permissable to delete an entire key using this command. To delete an entire key, use 'mcxset' and specify a management domain of 'none'.
Examples:
        Change the autohide key to TRUE, preserving current management setting
    mcxedit . com.apple.dock autohide -bool 1
    
        Set the 'dvd' key within the 'mount-controls' dictionary to the array containing two strings: 'authenticate' and 'eject'
    mcxedit . com.apple.systemuiserver mount-controls:dvd '(authenticate, eject)'
        
        Same effect as previous example, just using xml syntax
    mcxedit . com.apple.systemuiserver mount-controls:dvd arraystringauthenticate/stringstringeject/string/array
        
        Change the 2nd array element within the 'dvd' key of the 'mount-controls' dictionary to the string 'deny'
    mcxedit . com.apple.systemuiserver mount-controls:dvd:1 deny
    
        Remove the 'dvd' key of the 'mount-controls' dictionary
    mcxedit . com.apple.systemuiserver mount-controls:dvd
mcxdelete record path [optArgs] [appDomain [keyName]] ==
remove management of MCX preference key(s). equivalent to using the mcxset command with a 'mcxDomain' value of 'none'.

[optArgs]

-v mcxVersion version of the key to delete. If omitted, version 1 keys will be deleted.
appDomain application domain in which the key is to be set. Omitting or specifying '=' means ALL application domains will be processed.
keyName name of the key to be deleted. Omitting or specifying '=' means ALL keys in the application domain will be deleted.
Examples:
        No longer manage the 'autohide' Dock key.
    mcxdelete . com.apple.dock autohide
    
        Delete management of all Dock-related keys.
    mcxdelete . com.apple.dock
    
        Delete management of all keys for the current record.
    mcxdelete .
mcxdeleteall record path [optArgs] [appDomain [keyName]]
Works identically to mcxdelete except that this command does not require you to specify a path to a specific record. Instead, the path can point to a node or record type and all records within will be processed. Examples:
        Assuming the current working directory points to a DS node, remove all management keys for ALL users.
    mcxdeleteall Users

        
        , remove management of all Dock-related keys for ALL computer records.
    mcxdeleteall Computers com.apple.dock
        
        , remove management of the 'autohide' Dock key for ALL group records.
    mcxdeleteall Groups com.apple.dock autohide

        , remove ALL management keys for ALL users, groups, computers, computer groups and computer lists in the node.  
    mcxdeleteall .
mcxexport record path [optArgs] [appDomain [keyName]]

Same functionality as mcxread produces output in a format that can later be imported using mcximport. Usually specify -o to cause the output to be written to a file.

Example:

    mcxexport . -o /tmp/export.plist com.apple.dock
mcximport record path [optArgs] file path
= Imports the keys/values previously exported using 'mcxexport'. Each key/value in the import file will be processed as if the data were passed to 'mcxset'. This means the data in the import file is added to the existing data in the record.

[optArgs]

-d Delete ANY key found in the import file from the record. equivalent to calling mcxdelete for every key in the import file. The value of the key in the import file is ignored.
file file containing the data to be imported.
Examples:
    mcximport . /tmp/export.plist
    mcximport . -d /tmp/export.plist

Use dscl instead of netinfo

sudo plistbuddy /private/var/db/dslocal/nodes/Default/users/dgerman.plist >0  # some unprintable stuff! jpegphoto

Example of user plist as displayed by plistbuddy Opendirectory.

sudo ls -l /private/var/db/dslocal/nodes/Default/users/dgerman.plist
rw-------  1 root  wheel  336094 Mar 17 12:04 /private/var/db/dslocal/nodes/Default/users/dgerman.plist
./Default/groups users aliases config machines networks