Manual Pages for UNIX Darwin command on man dscl

dscl(1) BSD General Commands Manual dscl(1)

NAME

ddssccll - Directory Service command line utility

SYNOPSIS

ddssccll [options] [datasource [command]] options:

-pp prompt for password

-uu user authenticate as user

-PP password authentication password

-ff filepath targeted local node database file path

-rraaww don't strip off prefix from DirectoryService API

constants

-pplliisstt print out record(s) or attribute(s) in XML plist

format

-uurrll print record attribute values in URL-style encod-

ing

-qq quiet - no interactive prompt

commands:

-rreeaadd [path [key ...]]

-rreeaaddaallll [path [key ...]]

-rreeaaddppll path key plistpath

-rreeaaddppllii path key valueindex plistpath

-lliisstt path [key]

-sseeaarrcchh path key val

-ccrreeaattee recordpath [key [val ...]]

-ccrreeaatteeppll recordpath key plistpath val1 [val2 ...]

-ccrreeaatteeppllii recordpath key valueindex plistpath val1 [val2

...]

-aappppeenndd recordpath key val ...

-mmeerrggee recordpath key val ...

-ddeelleettee path [key [val ...]]

-ddeelleetteeppll recordpath key plistpath [val ...]

-ddeelleetteeppllii recordpath key valueindex plistpath [val ...]

-cchhaannggee recordpath key oldval newval

-cchhaannggeeii recordpath key valindex newval

-ddiiffff path1 path2 [key ...]

-ppaasssswwdd userpath [newpassword | oldpassword newpassword]

available only in interactive mode:

-ccdd dir

-ppuusshhdd [dir]

-ppooppdd

-aauutthh [user [password]]

-aauutthhoonnllyy [user [password]]

-qquuiitt

DESCRIPTION

ddssccll is a general-purpose utility for operating on Directory Service

directory nodes. Its commands allow one to create, read, and manage Directory Service data. If invoked without any commands, ddssccll runs in an

interactive mode, reading commands from standard input. Interactive pro-

cessing is terminated by the quit command. Leading dashes ("-") are

optional for all commands. ddssccll operates on a datasource specified on the command line. This may be a node name or a Mac OS X Server (10.2 or later) host specified by DNS hostname or IP address. Node names may be absolute paths beginning with

a slash ("/"), or relative domain paths beginning with a dot (".") char-

acter, which specifies the local domain, or "..", specifying the local domain's parent. If the hostname or IP address form is used then the

user must specify the -uu option and either the -PP of -pp options to spec-

ify an administrative user and password on the remote host to authenti-

cate with to the remote host. The exception to this is if "localhost" is specified. Passing passwords on the command line is inherently insecure and can cause password exposure. For better security do not provide the password as part of the command and you will be securely prompted.

The datasource may also be specified as "localonly" in which case a sepa-

rate DirectoryService daemon process is activated which contains only the

Local plugin for use by dscl. If no file path is provided then access

goes only to the registered local nodes on the system. However, if the -ff

option is specified then access is added to the local node "/Local/Tar-

get" which points to the database located at the provided filepath. One

example is to provide the filepath of "/Volumes/Build100/var/db/dslo-

cal/nodes/Default" and then access to that database is provided via the nodename "/Local/Target". PPAATTHH SSPPEECCIIFFIICCAATTIIOONN There are two modes of operation when specifying paths to operate on. The two modes correspond to whether the datasource is a node or a host. In the case of specifying a node, the top level of paths will be record types. Example top level paths would be: /Users/alice /Groups/admin In the case of specifying a host as a data source, the top level of paths

correspond to Open Directory plug-ins and Search Paths. One can specify

the plug-in to traverse to a node name, after which the paths are equiva-

lent to the former usage. The following might be the equivalent paths as the above paths: /NetInfo/root/Users/alice /LDAPv3/10.0.1.42/Groups/admin If path components contain keys or values with embedded slash characters, the slash characters must be escaped with a leading backslash character. Since the shell also processes escape characters, an extra backslash is required to correctly specify an escape. For example, to read a mount

record with the name "ldapserver:/Users" in the "/Mounts" path, the fol-

lowing path would be used:

ddssccll . -rreeaadd /Mounts/ldaphost:\/Users

All pathnames are case-sensitive.

CCOOMMMMAANNDDSS The action of each command is described below. Some commands have aliases. For example, "cat" and "." are aliases for "read". Command aliases are listed in parentheses. rreeaadd ((ccaatt ..)) Usage: read [path [key ...]] Prints a directory. Each of the properties are printed one per line.

The property key is followed by a colon, then a space-separated list of

the values for that property. Note that a value which contains embedded spaces will appear identical to a pair of values.

If The -rraaww flag for raw output has been given, then read prints the full

DirectoryService API constant for record and attribute types.

If the -uurrll flag has been specified then printed record path attribute

values are encoded in the style of URLs. This is useful if a script or program is trying to process the output since values will not have any spaces or other control characters. rreeaaddaallll Usage: readall [path [key ...]] readall prints all the records of a given type. The output of readall is

formatted in the same way as read with a "-" on a line as a delimeter

between records. rreeaaddppll Usage: readpl path key plistpath Prints the contents of plistpath. The plistpath is followed by a colon, then a whitespace, and then the value for the path. If the plistpath is the key for a dictionary or array, the contents of it are displayed in plist form after the plistpath. If plistpath is the key for a string, number, bool, date, or data object, only the value is printed out after the plistpath. rreeaaddppllii Usage: readpli path key valueindex plistpath Prints the contents of plistpath for the plist at valueindex of the key. The plistpath is followed by a colon, then a whitespace, and then the value for the path. If the plistpath is the key for a dictionary or array, the contents of it are displayed in plist form after the plistpath. If plistpath is the key for a string, number, bool, date, or data object, only the value is printed out after the plistpath. lliisstt ((llss)) Usage: list path Lists the subdirectories of the given directory. Subdirectories are listed one per line. In the case of listing a search path, the names are preceded by an index number that can act as a shortcut and 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. sseeaarrcchh path key val Searches for records that match a pattern. The search is 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. ccrreeaattee ((mmkk)) Usage: create recordpath [key [val ...]] Creates a record, property, or value. If only a record path is given, the create command will create the record if it does not exist. If a key is given, then a property with that key will be created.

WARNING - If a property with the given key already exists, it will be

destroyed and a new property will be created in its place. To add values to an existing property, use the append or merge commands. If values are included in the command, these values will be set for the given key.

NOTE - Not all directory nodes support a property without a value. An

error will be given if you attempt to create a property with no value in such a directory node. ccrreeaatteeppll Usage: createpl recordpath key plistpath val1 [val2 ...] Creates a string, or array of strings at plistpath.

If you are creating a value at the root of a plist that is an array, sim-

ply use "0" as the plistpath. If only val1 is specified, a string will be created at plistpath. If val1 val2 ... are specified, an array of strings will be created at plistpath.

WARNING - If a value with the given plistpath already exists, it will be

destroyed and a new value will be created in its place. ccrreeaatteeppllii Usage: createpli recordpath key valueindex plistpath val1 [val2 ...] Creates a string, or array of strings at plistpath for the plist at valueindex of the key.

If you are creating a value at the root of a plist that is an array, sim-

ply use "0" as the plistpath. If only val1 is specified, a string will be created at plistpath. If val1 val2 ... are specified, an array of strings will be created at plistpath.

WARNING - If a value with the given plistpath already exists, it will be

destroyed and a new value will be created in its place. aappppeenndd Usage: append recordpath key val ... Appends one or more values to a property in a given record. The property is created if it does not exist. mmeerrggee Usage: merge recordpath key val ... Appends one or more values to a property in a given directory if the property does not already have those values. The property is created if it does not exist. cchhaannggee Usage: change recordpath key oldval newval Replaces the given old value in the list of values of the given key with the new value in the specified record. cchhaannggeeii Usage: changei path key index val Replaces the value at the given index in the list of values of the given key with the new value in the specified record. index is an integer value. An index of 1 specifies the first value. An index greater than the number of values in the list will result in an error. ddiiffff Usage: diff path1 path2 key ... Compares the data from path1 and path2 looking at the specified keys (or all if no keys are specified). ddeelleettee ((rrmm)) Usage: delete path [key [val ...]] Delete a directory, property, or value. If a directory path is given, the delete command will delete the directory. This 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 given key. ddeelleetteeppll Usage: deletepl recordpath key plistpath [val ...] Deletes a value in a plist. If no values are given deletepl deletes the plistpath. If one or more values are given, deletepl deletes the values within plistpath. ddeelleetteeppllii Usage: deletepli recordpath key valueindex plistpath [val ...] Deletes a value for the plist at valueindex of the key. If no values are given deletepli deletes the plistpath. If one or more values are given, deletepli deletes the values within plistpath. ppaasssswwdd Usage: passwd userpath [newpasword | oldpassword newpasword] Changes a password for a user. The user must be specified by full path, not just a username. If you are authenticated to the node (either by

specifying the -uu and -PP flags or by using the auth command when in

interactive node) then you can simply specify a new password. If you are not authenticated then the user's old password must be specified. If passwords are not specified while in interactive mode, you will be

prompted for them. Passing these passwords on the command line is inher-

ently insecure and can cause password exposure. For better security do not provide the password as part of the command and you will be securely prompted. IINNTTEERRAACCTTIIVVEE CCOOMMMMAANNDDSS ccdd Usage: cd dir Sets the current directory. Path names for other ddssccll commands may be relative to the current directory. ppuusshhdd ((ppdd)) Usage: pushd path Similar to the pushd command commonly found in Unix shells. When a path is specified it sets the current directory while pushing the previous directory on to the directory stack. If no path is specified it exchanges the top two elements of the directory stack. It will also print the final directory stack. ppooppdd Usage: popd Pops the directory stack and returns to the new top directory. It will also print the final directory stack. aauutthh ((ssuu)) Usage: auth [user [password]] Authenticate as the named user, or as "root" if no user is specified. If a password is supplied, then that password is used for authentication, otherwise the command prompts for a password. If ddssccll is run in host mode, then when this command is run the current directory must be in the subdirectories of a node. aauutthhoonnllyy Usage: authonly [user [password]] Used to verify the password of a named user, or of "root" if no user is specified. If a password is supplied, then that password is used for authentication, otherwise the command prompts for a password. If ddssccll is run in host mode, then when this command is run the current directory must be in the subdirectories of a node. qquuiitt ((qq)) Usage: quit Ends processing of interactive commands and terminates the program. ccoommmmaanndd hhiissttoorryy The up and down arrow keys will scan through the command history. ttaabb ccoommpplleettiioonn When pathnames are being typed, pressing the tab key will result in a

search to auto-complete the typed partial subdirectory name. It will also

attempt to correct capitilization in the process. EEXXAAMMPPLLEESS

-vviieeww aa rreeccoorrdd iinn tthhee llooccaall ddiirreeccttoorryy nnooddee

dscl . -read /Users/www

-ccrreeaattee oorr rreeppllaaccee tthhee UUsseerrSShheellll aattttrriibbuuttee vvaalluuee ffoorr tthhee wwwwww uusseerr rreeccoorrdd

dscl . -create /Users/www UserShell /usr/bin/false

-ccrreeaattee oorr rreeppllaaccee tthhee tteesstt kkeeyy ooff tthhee mmccxxaapppplliiccaattiioonnddaattaa::llooggiinnwwiinnddooww

pplliisstt vvaalluuee ffoorr tthhee MMCCXXSSeettttiinnggss aattttrriibbuuttee ooff tthhee uusseerr11 uusseerr rreeccoorrdd

dscl . -createpl /Users/user1 MCXSettings mcxapplica-

tiondata:loginwindow:test value

-lliisstt tthhee uunniiqquueeIIDD vvaalluueess ffoorr aallll uusseerr rreeccoorrddss oonn aa ggiivveenn nnooddee

dscl /LDAPv3/ldap.company.com -list /Users UniqueID

-aappppeenndd aa vvaalluuee tthhaatt hhaass ssppaacceess iinn iitt

dscl . -append /Users/www Comment "This is a comment"

DIAGNOSTICS

ddssccll will return -1 (255) on error.