The complete article with graphics can be found in the June 1999 issue of 'System i Magazine'.
A Lightweight Directory Access Protocol (LDAP) server (referred to as the directory server) is available as part of IBM i. The server provides a network directory which can be accessed by network clients using the LDAP protocol. The directory can be used to store a wide variety of information, including:
- E-mail addresses. Several mail applications can access a LDAP directory as an address book.
- Application data. Several PC applications store user and configuration information in a LDAP directory.
- Network resources. Emerging standards will provide printer management using an LDAP directory to store information about printers capabilities, locations, etc..
This article is intended to help you get your directory server up and running. It describes how to create the initial server configuration and manage the server. It also describes how to control access of network clients to data in the directory.
You can find more information about the IBM i directory server at the IBM i Information Center website (http://www.ibm.com/systems/i/infocenter). Enter the Information Center, select Networking, then IBM i Directory Services (LDAP).
Terminology
First, lets define a few terms that you will need to know.
A directory server provides access to information using the LDAP protocol, a standard TCP/IP protocol.
The information in the directory is organized as a tree, known as a "directory information tree" (DIT). Depending on what you are using the directory for, the tree may be flat, it may follow your organization's structure, or you may create your own tree. An example of a simple directory tree follows:
The objects within the tree are referenced by their distinguished name (DN), where the names follow a syntax defined by X.500. Objects within the tree have a relative distinguished name (RDN), which identifies the object relative to it's parent, and a distinguished name, which uniquely identifies the object within the entire directory. RDNs are generally of the form "attribute=value", where attribute might be c (country), cn (common name), o (organization), etc., and the value is the name of the country, person, etc.. The DN is constructed by combining the RDNs of the object with those of its parents. For example, the DN of the root of the sample tree is "o=Deltawing, c=au" (organization = deltawing, country = Australia). The RDN of the president is "cn=John Smith" (common name = John Smith), while the DN of that directory object is "cn=John Smith, ou=Executives, o=Deltawing, c=au".
Each object in the directory consists of a set of attributes. For example, a person might have the following attributes:
object class:
common name:
mail:
ePerson
John Smith
jsmith@deltawing.au
The types of objects you can create (object class) and the attributes associated with the object class are defined by a set of schema files. Refer to the IBM i Information Center for more information about the directory schema.
A LDAP client can connect to a LDAP server in two ways: It can provide a DN and password that is known to the server -- the DN can be provided in other ways, for example, from a digital certificate. Or, it can use an unauthenticated connection (no DN is provided). For some applications, for example, looking up e-mail addresses on server located in an intranet, you may want to provide access to directory data using unauthenticated connections. For other applications, for example, changing data, you may want to require an authenticated connection, so that the server can control access based on the DN used to connect to the server.
Configuring a new directory server
Before you begin
In the following paragraphs we will describe how to configure a new directory server, the objects that comprise a server configuration, and how to populate the directory.
The directory server consists of two major components:
- a front-end, which handles LDAP client operations coming into the server over a TCP/IP connection
- a relational database back-end, which handles stores and retrieves directory objects from a relational database.
-
To configure or administer the directory server configuration, you must have All Object (*ALLOBJ), and IO System Configuration (*IOSYSCFG) authority.
Before you begin configuring your server you should be prepared to provide the following information:
- The name to use for the local relational database (RDBM), if the relational database on your system has never been configured for a local database. By default, the system name will be used.
- The name of the library to contain the database tables and other objects. This directory will be created if it does not exist, and it will be owned by the directory server user profile QDIRSRV. If your system has been configured with multiple auxiliary storage pools (ASPs), you will be asked which ASP the library should be created in.
- A distinguished name and password for the directory administrator. Directory clients connected to the server using this DN have authority to all objects in the directory. The administrator DN and password are part of the server configuration. You may also connect to the server using the DN of an object in the directory, for example, "cn=John Smith, ou=Executives, o=Deltawing, c=au".
- One or more "suffixes" which define the root(s) of the directory tree. For our example tree above, the suffix would be "o=Deltawing, c=au". Typically you would have only one suffix, but you may want to have more. Suffixes can be added to or removed from the configuration at a later time. One suffix is predefined by the server, "cn=localhost". This suffix will contain objects related to replication, if you set up a network where one server contains a copy (replica) of data on this server.
- Finally, you will be asked whether you want the server to be started automatically when TCP/IP is started on your system. You can change this value later.
Use the Operations Navigator Directory Server wizard
To configure the directory server, you must use Navigator for i. In Operations Navigator, navigate to the TCP/IP Servers folder for your system, select the Directory server, and select "Configure" from the context menu. This launches the directory server configuration wizard.
I've configured my server, now what?
At this point, you have an empty database library and some configuration objects stored in the Directory Services product library. The first time the server is started, or if you import data via LDIF utilities (more on these later), the database tables must be created. Depending on your system, this process could take several minutes or more before your server is ready to use.
You have several options for populating your directory:
- Publish from the system distribution directory
- Import data from a formatted file
- From an LDAP application or client
The System Distribution Directory
If you want to be able to look up system distribution directory information (for example, e-mail addresses) IBM i provides the capability to publish the System Distribution Directory to an LDAP server. Several PC mail applications support using a LDAP directory as an address book. Setting up publishing will be the topic of a future System i magazine article, but you can look in the IBM i Information Center, or, from Navigator for i, select "Properties" from the context menu of an IBM i system, and go to the "Directory Services" tab to get started. Also, see the QGLDSSDD (Synchronize System Distribution Directory to LDAP) API.
The LDAP Data Interchange Format (LDIF)
The LDAP standards define a standard data interchange format, the LDAP Data Interchange Format (LDIF). This defines a format for a text file that can be imported into the directory. For example:
dn: cn=John Smith, ou=Executives, o=Deltawing, c=AU
objectclass: top
objectclass: person
cn: John Smith
sn: Smith
mail: jsmith@deltawing.au
telephonenumber: 555-5555
You can write an application that creates such a file from an existing database or creates a file containing periodic updates. Refer to the IBM i Information Center for more information on LDIF files.
You can import a LDIF file into the directory using IBM i APIs (QgldImportLdif) or using Operations Navigator. After creating a LDIF file and storing it on your IBM i (it can be either a stream file or a source physical file), make sure your server is stopped, then select Tools -> LDIF Import from the Directory server context menu.
Write your own LDAP client application
Finally, you can develop your own LDAP client application to add, delete, or modify directory information. A LDAP client is available on the IBM i and a LDAP client is shipped with Operations Navigator. LDAP clients are available for many platforms from IBM and other sources.
Administering the Directory Server
In this section, we will describe administering the server itself; that is, the monitoring the server status, and starting or stopping the server. We'll also breifly describe some the server configuration parameters that can be changed. In the next section we will describe how to administer the directory itself; specifically, controlling access to the directory data.
The entire user interface for administering the server is in Operations Navigator. From a green screen, you can start and stop the server (STRTCPSVR, ENDTCPSVR commands) and monitor the server job (WRKACTJOB, WRKJOB commands).
The following context menu actions are available from Operations Navigator for administering the server (if the server has not been configured, "Configure" will be the only action shown):
- Start or stop the server
- Status. This menu action displays the directory server status dialog, shown below. From this dialog you can monitor the server status and activity.
- Server jobs. This menu action displays the directory server job log. This is most useful when either: the server fails to start (or ends abnormally); or, clients are receiving "operations error" error codes from the server.
Tip: If the server is running, "Server jobs" displays the active server job. If the server is not running, spooled job logs are shown. You can use the "Include" menu item on the job list menu to filter which jobs are shown. From a green screen interface, you can use WRKJOB or WRKACTJOB, specifying JOB(QDIRSRV) to get a list of directory server jobs. - Properties. This menu item displays the server configuration.
-
From Operations Navigator, there are additional server properties you can configure, including things such as: replication, using SSL, performance tuning, etc.. These are briefly described below. Look in the IBM i Information Center. and in Operations Navigator help for each of the property pages, for additional information.
From the "General" property page, you can do such things as:
- Change the administrator's DN or password.
- Put the server into read-only mode -- useful, for example, when preparing to set up a replica, to allow access to directory data, but without allowing change.
- Configure a "referral" - another directory server that might contain data not located on the current server. LDAP clients can be configured to retry requests using the referral.
- Configure the server as a master server or a replica server.
From the "Suffixes" page, you can change the list of suffixes recognized by the server. You probably won't be doing this very often.
From the "Replicas" page, you can identify other servers that you have configured to contain copies of data. This is useful if your original server handles a lot of requests, or if you want to ensure that directory data remains accessible when the master server is down. The list of replica servers is stored in the directory, so you'll want the master server running before you try to define any replicas.
From the "Network" page, you can do such things as:
- Set up your server to support SSL connections.
- Change port numbers.
From the "Performance" page, you can define limits on searches, configure such things as the maximum number of connections that can be open at a time, or define database indexes that should be created for attributes frequently used in directory searches (see the terminology discussion).
Administering your directory data
Administering the directory contents falls broadly into two categories:
- managing the actual directory data
- controlling access to the directory
Managing the actual content is typically highly application dependent. However, there is a set of utilities that provide some capability for viewing, changing, deleting and renaming directory objects. These utilities are: ldapadd, ldapmodify, ldapdelete, ldapmodify, ldapmodrdn, and ldapsearch. A set of these utilities are useable from the IBM i shell (QSH), and are provided in the "/usr/bin" directory. Versions of these utilities for Windows 95 and Windows NT are provided in "/QIBM/ProdData/OS400/DirSrv/UserTools/Windows/bin" directory. These utilities are documented in the IBM i Information Center.
Since the directory server is a network directory, not an IBM i directory, access to the directory is not based on IBM i authority mechanisms. Instead, the directory server defines its own authority model. Access to directory data is determined by the DN used to connect to the server. You can connect to the server anonymously, or specify a DN and password. The DN and password are managed by the server; they are not a IBM i user name and password. Additionally, a DN can be a member of a group and that group given authority to directory objects. All DNs, and anonymous connections, are members of a special group, " cn=anybody".
An access control list (ACL) is defined for each directory object, or the object can inherit its ACL from its parent. The ACL defines an owner, object authority, and attribute authority. The owner has all access to an object. Object authority specifies the authority other DNs have to create lower level objects, and to delete this object. Attribute authority defines the authority of other DNs to access the attribute values (i.e. the email address, public key, etc..). Attributes are classified into "access classes" (this is defined in the schema). You define authority to attributes based on:
- their access class -- one of normal, sensitive, or critical
- and the type of operation they can perform on those attributes -- read, search, compare (think of this collection being read access), and write.
Consider the following example, describing access to the object "cn=John Smith, ou=Executives,o=Deltawing,c=au":
Owner:
ACL for:
cn=anybody
cn=administrators, o=Deltawing,c=au
cn=this (ownership inherited from "ou=Executives,...")
(ACL also inherited from "ou=Executives,...")
object: none
normal: read, search, compare
sensitive: none
critical: none
object: add, delete
normal: read, write, search, compare
sensitive: read, write, search, compare
critical: write
Further for this exercise, lets assume that the following attributes are defined for "cn=John Smith":
| Attribute | Access class |
|---|---|
| cn (commonname) | normal |
| sn (surname) | normal |
| mail (e-mail address) | normal |
| userpassword | critical |
The ACL information is inherited from a parent object, "ou=Executives, o=Deltawing, c=au". So we didn't have to specify authority when we created this object.
The object is owned by "cn=this". "cn=this" is a special DN that translates into "this object". So, the object owner is "cn=John Smith, ou=Executives, o=Deltawing, c=au". If you connect to the server as "cn=John Smith, ou=Executives, o=Deltawing, c=au." from an LDAP-enabled application, you can delete the object, create lower level objects, and retrieve or modify all attributes.
"cn=anybody" specifies the public authority, including anonymous binds. You can bind to the server anonymously (by not providing a DN) and retrieve the cn, sn, and mail attributes, but not the userpassword. You cannot delete the object.
"cn=Administrators,..." is an accessgroup. An accessgroup is a directory object that can be used in ACLs. The group contains a list of DNs that are members of the group. Members of the "cn=Administrators,..." group can delete this object, and create lower level objects. They can retrieve or modify all normal and sensitive attributes. Also, in case John Smith forgets his password, they can change it. However, they cannot retrieve his password.
When you first create your directory, all objects will inherit their authority from the server defaults: Objects are owned by the administrator DN; the group "cn=anybody" has read access to normal attributes; only the administrator DN has authority to update data.
From Operations Navigator, you can work with groups or object authority:
Conclusion
We've talked a little about what an LDAP server is, and given you the information you need to get a directory server up and running on your IBM i, as well as perform some basic server administration tasks. Next month, we'll talk about publishing the System Distribution Directory, and other system information, to your server.
We're here to help
Easy ways to get the answers you need.
or call us at
1-866-883-8901
Priority code:
101AR13W