Apple Mac Server OS X User Manual
Open Directory Programming Guide
Networking > Mac OS X Server
2007-01-08
Apple Inc.
© 2007 Apple Inc.
All rights reserved.
No part of this publication may be reproduced,
stored in a retrieval system, or transmitted, in
any form or by any means, mechanical,
electronic, photocopying, recording, or
otherwise, without prior written permission of
Apple Inc., with the following exceptions: Any
person is hereby authorized to store
documentation on a single computer for
personal use only and to print copies of
documentation for personal use provided that
the documentation contains Apple’s copyright
notice.
The Apple logo is a trademark of Apple Inc.
Use of the “keyboard” Apple logo
(Option-Shift-K) for commercial purposes
without the prior written consent of Apple may
constitute trademark infringement and unfair
competition in violation of federal and state
laws.
No licenses, express or implied, are granted
with respectto any of the technologydescribed
in this document. Apple retains all intellectual
property rights associated with the technology
described in this document. This document is
intended to assist application developers to
develop applications only for Apple-labeled
computers.
Every effort has been made to ensure that the
information inthis document is accurate. Apple
is not responsible for typographical errors.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
ASSUMING THE ENTIRE RISK AS TO ITS QUALITY
AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES RESULTINGFROM ANY
DEFECT OR INACCURACY IN THIS DOCUMENT,even
if advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple
dealer, agent, or employee is authorized to make
any modification, extension, or addition to this
warranty.
Some states do not allow the exclusion or limitation
of implied warranties or liability for incidental or
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have
other rights which vary from state to state.
.Mac is a registered service mark of Apple Inc.
Apple, theApple logo,AppleTalk, Bonjour, Mac,
Mac OS, and QuickTime are trademarks of
Apple Inc., registered in the United States and
other countries.
UNIX is a registered trademark of The Open
Group
Simultaneously published in the United States
and Canada.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO
THIS DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. AS A RESULT, THIS DOCUMENT IS
PROVIDED “AS IS,” AND YOU, THE READER, ARE
Contents
Introduction
Chapter 1
Chapter 2
Introduction 7
Organization of This Document 7
See Also 7
Concepts 9
Open Directory Overview 9
Nodes 10
Search Policies and Search Nodes 12
Record Types 12
Standard Attribute Types 14
Native Attribute Types 15
Authentication 15
Directory Proxy 21
Open Directory, lookupd, and NetInfo 22
Directory Service Command Line Utility 24
Debugging 24
Working with Nodes 25
Chapter 3
Listing Registered Nodes 25
Finding a Node 27
Opening and Closing a Node 28
Authenticating a User to a Node 29
Directory Native Authentication 30
Working with Records 33
Listing Records 33
Getting Information About a Record’s Attribute 35
Setting the Name of a Record 37
Creating a Record and Adding an Attribute 39
Deleting a Record 41
Document Revision History 43
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
3
CONTENTS
4
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
Figures, Tables, and Listings
Chapter 1
Chapter 2
Chapter 3
Concepts 9
Figure 1-1 Flow of an Open Directory request 10
Figure 1-2 An Open Directory request over a network 11
Figure 1-3 lookupd and NetInfo interaction when using SSH 23
Figure 1-4 lookupd, NetInfo, and Open Directory interaction when using SSH 23
Table 1-1 Standard record types 13
Table 1-2 Standard attribute types 14
Working with Nodes 25
Listing 2-1 Listing registered nodes 25
Listing 2-2 Finding the node for a pathname 27
Listing 2-3 Opening a node 28
Listing 2-4 Authenticating using directory native authentication 30
Working with Records 33
Listing 3-1 Listing records in a node 34
Listing 3-2 Getting information about a record’s attribute 36
Listing 3-3 Setting the name of a record 38
Listing 3-4 Creating and opening a record and adding an attribute 39
Listing 3-5 Deleting a record 41
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
5
FIGURES, TABLES, AND LISTINGS
6
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
INTRODUCTION
Introduction
This manual describes the Open Directory application programming interface for Mac OS X v10.4. Open
Directory is a directory service architecture whose programming interface provides a centralized way for
applications and services toretrieve information stored in directories. The Open Directory architecture consists
of the DirectoryServices daemon, which receives Open Directory client API calls and sends them to the
appropriate Open Directory plug-in.
Organization of This Document
This book contains the following chapters:
■ “Concepts” (page 9) describes the concepts used in the Open Directory architecture.
■ “Working with Nodes” (page 25) explains how to use the Open Directory API interact with nodes.
■ “Working with Records” (page 33) explains how to use the Open Directory API to interact with records.
See Also
Refer to the following reference document for Open Directory:
■ Open Directory Reference
For more information about writing plug-ins for Open Directory, read:
■ Open Directory Plug-in Programming Guide
Organization of This Document 7
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
INTRODUCTION
Introduction
8
See Also
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
CHAPTER 1
Concepts
Open Directory is a directory service architecture whose programming interface provides a centralized way
for applications and services to retrieve information stored in directories. Often, the information that is being
sought is configuration information stored in a NetInfo database or in flat files, with each file having its own
record format and field delimiters. Examples of configuration information include users and groups
(/etc/passwd and /etc/group), and automount information (/mounts). Open Directory uses standard
record types and attributes to describe configuration information so that Open Directory clients have no
need to know the details of record formats and data encoding.
Earlier directory services, such as lookupd and NetInfo, took the first steps in providing access to configuration
information but were limited in their capabilities. For example, lookupd provides support for reading but
does not provide support for writing, and it does not provide support for authentication. Open Directory
continues the evolution of directory services by providingexpanded functionality. For example, Open Directory
can writedata as well as read it, and Open Directory includessupport for a variety of authentication methods.
While providing support for lookupd and NetInfo, Open Directory’s primary protocol is LDAP (supporting
LDAPv2 and LDAPv3). As a result, Open Directory provides a way of accessing and sharing data using both
LDAP and NetInfo. Open Directory provides seamless and automatic integration of Apple Computer’s directory
services and third-party directory services including Active Directory, iPlanet and OpenLDAP.
Open Directory Overview
Open Directory consists of the DirectoryService daemon and Open Directory plug-ins. Apple Computer
provides Open Directory plug-ins for LDAPv3 (which supports LDAPv2), NetInfo, AppleTalk, SLP, Windows,
and Bonjour. The AppleTalk, SLP, SMB, and Bonjour Open Directory plug-ins discover services that are available
on the local network. In Mac OS X, lookupd resolves DNS queries through UNIX function calls like
gethostbyname(). TheOpen Directory LDAP plug-in provides information aboutusers and groups of users.
For information on writing your own Open Directory plug-in, see the document Open Directory Plug-ins.
Open Directory Overview 9
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
Request
Response
Open Directory client
DirectoryServices daemon
Open Directory plug-ins
CHAPTER 1
Concepts
Figure 1-1 Flow of an Open Directory request
The Open Directory programming interface identifies the basic features that are common to many directory
services and provides the functions necessary to support the development of high-quality applications that
can work with a wide range of dissimilar directory services.
Nodes
From the viewpoint of Open Directory, a directory service is a collection of one or more nodes, where a node
is a place that can be searched for information. Each NetInfo database in a hierarchy and each LDAP service
configured by the Directory Access tool is a separate node. The following rules apply to nodes.
■ A node is either the root of a directory or a child of another node.
■ A registered node is a node that an Open Directory plug-in has registered with Open Directory or that
an administrator has registered using the Directory Access tool.
■ A node is a collection of records and child nodes.
■ A record can belong only to one node.
■ A record has a type and can be of no more than one type. Examples of record types include user records
and group records.
■ A record has a name and type that together make the record unique within its node. For example, there
can’t be two user records that have the name “admin,” but there can be a user record named “admin”
and a group record named “admin” within the same node.
■ Nodes and records can contain any number of attributes.
■ An attribute can have a value. Certain attributes can have more than one value.
■ An attribute value is arbitrary data whose structure is unknown to the Open Directory programming
Figure 1-2 (page 11) shows how Open Directory and the Open Directory LDAPv3 and NetInfo plug-ins might
locate nodes over a network.
10
Open Directory Overview
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
interface. Open Directory clients are responsible for interpreting the value of any particular attribute.
Request
Response
Service-specific protocol
over the Internet or intranet
Open Directory client
DirectoryService daemon
Local System
Remote System
LDAP plug-in NetInfo plug-in
public.example.com
private.example.com
Publications
EngineeringMarketing
CHAPTER 1
Concepts
Figure 1-2 An Open Directory request over a network
Given the topology shown in Figure 1-2, the Open Directory function for listing registered nodes
(dsGetDirNodeList) might return the following list:
/NetInfo/root/AppleMarketing
/NetInfo/root/AppleEngineering
/NetInfo/root/ApplePublications
/LDAPv3/private.example.com
/LDAPv3/public.example.com
The first part of the node name (LDAPv3 and NetInfo in this example)is the name of the plug-in that handles
that node.
Open Directory Overview 11
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
CHAPTER 1
Concepts
Note:An Open Directory plug-in is not required to return information that conforms exactly to the information
that the directory service maintains. A plug-in can generate information “on the fly.” In addition, a plug-in
may not return information about certain nodes; the plug-in's behavior in this respect can be configurable.
Search Policies and Search Nodes
A search policy defines the locations that are to be searched and the order in which those locations are
searched in order to get certain kinds of information. The first location that a search policy defines must be
the local NetInfo database.
Search nodes implement search policies, which are configured by administrators through the Directory Access
application. Search nodes are easy for Open Directory applications to find and are guaranteed to always be
available.
There are four search node types:
■ authentication search node — Use this search node when you are looking for information that is needed
to authenticate a user. Use the pattern matching constant eDSAuthenticationSearchNodeName to
locate theauthentication search node. Examples of applications that use the authentication search node
include the login window and applications that set System Preferences. The authentication search node
is also used indirectly by all UNIX commands that use lookupd.
■ contacts search node — Use this search node when you are looking for contact information, such as an
e-mail address, a telephone number, or a street address. Use the pattern matching constant
eDSContactsSearchNodeName to locate the contacts search node. Mail.app and Address Book use the
contacts search node to look up e-mail addresses and other types of contact information.
■ network search node — Use this search node, which consolidates all of the nodes that are local to a
machine for service discovery purposes, to find services on the local network. When third-party Open
Directory plug-ins are loaded, they register their nodes with Open Directory so they can be found by
the network search node. Use the pattern matching constant eDSNetworkSearchNodeName to locate
the network search node.
■ locally hosted nodes — Use a locally hosted node to find NetInfo domains stored on this machine (that
is, the local domain plus any shared domains that are running locally). Locally hosted nodes are a class
of nodes that have a special pattern match. Use the pattern matching constant eDSLocalHostedNodes
to locate locally hosted nodes.
When an Open Directory client application uses a search node to search for information, it can request the
fully qualified path for any record that matches a specific search criteria. As a result, Open Directory can
perform extremely precise searches and a high degree of control over the type of information that is returned.
Record Types
Apple Computer has defined a series of standard record types. The standard record types include but are
not limited to user records, group records, machine records, and printer records.
12
Providers of services can define their own record types (known as native record types) and are encouraged
to publishinformation about them. Developers are encouraged touse Apple’s standard record typeswhenever
possible.
Open Directory Overview
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
CHAPTER 1
Concepts
Table 1-1 Standard record types
DescriptionConstant
Standard record for describing userskDSStdRecordTypeUsers
Standard record for describing groupskDSStdRecordTypeGroups
Standard record for describing machineskDSStdRecordTypeMachines
Standard record for describing hostskDSStdRecordTypeHosts
Standard record for describing printerskDSStdRecordTypePrinters
Standard record for describing records in the networks filekDSStdRecordTypeNetworks
Standard record for describing records in the services filekDSStdRecordTypeServices
Standard record for describing records in the protocols filekDSStdRecordTypeProtocols
kDSStdRecordTypeComputerLists
Standard record for describing RPC recordskDSStdRecordTypeRPC
Standard records for describing print serviceskDSStdRecordTypePrintService
Standard record for describing configuration recordskDSStdRecordTypeConfig
Standard record for describing AFP serverskDSStdRecordTypeAFPServer
Standard record for describing SMB serverskDSStdRecordTypeSMBServer
Standard record for describing FTP serverskDSStdRecordTypeFTPServer
Standard record for describing NFS serverskDSStdRecordTypeNFS
Standard record for describing Web serverskDSStdRecordTypeWebServer
Standard record for describing LDAP serverskDSStdRecordTypeLDAPServer
Standard record for describingQuickTime Streaming serverskDSStdRecordTypeQTSServer
Standard record for entries in the mount filekDSStdRecordTypeMounts
Standard record for storing computer informationkDSStdRecordTypeComputers
Standard record for storing information about a list of
computers
kDSStdRecordTypePresetUsers
Standard record for storing “preset” information used to
create new user records
kDSStdRecordTypePresetGroups
Standard record for storing “preset” information used to
create new group records
kDSStdRecordTypePresetComputerLists
Standard record for storing “preset” information used to
create new computer list records
Open Directory Overview 13
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
CHAPTER 1
Concepts
DescriptionConstant
kDSStdRecordTypePrintServiceUser
Standard record for storing quota usage for a user in the
local node
Standard record for storing bootp informationkDSStdRecordTypeBootp
Standard record for storing net domainskDSStdRecordTypeNetDomains
Standard record for storing EthernetskDSStdRecordTypeEthernets
Standard record for storing net groupskDSStdRecordTypeNetGroups
Standard record for storing host serviceskDSStdRecordTypeHostServices
Standard Attribute Types
Apple Computer has defined a series of standard attributes. Developers can define their own attributes
(known as native attributes). An attribute can be required or optional. Each record type defines the attributes
that it requires.
Open Directory clients are responsible for interpreting the value of any particular attribute. All configuration
and discovery of information in the directory service can be accomplished by requesting the appropriate
attribute value.
Table 1-2 lists some of the standard attribute types. See the Open Directory Reference section for the complete
list of attributes. Constants for attributes that start with kDS1 represent attributes that can only have one
value; constants for attributes that start with kDSN represent attributes that can have multiple values.
Table 1-2 Standard attribute types
DescriptionConstant
kDS1AttrPassword
kDS1AttrUniqueID
kDS1AttrPrimaryGroupID
kDS1AttrComment
kDS1AttrUserShell
kDS1AttrPrintServiceUserData
Standard attribute for storing a password; commonly found in
kDSStdRecordTypeUsers records
Standard attribute for storing a unique ID; commonly found in
kDSStdRecordTypeUsers records
Standard attribute for storing a Primary Group ID; commonly found in
kDSStdRecordTypeUsers and kDSStdRecordTypeGroups records
Standard attribute for storing a comment; commonly found in
kDSStdRecordTypeGroup, kDSStdRecordTypeUsers,
kDSStdRecordTypeComputers and other preset records
Standard attribute for storing the user’s shell; commonly found in
kDSStdRecordTypeUsers records
Standard attribute for print quota configuration or statistics; commonly
found in kDStdRecordTypePrintServiceUser records
14
Open Directory Overview
2007-01-08 | © 2007 Apple Inc. All Rights Reserved.
Loading...