Apple Mac Server OS X User Manual

0 (0)

Open Directory Programming Guide

Networking > Mac OS X Server

2007-01-08

Apple Inc.

Nopartofthispublicationmaybereproduced, 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 withoutthepriorwrittenconsentofApplemay constitute trademark infringement and unfair competition in violation of federal and state laws.

No licenses, express or implied, are granted withrespecttoanyofthetechnologydescribed in this document. Apple retains all intellectual propertyrightsassociatedwiththetechnology 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 informationinthisdocumentisaccurate. Apple is not responsible for typographical errors.

Apple Inc.

1 Infinite Loop Cupertino, CA 95014 408-996-1010

.Mac is a registered service mark of Apple Inc.

Apple,theApplelogo,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, APPLEMAKESNOWARRANTYORREPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY,ORFITNESSFORAPARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE

ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGESRESULTINGFROMANY DEFECTORINACCURACYINTHISDOCUMENT,even if advised of the possibility of such damages.

THEWARRANTYANDREMEDIESSETFORTHABOVE AREEXCLUSIVEANDINLIEUOFALLOTHERS,ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty.

Somestatesdonotallowtheexclusionorlimitation of implied warranties or liability for incidental or consequentialdamages,sotheabovelimitationor exclusionmaynotapplytoyou.Thiswarrantygives you specific legal rights, and you may also have other rights which vary from state to state.

Introduction	Introduction 7
	Organization of This Document 7
	See Also 7
Chapter 1	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
Chapter 2	Working with Nodes	25
	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
Chapter 3	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

C O N T E N T S

Figures, Tables, and Listings

Chapter 1	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

Chapter 2	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

Chapter 3	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

F I G U R E S , T A B L E S , A N D L I S T I N G S

I N T R O D U C T I O N

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 applicationsandservicestoretrieveinformationstoredindirectories. TheOpenDirectoryarchitectureconsists 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.

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.

Earlierdirectoryservices,suchas lookupd andNetInfo,tookthefirststepsinprovidingaccesstoconfiguration 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 continuestheevolutionofdirectoryservicesbyprovidingexpandedfunctionality. Forexample,OpenDirectory canwritedataaswellasreadit,andOpenDirectoryincludessupportforavarietyofauthenticationmethods.

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 LDAPandNetInfo. OpenDirectoryprovidesseamlessandautomaticintegrationofAppleComputer’sdirectory 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, andBonjour. TheAppleTalk,SLP,SMB,andBonjourOpenDirectoryplug-insdiscoverservicesthatareavailable on the local network. In Mac OS X, lookupd resolves DNS queries through UNIX function calls like gethostbyname(). TheOpenDirectoryLDAPplug-inprovidesinformationaboutusersandgroupsofusers. For information on writing your own Open Directory plug-in, see the document Open Directory Plug-ins.

Open Directory Overview

C H A P T E R 1

Concepts

Figure 1-1 Flow of an Open Directory request

Open Directory client

DirectoryServices daemon

Open Directory plug-ins

Request

Response

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 interface. Open Directory clients are responsible for interpreting the value of any particular attribute.

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

C H A P T E R 1

Concepts

Figure 1-2 An Open Directory request over a network

Open Directory client

DirectoryService daemon	Local System

LDAP plug-in		NetInfo plug-in

public.example.com	Publications	Remote System
		Remote System

private.example.com
Marketing	Engineering

Request

Response

Service-specific protocol

over the Internet or intranet

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

Thefirstpartofthenodename(LDAPv3 and NetInfo inthisexample)isthenameoftheplug-inthathandles that node.

Open Directory Overview

C H A P T E R 1

Concepts

Note:AnOpenDirectoryplug-inisnotrequiredtoreturninformationthatconformsexactlytotheinformation 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.

Searchnodesimplementsearchpolicies,whichareconfiguredbyadministratorsthroughtheDirectoryAccess application. Search nodes are easy for Open Directory applications to find and are guaranteed to always be available.

There are four search node types:

■authenticationsearchnode — Use this search node when you are looking for information that is needed to authenticate a user. Use the pattern matching constant eDSAuthenticationSearchNodeName to locatetheauthenticationsearchnode. Examplesofapplicationsthatusetheauthenticationsearchnode 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 performextremelyprecisesearchesandahighdegreeofcontroloverthetypeofinformationthatisreturned.

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.

Providers of services can define their own record types (known as native record types) and are encouraged topublishinformationaboutthem. DevelopersareencouragedtouseApple’sstandardrecordtypeswhenever possible.

12	Open Directory Overview

C H A P T E R 1

Concepts

Table 1-1	Standard record types
Constant		Description
kDSStdRecordTypeUsers		Standard record for describing users
kDSStdRecordTypeGroups		Standard record for describing groups
kDSStdRecordTypeMachines		Standard record for describing machines
kDSStdRecordTypeHosts		Standard record for describing hosts
kDSStdRecordTypePrinters		Standard record for describing printers
kDSStdRecordTypeNetworks		Standard record for describing records in the networks file
kDSStdRecordTypeServices		Standard record for describing records in the services file
kDSStdRecordTypeProtocols		Standard record for describing records in the protocols file
kDSStdRecordTypeRPC		Standard record for describing RPC records
kDSStdRecordTypePrintService		Standard records for describing print services
kDSStdRecordTypeConfig		Standard record for describing configuration records
kDSStdRecordTypeAFPServer		Standard record for describing AFP servers
kDSStdRecordTypeSMBServer		Standard record for describing SMB servers
kDSStdRecordTypeFTPServer		Standard record for describing FTP servers
kDSStdRecordTypeNFS		Standard record for describing NFS servers
kDSStdRecordTypeWebServer		Standard record for describing Web servers
kDSStdRecordTypeLDAPServer		Standard record for describing LDAP servers
kDSStdRecordTypeQTSServer		StandardrecordfordescribingQuickTimeStreamingservers
kDSStdRecordTypeMounts		Standard record for entries in the mount file
kDSStdRecordTypeComputers		Standard record for storing computer information
kDSStdRecordTypeComputerLists		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

C H A P T E R 1

Concepts

Constant	Description
kDSStdRecordTypePrintServiceUser	Standard record for storing quota usage for a user in the
	local node
kDSStdRecordTypeBootp	Standard record for storing bootp information
kDSStdRecordTypeNetDomains	Standard record for storing net domains
kDSStdRecordTypeEthernets	Standard record for storing Ethernets
kDSStdRecordTypeNetGroups	Standard record for storing net groups
kDSStdRecordTypeHostServices	Standard record for storing host services

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.

Table1-2listssomeofthestandardattributetypes. SeetheOpenDirectoryReferencesectionforthecomplete 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

Constant	Description
kDS1AttrPassword	Standard attribute for storing a password; commonly found in
	kDSStdRecordTypeUsers records
kDS1AttrUniqueID	Standard attribute for storing a unique ID; commonly found in
	kDSStdRecordTypeUsers records
kDS1AttrPrimaryGroupID	Standard attribute for storing a Primary Group ID; commonly found in
	kDSStdRecordTypeUsers and kDSStdRecordTypeGroups records
kDS1AttrComment	Standard attribute for storing a comment; commonly found in
	kDSStdRecordTypeGroup, kDSStdRecordTypeUsers,
	kDSStdRecordTypeComputers and other preset records
kDS1AttrUserShell	Standard attribute for storing the user’s shell; commonly found in
	kDSStdRecordTypeUsers records
kDS1AttrPrintService-	Standard attribute for print quota configuration or statistics; commonly
UserData	found in kDStdRecordTypePrintServiceUser records

14	Open Directory Overview

+ 30 hidden pages

Apple Mac Server OS X User Manual

Contents

Figures, Tables, and Listings

Introduction

Concepts

Open Directory Overview

Nodes

Search Policies and Search Nodes

Record Types

Standard Attribute Types