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 specifies that read will display the full DirectoryService API constant for record and attribute types.

-url specifies 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
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<./code>) .

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

mcxread record path [optArgs] [appDomain [keyName]] Used to display existing values for MCX preference key(s). [optArgs] -v mcxVersion Specifies which version of the key should be retrieved. If this parameter is omitted, version 1 keys are searched for. -o filePath Specifies the output file where results should be written. If this parameter is omitted, results are written to stdout. -format xml | plist | text Specifies how the output should be formatted. If omitted, the default is 'text'. appDomain Specify the application domain you want to retrieve keys from.
If this parameter is omitted or is equal to '=' then all application domains will be dumped for the specified record.

keyName Specify 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 =
Displays, 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]]] ======================================================================================= Used to set values for a new or existing MCX preference key. [optArgs] -v mcxVersion Specifies the version of the key to set. If this parameter is omitted, version 1 keys will be created. appDomain Specify the application domain in which the key is to be set. keyName Specify the name of the key being set mcxDomain Specify 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). keyValue Specify the new value for the specified key. Values can be specified using the same syntax as used by the 'defaults' command line tool. If the value parameter is omitted, then the existing value for the key will not be updated. UPK The (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) You can specify 'input' as a shorthand for 'mcx_input_key_names'. You can specify 'output' as a shorthand 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: mcxset /Users/mcx1 com.apple.dock autohide always -bool 1 Sets the 'autohide' key in the com.apple.dock domain to a value of TRUE with 'always' management. mcxset . com.apple.dock autohide once Moves the 'autohide' key to 'once' management, preserving the existing value of the key. mcxset . com.apple.dock autohide none Removes management of the autohide key in com.apple.dock domain for the current record. mcxset . com.apple.dock autohide . -bool 0 Sets the value of autohide to FALSE, preserving the existing management level mcxset . com.apple.dock tilesize . real64.0/real Sets the tilesize key to the floating point number 64.0 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] ================================================================== Used to update the value of an existing MCX preference key. [optArgs] -v mcxVersion Specifies the version of the key to set. If this parameter is omitted, version 1 keys will be edited. appDomain Specify the application domain in which the key is to be set. keyPath Specify the path to the EXISTING key to be edited. keyValue Specify 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: mcxedit . com.apple.dock autohide -bool 1 Change the autohide key to TRUE, preserving current management setting mcxedit . com.apple.systemuiserver mount-controls:dvd '(authenticate, eject)' Sets the 'dvd' key within the 'mount-controls' dictionary to the array containing two strings: 'authenticate' and 'eject' mcxedit . com.apple.systemuiserver mount-controls:dvd arraystringauthenticate/stringstringeject/string/array Same effect as previous example, just using xml syntax mcxedit . com.apple.systemuiserver mount-controls:dvd:1 deny 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 Remove the 'dvd' key of the 'mount-controls' dictionary
mcxdelete record path [optArgs] [appDomain [keyName]] =========================================================== Used to remove management of MCX preference key(s). This is equivalent to using the mcxset command with a 'mcxDomain' value of 'none'. [optArgs] -v mcxVersion Specifies the version of the key to delete. If this parameter is omitted, version 1 keys will be deleted. appDomain Specify the application domain in which the key is to be set. Omitting this parameter, or specifying '=' means all application domains will be processed. keyName Specify the name of the key to be deleted. Omitting this parameter, or specifying '=' means all keys in the application domain will be deleted. Examples: mcxdelete . com.apple.dock autohide No longer manage the 'autohide' Dock key. mcxdelete . com.apple.dock Delete management of all Dock-related keys. mcxdelete . Delete management of all keys for the current record. 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: mcxdeleteall Users Assuming the current working directory points to a DS node, this command will remove all management keys for all users. mcxdeleteall Computers com.apple.dock Assuming the current working directory points to a DS node, this command will remove management of all Dock-related keys for all computer records. mcxdeleteall Groups com.apple.dock autohide Assuming the current working directory points to a DS node, this command will remove management of the 'autohide' Dock key for all group records. mcxdeleteall . Assuming the current working directory points to a DS node, this command will remove all management keys for all users, groups, computers, computer groups and computer lists in the node. mcxexport record path [optArgs] [appDomain [keyName]] ========================================================= Same functionality as the 'mcxread' command but produces output in a format that can later be imported using 'mcximport'. Usually you will also want to specify the -o optional argument to cause the output to be written to a file. Examples: 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 Causes mcximport to delete any key found in the import file from the record. This is equivalent to calling mcxdelete for every key in the import file. The value of the key in the import file is ignored. file path Specify the location of the 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