Understanding lookupd

An additional process called lookupd interacts with DirectoryService and provides some similar services for system-level requests. The lookupd process uses agents that are extensions to the lookupd code to retrieve information about users, groups, and domain name system (DNS) configuration. Each agent is designed to locate a particular type of information. Command-line utilities such as ls and any network applications requiring DNS resolution use lookupd to retrieve DNS information.

The following agents retrieve information for directory services:

• CacheAgent: The cache agent stores retrieved values; this improves performance by minimizing trips to other data sources.

• DNSAgent: The DNS agent queries a DNS server for host resolution, using the currently configured DNS server information.

• FFAgent: The flat file agent queries traditional UNIX flat files in the file system.

• NIAgent: The NetInfo agent queries the local NetInfo database and its parents.

• DSAgent: The directory-service agent queries DirectoryService.

You can configure which agents are used and the order in which they are searched, although the cache agent is typically searched first. Also, you can use lookupd to check what information is being retrieved from the DirectoryService process. These are both good troubleshooting steps when attempting to locate a problem with directory services not looking in the proper place.

Another point to consider is that the lookupd process can be configured to work with DirectoryService using DSAgent. Any process that uses lookupd would also search the DSAgent and, therefore, DirectoryService.

Because lookupd has a DNS agent, it is the DNS resolver for Mac OS X. It is, therefore, an acceptable tool for performing DNS lookups.

Comparing DirectoryService and lookupd

DirectoryService and lookupd are similar in that both have an architecture that allows for flexible configuration of various data stores. There are, however, significant differences between the two:

• The UNIX-based system calls of Mac OS X rely on lookupd to provide access to data stores, whereas native applications use the set programming functions implemented with DirectoryService.

• DirectoryService provides read and write support, whereas lookupd is read only.

• DirectoryService supports many authentication methods; lookupd only returns results for predefined attribute schemes.

• DirectoryService does not provide DNS resolution, a critical service to Mac OS X. This function is provided by lookupd.

These differences are summarized in the following table:

DirectoryService	lookupd
Used by native applications	Used by standard system calls
Read and write support	Read-only support
Full support for many authentication methods	Does not provide authentication support
No DNS support	Used to resolve DNS

Identifying lookupd Agents

Because different types of information might be stored in different places, you can configure a separate set of agents and a separate lookup order for each category of agents. When lookupd searches for user information, it looks in the cache first (using the CacheAgent), then the NetInfo database (using the NIAgent), and then DirectoryService (using the DSAgent). When lookupd searches for host information, it looks in the cache first, then the /etc/hosts file (using the FFAgent), then the DNS server (using the DNSAgent), then the NetInfo database, and, finally, the DirectoryService process.

The lookupd process has a predefined default configuration. No configuration files are necessary. There are two methods for changing the configuration of lookupd:

• Create entries in the local NetInfo database.

• Create flat files with properly formatted configuration information.

While global settings affect the process as a whole, you can add further configuration information for each agent or category of agents. For example, the global timeout value for lookupd might be set to 30 seconds, but you could set the timeout value for the DNSAgent to be 15 seconds. The more specific settings will override the global values.

To determine the configuration of lookupd, type lookupd configuration at the command line.

To change the values in the NetInfo database for lookupd and its agents, you can use Workgroup Manager (running locally) or through manual configuration files. Refer to the man page for lookupd for more information.

1.	Open Workgroup Manager.
2.	Choose Server > View Directories.
3.	Click the Lock button and authenticate so that you can edit the local NetInfo database.
4.	Click the Inspector button next to the Users, Groups, and Computers button.
5.	Choose Locations from the Record Types pop-up menu.
6.	Choose Server > New Record to create a new locations record.
7.	Set the name of the new record to lookupd.
8.	Within the lookupd record, create an attribute for each of the categories you want to edit. For example, to change how lookupd searches for users, click the New Attribute button, type users in the Attribute Name field, and click OK.
9.	Within each attribute for the category you want to edit, define the property and the value. For example, to change the lookup order for users, create a new property called LookupOrder. For the values, enter the agent names in the order you want them used. To change the time agents, wait for a response, create a new property called Timeout, and give the value in seconds.

Working With lookupd and PAM

Although lookupd is able to do the work of identification, it cannot actually authenticate the user account. To solve this, Mac OS X provides a pluggable authentication module (PAM) that accesses the security framework. PAM is a set of libraries that handle authentication tasks for applicationsin this case, BDS utilities and UNIX system calls. The primary purpose of PAM is to provide a layer of abstraction between the open-source system calls and the security framework that works directly with DirectoryService. The configuration for PAM-enabled services are stored in /etc/pam.d. The following figure illustrates how Mac OS X leverages a PAM to act on behalf of the requestor when talking to the security framework.

Examples of an ssh Login

There are two basic ways to do ssh login, depending on whether the user is in the NetInfo database or in BDS flat files. Both of these examples illustrate how the lookup process handles queries to the user data, depending on where that data is stored.

ssh Login of a User in the NetInfo Database

The lookupd process is used when a user logs in via the command line, referencing getpwent, getpwnam, and other various system calls, depending on the specific command, which can be ftp, ssh, su, or sudo. The login process may or may not use DirectoryService, depending on where the user record is stored and in what order the agents are used.

In this first example, the user record is located in the local NetInfo database. From a remote computer, the user (Warren) uses ssh to access a Mac OS X computer, which then uses lookupd to retrieve the user record. To perform the search, lookupd agents query data stores. First the cache is checked. If the user record is not found in the cache, the NetInfo agent queries the local NetInfo database. The record is found and returned to ssh, and the user is authenticated using PAM. DirectoryService is not used for this request.

ssh Login of a User in BSD Flat Files

From a remote computer, the user (Tina) uses ssh to access a Mac OS X computer, which then uses lookupd to retrieve the user record. To perform the search, lookupd agents query data stores. First the cache is checked. If the user record is not found in the cache, the NetInfo agent queries the local NetInfo database. When the record is not found in the local NetInfo database, the DSAgent queries the DirectoryService process. Provided DirectoryService is configured to search the BDS flat files (along with the preceding default search in the NetInfo database) for authentication, the record is found and returned to ssh, and the account is authenticated with PAM.

An alternative to this somewhat lengthy process would be to reconfigure lookupd to search the flat files using the FFAgent. This would require you to create a lookup order for lookupd in either a configuration file or in the NetInfo database.

Viewing the Current Configuration of lookupd

When you use the lookupd command to retrieve directory-service information, it is helpful to understand how lookupd is configured so that you know where the information is coming from.

1.	Log in as Apple Admin.
2.	Open Terminal.
3.	Display the current configuration for lookupd by typing lookupd -configuration. Notice that the configuration information is broken into sections, each ending with "_config_name:" and the type of configuration to which the preceding settings apply. The Global Configuration settings apply to all lookupd requests, unless a specific request type has a setting specified, in which case the global value is overridden. DNS represents the DNS agent, FF the flat file agent, NI the NetInfo agent, and DS the DirectoryService agent.
4.	Query the Directory Domain with lookupd by using the -q option with the lookupd command, which can query the currently running instance of lookupd. To do so, type lookupd -q category -a key value where category is the category of request being made (user, group, service, etc.), key is the record attribute being used to search, and value is the value being looked for in the key.
5.	In Terminal, test the resolution of user names by typing lookupd -q user -a name apple. This returns the user records that have a short name of apple. Since there is only one user account with the short name apple, only one user record will be displayed.
6.	Locate the authentication_authority, generateduid, and passwd attributes. They will look similar to the following: authentication_authority: ;ShadowHash; generateduid: A2B6A2A-1F56-11B9-8A22-0003935455BC passwd: ******** The authentication_authority attribute specifies the type of password used (basic or shadow). If the user account was created by a prior version of Mac OS X, the authentication_authority would be set to Basic and the passwd attribute would contain an encrypted version of the password. When authentication_authority is set to ShadowHash, the generateduid attribute contains a unique ID for the user. A file in /var/db/shadow/hash with a name that matches the generateduid value contains the user's encrypted password. (The passwd value is set to ******** to indicate that it is not used.) If the authentication_authority attribute is blank, then a crypt password is used.
7.	Switch to the root user by typing sudo s.
8.	Navigate to /var/db/shadow/hash.
9.	List the contents of the hash folder. For each user account set to use shadow hash passwords, there is a file named with the user account's generated user ID (GUID).
10.	Display the contents of the file with the name that matches the GUID for the Apple Admin that you looked up in step 2. The file contains a shadow hash of the user's password.

Running an Interactive Session With lookupd

By using the -d option with the lookupd command, you can begin an interactive session of lookupd. Using this option creates a second lookupd process on the machine, separate from the one that is normally running. This enables you to test lookupd settings interactively, without affecting the entire machine.

1.	At the command prompt, type lookupd -d. You will be presented with three lines of output similar to the following: lookupd version 324.5 (root 2005.05.13 00:28:44 UTC) Enter command name, "help", or "quit" to exit > Notice that the command prompt has changed. The > prompt indicates that you are now in a session with lookupd, and not at the command-line shell.
2.	At the prompt, type ? to get a listing of all commands. You will see a listing of all the commands you can enter in the lookupd prompt. All the queries that lookupd performs are represented here.
3.	To test resolution of host names, at the prompt (>) type userWithName and press the Tab key. The interactive lookupd session supports command completion. Press the Tab key or Space bar instead of the colon. This will fill in the colon and enable you to type in the argument.
4.	Look up a user by typing userWithName: apple. The result is a list of attributes for Apple's user account. Note the lookupd agent used. In this instance, it is the NIAgent.
5.	Type q to quit the lookupd interactive session and quit the Terminal application.