Mac OS X provides a suite of command-line tools to view and manage the information in Open Directory. The most useful of these tools are:
dscl
A general-purpose interactive command-line tool for working with data in any Open Directory data source, including LDAP, NetInfo, SMB, and Bonjour. This tool can also be used in single-shot mode.
nicl
An interactive command-line tool for working with data in a NetInfo database. Unlike dscl
, this tool will not work with any other data source. This tool can also be used in single-shot mode.
nidump
Extracts data from a NetInfo database into either legacy Unix flat file formats (such as the files found in the /etc
directory) or into a NetInfo-specific raw format.
niload
Loads data from a flat file, either a Unix /etc
format file or a NetInfo raw format file.
niutil
A single-shot tool used for reading and writing information to a NetInfo database. You should consider using nicl
in single-shot mode instead of this tool.
nifind
Searches through a NetInfo database for directories that match a pattern.
nigrep
Searches through a NetInfo database for directories or properties that match a particular pattern.
Of these commands, the most useful are dscl
, nicl
,nidump
, and niload
.
Before you get too creative with your NetInfo database, you should make sure you have a good backup of it. You can create a backup simply by copying the /var/db/netinfo/local.nidb
directory. For example, you can use the following to create a backup:
sudo cp -R /var/db/netinfo/local.nidb /var/backups/backup.nidb
If you manage to get the NetInfo database into a state where it can’t be used, you can boot into single-user mode by holding down -S as the computer starts up. When you are presented with the single-user prompt (#
), execute the commands in Example 7-1.
Example 7-1. Restoring the NetInfo database in single-user mode
#/sbin/fsck -y
#/sbin/mount -uw /
#mv /var/db/netinfo/local.nidb /var/backups/damaged.nidb
#cp -R /var/backups/backup.nidb /var/db/netinfo/local.nidb
The first command makes sure that the filesystem is safe. The second command mounts the filesystem in read/write mode. The third command moves the damaged database out of the way. The fourth copies the backup copy of the database back into place.
The dscl
command-line tool is an interactive program like the shell, which means that when you run it, it stays active. And, like the shell, it features tab-completion and a history. This lets you navigate through the large amounts of data that can be present in Open Directory. The best way to learn how to use this tool is to go on a guided tour. Example 7-2 shows how to launch dscl
so it connects to Open Directory running on your local system.
The dot is important; it means connect to Open Directory on the local system. You’ll notice that the prompt changes to the greater-than (>
) symbol. This means that dscl
is ready to accept your commands. Table 7-1 lists the various commands you can use. The top level of the directory tree that you are at when you start dscl
contains the various directory sources that Open Directory has access to. To see these sources of directory information, use the list
command, as shown in Example 7-3.
Table 7-1. dscl commands
Command |
Description |
---|---|
|
Prints out the various commands for |
|
Lists the subdirectories of the given directory. If no path is given, the subdirectories of the current directory will be listed. |
|
Changes the working directory to the path given. |
|
Reads the properties in a directory. If no path is given, the current path is used. You can specify a particular key of a property to read. If no key is given, all the properties of the path will be printed. |
|
Searches for records that match a pattern at the given path. |
|
Authenticate to the system as a user. You can either specify a password or let |
|
Creates a path or a property with the given key and value at a path. This command will overwrite any existing path or property. |
|
Appends a property value to the property at the given path. |
|
Appends a property value to the property at the given path if the value does not already exist. |
|
Deletes a path or a property value at the given path. |
|
Changes the property value at the given path. |
|
Changes the property value at a given index for the given path. |
|
Changes the password for the user whose record is at a given path. |
|
Quits |
Example 7-3. Using the dscl list command
/ > list
NetInfo
LDAPv3
PasswordServer
Bonjour
SLP
SMB
Search
Contact
/ >
To take a look at the NetInfo database that serves as the local directory service domain, use cd
and then the list
command, as shown in Example 7-4.
Example 7-4. Using the dscl cd and list commands
/ >cd NetInfo/
/NetInfo/root >list
AFPUserAliases Aliases Config Groups Hosts Machines Networks Users /NetInfo/root >
You’ll notice the exact same set of subdirectories in the NetInfo tree here as you saw in NetInfo Manager, with one key difference, the initial letter in each directory name is in uppercase. This reflects a mapping from the lowercase names that NetInfo uses to the new naming convention used by Open Directory. You can view the properties of a subdirectory record with the read
command, as shown in Example 7-5.
To take a look at the NetInfo database that serves as the local directory service domain, use the cd
and then the list
commands as shown in Example 7-4.
Example 7-5. Using the dscl read command
/NetInfo/root > read Users/jldera
_shadow_passwd:
_writers_hint: jldera
_writers_passwd: jldera
_writers_picture: jldera
_writers_realname: jldera
_writers_tim_password: jldera
naprivs: -2147483137
sharedDir:
AppleMetaNodeLocation: /NetInfo/root
AuthenticationAuthority: ;ShadowHash;HASHLIST:<SALTED-SHA1,SMB-NT,SMB-LAN-MANAGER>
AuthenticationHint:
GeneratedUID: 1827A3B8-CBD8-4466-B817-0E47FB30D441
NFSHomeDirectory: /Users/jldera
Password: ********
Picture: /Library/Caches/com.apple.user501pictureCache.tiff
PrimaryGroupID: 501
RealName: Jason Deraleau
RecordName: jldera
RecordType: dsRecTypeStandard:Users
UniqueID: 501
UserShell: /bin/bash
Once again, you should notice that this is basically the same information that you saw in NetInfo Manager, but some of the names are different. You’ll also notice the difference in capitalization due to a bit of translation behind the scenes between the older NetInfo style of naming and the newer Open Directory style. Table 7-2 provides a mapping of these properties. If you just want to read a single property from a user record, you can use the read
command, as shown in Example 7-6.
Table 7-2. Mapping Between Open Directory- and NetInfo-style user property names
Open Directory property key |
NetInfo property key |
---|---|
AuthenticationAuthority |
authentication_authority |
AuthenticationHint |
hint |
GeneratedUID |
generateduid |
NFSHomeDirectory |
home |
Password |
passwd |
Picture |
picture |
PrimaryGroupID |
gid |
RealName |
realname |
RecordName |
name |
UniqueID |
uid |
UserShell |
shell |
Example 7-6. Reading a single property from a user record
/NetInfo/root/Users > read jldera UserShell
UserShell: /bin/bash
So far, you’ve only been reading values from the database. To write a value, you’ll first need to authenticate and then use the create
command. For example, if you wanted to set the AuthenticationHint
property, you would use the set of commands shown in Example 7-7.
Example 7-7. Writing a property to a user record
/NetInfo/root/Users >auth jldera
Password:********
/NetInfo/root/Users >create jldera AuthenticationHint "Name of my pet"
Now, when you take a look at the AuthenticationHint
property, you’ll see that it has changed, as shown in Example 7-8.
Example 7-8. Checking a modified property
/NetInfo/root/Users > read jldera AuthenticationHint
AuthenticationHint: Name of my pet
One important thing to note about the auth
command is that it will authenticate you only in the directory database in which you are working. For example, if you have an LDAPv3 directory configured in Open Directory, when you authenticate in the NetInfo database, you are not authenticated in the LDAPv3 database.
When you are ready to leave the dscl
shell, use the quit
command.
You can also use dscl
in single-shot mode—this is where you can enter a command directly at the shell prompt and it won’t result in an interactive shell. For example, from the command line, we can read the AuthenticationHint
property, as shown in Example 7-9.
The nicl
command works in much the same way as the dscl
command. The major difference between the two is that nicl
presents only data in the NetInfo database and presents property names in NetInfo format. To run nicl
, use the command shown in Example 7-10.
When you are at the nicl
prompt, you can use the same commands as dscl
, listed in Table 7-1. For example, to list the directories at the top of the NetInfo tree, use the list
command, as shown in Example 7-11.
Example 7-11. Using the nicl list command
/ > list
1 users
2 groups
3 machines
4 networks
5 protocols
6 rpcs
7 services
8 aliases
9 mounts
10 printers
You can see from the output in Example 7-11 that each directory in the NetInfo database has a number associated with it as well as a name. To read the properties associated with a user, use the read
command, as shown in Example 7-12. The property names are quite similar to those used when viewing the data with dscl
. Table 7-2 lists mappings of some major properties.
Example 7-12. Using the nicl read command
/ > read /users/jldera
name: jldera
home: /Users/jldera
gid: 501
picture: /Library/Caches/com.apple.user501pictureCache.tiff
uid: 501
hint:
sharedDir:
shell: /bin/bash
passwd: ********
authentication_authority: ;ShadowHash;HASHLIST:<SALTED-SHA1,SMB-NT,SMB-LAN-MANAGER>
realname: Jason Deraleau
generateduid: 1827A3B8-CBD8-4466-B817-0E47FB30D441
naprivs: -2147483137
_writers_passwd: jldera
_writers_tim_password: jldera
_writers_picture: jldera
_writers_hint: jldera
_shadow_passwd:
_writers_realname: jldera
The nidump
command is used primarily for outputting the contents of the NetInfo database in standard Unix formats and for making backups of the database. For example, to output the user information in the database in the traditional format used by /etc/passwd
, you would use the nidump
command, as shown in Example 7-13.
Example 7-13. Using the nidump command
$nidump passwd .
nobody:*:-2:-2::0:0:Unprivileged User:/var/empty:/usr/bin/false
root:*:0:0::0:0:System Administrator:/var/root:/bin/sh
daemon:*:1:1::0:0:System Services:/var/root:/usr/bin/false
unknown:*:99:99::0:0:Unknown User:/var/empty:/usr/bin/false
lp:*:26:26::0:0:Printing Services:/var/spool/cups:/usr/bin/false
postfix:*:27:27::0:0:Postfix User:/var/spool/postfix:/usr/bin/false
www:*:70:70::0:0:World Wide Web Server:/Library/WebServer:/usr/bin/false
eppc:*:71:71::0:0:Apple Events User:/var/empty:/usr/bin/false
mysql:*:74:74::0:0:MySQL Server:/var/empty:/usr/bin/false
sshd:*:75:75::0:0:sshd Privilege separation:/var/empty:/usr/bin/false
qtss:*:76:76::0:0:QuickTime Streaming Server:/var/empty:/usr/bin/false
cyrusimap:*:77:6::0:0:Cyrus IMAP User:/var/imap:/usr/bin/false
mailman:*:78:78::0:0:Mailman user:/var/empty:/usr/bin/false
appserver:*:79:79::0:0:Application Server:/var/empty:/usr/bin/false
clamav:*:82:82::0:0:Clamav User:/var/virusmails:/bin/tcsh
amavisd:*:83:83::0:0:Amavisd User:/var/virusmails:/bin/tcsh
jabber:*:84:84::0:0:Jabber User:/var/empty:/usr/bin/false
xgridcontroller:*:85:85::0:0:Xgrid Controller:/var/xgrid/controller:/usr/bin/false
xgridagent:*:86:86::0:0:Xgrid Agent:/var/xgrid/agent:/usr/bin/false
appowner:*:87:87::0:0:Application Owner:/var/empty:/usr/bin/false
windowserver:*:88:88::0:0:WindowServer:/var/empty:/usr/bin/false
tokend:*:91:91::0:0:Token Daemon:/var/empty:/usr/bin/false
securityagent:*:92:92::0:0:SecurityAgent:/var/empty:/usr/bin/false
jldera:********:501:501::0:0:Jason Deraleau:/Users/jldera:/bin/bash
panic:********:502:502::0:0:Colonel Panic:/Users/panic:/bin/bash
To make a backup of the NetInfo database, handy for when you want to make potentially harmful changes, use the following command:
$ nidump -r / . > nibackup.txt
The niload
command is complementary to nidump
. This command can accept a variety of Unix /etc
file formats as input to add data to a NetInfo database. For example, the following command loads a /etc/passwd
-style file named userlist
into the database:
$ niload passwd . < userlist
To perform a full database restore from the output of an nidump
command, you would use the following command:
$ niload -r / . < nibackup.txt