Previous Contents Index Next |
Setup Util Programmer's Guide |
Chapter 8 Interacting with the Directory Server
This chapter shows you how to use the Setup Util to work with data stored in an LDAP Directory Server. It contains the following sections:
`Overview: Setup Util and the Directory Server
One of the many useful features of the Directory Server is its ability to store configuration data. By reducing the number and size of configuration files, the Directory Server has helped centralize and simplify server management.
This section explains how configuration information is stored in the Directory Server.
Directory Organization
Depending on how it is set up, Directory Server can contain user data, configuration data, or both. While there are many different ways to organize user data, configuration settings are always stored in the branch of the directory beginning with cn=NetscapeRoot. The hierarchical structure beneath this entry contains configurable and non-configurable information about installed software. Often, the whole branch is collectively referred to as the configuration directory.
When working with Console, the configuration directory is logically organized into administration domains, hosts, server groups, and products. An administration domain can contain multiple hosts, each of which can contain one or more server groups (Windows NT machines can only support one server group). Each server group has one administration server and one or more servers and server instances.
In more generic terms, an administration domain is a collection of hosts. A server group is a server root and a server is a product installed in a server root.
By default, full access to the configuration directory is only granted to members of the Directory Administrators group.
Installed Software Instance Entries
When a user first installs the Directory Server, a complete cn=NetscapeRoot branch is created. Whenever the user installs an additional product, the Common Install Shell adds an Installed Software Instance Entry (ISIE) to the branch. This establishes a location in which to store settings for a specific server.
Each product in a server root has its own ISIE. Like all entries in the directory, ISIEs are represented by DNs. For example, an Enterprise Server ISIE might have the following DN:
cn=Enterprise Server, cn=Server Group, cn=host.siroe.com, ou=siroe.com, o=NetscapeRoot
When a server is successfully installed, the Common Install Shell registers an ISIE in the configuration directory. When the server is upgraded, the Shell updates the ISIE to reflect the new version.
A number of unique object classes represent the different elements of the configuration directory. Each host machine that contains software managed by Console is represented by an entry of the object class prefixHost. Individual server group entries have an object class of nsAdminGroup and each ISIE is of the object class prefixApplication.
Server Instance Entries
Server instances need identities in order to authenticate to the Directory Server and perform privileged operations such as creating and updating entries. To accomplish this, every server instance is represented by a Server Instance Entry (SIE). This is an LDAP entry that contains configuration and state information for a specific server instance. During installation, you can create an SIE using the setupCreateSIE function of the Setup Util. For information on this function, see Appendix A.
An SIE's DN is constructed by prepending the instance name to the appropriate ISIE. For example, an Enterprise Server SIE might have the following DN:
cn=https-webmachine, cn=Enterprise Server, cn=Server Group, cn=host.siroe.com, ou=siroe.com, o=NetscapeRoot
An SIE typically has two subentries: Tasks and Configuration. Tasks contains information about the various functions that a server instance can perform while Configuration stores the instance's settings.
Preferences
Servers often need to share configuration and state information among themselves and with external applications. At the same time, there are some settings that only pertain to a specific set of servers. The Directory Server manages this situation through the use of individual, host, shared, and global preferences.
Individual preferences are configuration settings for a single server instance.
Host preferences are shared across a single host machine.
Shared preferences are configuration settings that are shared across all instances of a particular type of server.
Global preferences are configuration settings that apply to all the installing products. The following examples illustrate the four different types of preferences:
When a user changes the log settings of a single Messaging Server instance, he is modifying an individual preference.
When he requires client authentication for all servers on a single machine, he is changing a host preference.
When he lowers the IMAP disk quota across six Messaging Server instances, he is modifying a shared preference.
When he changes the minimum password length across all servers, he is modifying a global preference. A set of precedence rules apply to these preferences. In general, individual preferences override shared preferences which, in turn, override global preferences.
A server should search for its configuration information in the following order:
In addition, a server should store a minimum set of preferences locally. It should use these if the Directory Server is not available.
There are many other variations on preferences and their applicability in different situations. For more information, see the Console SDK Programmer's Guide.
Access Control
By default, the Setup Util applies the following access rules to servers that it installs:
A server group is only visible to SIEs that belong to it.
An SIE has all access rights to itself and everything below it. In addition, the Configuration Administrator has all access rights to the entire cn=NetscapeRoot branch.
For more information on the Configuration Administrator and Access Control, see the Directory Server Administrator's Guide.
Importing Schema and LDIF Files
There are a number of Setup Util features designed to help you store configuration data in the Directory Server. These include information file directives as well as API functions for importing schema and LDIF files.
Using Information File Directives
The easiest way to import schema and LDIF files into the Directory Server is to use information file directives.
Create a schema file containing the attribute types and object classes you want to add to the directory. This file should be in the same format as the configuration files in slapd-<host>/config.
For more information on creating a schema file, see the Directory Server documentation.
Save your schema file in the same directory as your package information file.
In your package information file, add the updateSchema directive and provide the name of your schema file as a value.
Create an LDIF file containing the information you want to add to the directory.
For more information on creating an LDIF file, see the Directory Server documentation.
Save your LDIF file in the same directory as your package information file.
In your package information file, add the updateLdif directive and provide the name of your LDIF file as a value.
Using API Functions
You can use the Setup Util API to import schema and LDIF entries into the Directory Server. When importing schema, you can use a file containing schema or you can code specific entries into your post-installation program. When importing LDIF entries, you must use a file.
Create a schema file containing the attribute types and object classes you want to add to the directory. This file should be in the same format as the configuration files in slapd-<host>/config. For example, Directory Server uses the following schema file:
# Used by Directory Server
attribute nsSecureServerPort cis
objectclass prefixDirectoryServer
oid 2.16.840.1.113730.3.2.23
requires
objectclass
objectclass nsDirectoryServer
requires
objectclass,
nsServerID
allows
serverHostName,
nsServerPort,
nsSecureServerPort,
nsBindPassword,
nsBindDN,
nsBaseDN
For more information on creating a schema file, see the Directory Server documentation.
Save your schema file in the same directory as your package information file.
Add an include statement for ldapu.h to your post-installation program.
In your post-installation program, call the insertSchemaFile function and provide the name of your schema file as a value. For more information on the setupInsertSchemaFile function, see Chapter 13 "Setupapi.h Library Reference."
Add an include statement for ldapu.h to your post-installation program.
In your post-installation program, call the insertSchemaEntries function. For more information on the setupInsertSchemaEntries function, see Chapter 13 "Setupapi.h Library Reference."
Create an LDIF file containing the information you want to add to the directory.
For more information on creating an LDIF file, see the Directory Server documentation.
Save your LDIF file in the same directory as your post-installation program.
Add an include statement for ldapu.h to your post-installation program.
In your post-installation program, call the insertLdifEntries function and specify your LDIF file.
For more information on the setupInsertLdifEntries function, see Chapter 13 "Setupapi.h Library Reference."
Previous Contents Index Next
Copyright (C) 2005 Red Hat, Inc. All rights reserved.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/
Last Updated September 21, 2001