Networking AS/400 Directory Services (LDAP)

Networking AS/400 Directory Services (LDAP)

 Copyright International Business Machines Corporation 1998,2000. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Part 1. Directory Services (LDAP) . . 1
Chapter 1. Whats new for V4R5 . . . . 3 Chapter 2. Print this topic . . . . . . . 5 Chapter 3. Getting started with AS/400 Directory Services . . . . . . . . . . 7
| | | | | |
LDAP basics . . . . . . . . . . . . . . 8 Example of using AS/400 Directory Services . . 11 Considerations for using LDAP V2 with LDAP V3 . . . . . . . . . . . . . . . . 11 Planning your LDAP directory server . . . . . 12 Migrating to V4R5 from an earlier release of AS/400 Directory Services . . . . . . . . . . . . 12 Migrating from V4R3 AS/400 Directory Services to a later release . . . . . . . . . . . . 13 Installing and Configuring AS/400 Directory Services . . . . . . . . . . . . . . . 14 Installing AS/400 Directory Services . . . . . 14 Configuring the LDAP directory server . . . . 14 Uninstalling AS/400 Directory Services . . . . 16 The IBM SecureWay Directory Management Tool . . 16 Working with ACL Groups . . . . . . . . 29 Tracking changes to the LDAP directory . . . . . 29 Adjusting performance of the LDAP directory server 30

Chapter 5. AS/400 Directory Services concepts and reference information . . 31

LDAP access control lists (ACLs) . . . . . . Access control list (ACL) attributes . . . . LDAP Directory Interchange Format . . . . . National language support (NLS) considerations . Ownership of LDAP directory objects . . . . LDAP directory referrals . . . . . . . . . Replica LDAP directory servers. . . . . . . Using Secure Sockets Layer (SSL) security with the LDAP directory server. . . . . . . . . . AS/400 Directory Services and OS/400 journaling support. . . . . . . . . . . . . . . . . . . . . . 31 32 36 39 39 39 40

. 40 . 41

Chapter 6. LDAP command line utilities 43

ldapmodify and ldapadd utilities . . . . . . Examples: ldapmodify and ldapadd . . . . ldapdelete utility . . . . . . . . . . . Example: ldapdelete . . . . . . . . . ldapsearch utility . . . . . . . . . . . Examples: ldapsearch . . . . . . . . . ldapmodrdn utility . . . . . . . . . . . Example: ldapmodrdn . . . . . . . . . Notes about using SSL with the LDAP command line utilities . . . . . . . . . . . . . . . . . . . . . 43 45 46 48 48 51 54 55

Chapter 4. Administering the LDAP directory server . . . . . . . . . . . 19

Starting the LDAP directory server . . . . . Stopping the LDAP directory server . . . . . Checking the status of the directory server . . . Checking jobs on the LDAP directory server . . Moving LDAP directory data between systems . Importing an LDIF file . . . . . . . . Exporting an LDIF file. . . . . . . . . Setting up a new replica of the directory server Publishing AS/400 information to the directory server . . . . . . . . . . . . . . Specifying a server for directory referrals . . . Adding suffixes to the LDAP directory server . . Removing suffixes from the directory server . . Saving and restoring AS/400 Directory Services information . . . . . . . . . . . . . Managing ownership and access of directory data Working with the ownership properties of directory objects . . . . . . . . . . . Working with the Access Control Lists (ACLs). . . . . . . . 19 20 20 20 20 21 21 21 25 27 27 27

. 56

Chapter 7. Troubleshooting AS/400 Directory Services . . . . . . . . . . 57

Basic troubleshooting procedure for AS/400 Directory Services . . . . . . . . . . . Monitoring errors and access with the AS/400 Directory Services job log. . . . . . . . Common LDAP client errors . . . . . . . ldap_search: Timelimit exceeded . . . . . [Failing LDAP operation]: Operations error . . ldap_bind: No such object . . . . . . . ldap_bind: Inappropriate authentication . . . [Failing LDAP operation]: Insufficient access . [AS/400 System]: A remote host refused an attempted connect operation. . . . . . . [AS/400 System]: Failed to connect to ssl server . 57 . . . . . . . 58 58 59 59 59 59 59

. . . .

. 28 28 . 28 . 28

. 60 60

Copyright IBM Corp. 1998,2000

iii

iv

Networking AS/400 Directory Services (LDAP)

Part 1. Directory Services (LDAP)

AS/400 Directory Services provides a Lightweight Directory Access Protocol (LDAP) server on AS/400. LDAP runs over Transmission Control Protocol/Internet Protocol (TCP/IP), and is gaining popularity as a directory service for both Internet and non-Internet applications. If you are already familiar with AS/400 Directory Services, you might want to first read start with whats new for this release. If you want, you can print or display a PDF version of the AS/400 Directory Services information. The following topics introduce AS/400 Directory Services and provide you with information to help you administer the LDAP server on your AS/400: v Chapter 3. Getting started with AS/400 Directory Services on page 7 v Chapter 4. Administering the LDAP directory server on page 19 v Chapter 5. AS/400 Directory Services concepts and reference information on page 31 v Chapter 6. LDAP command line utilities on page 43 v Chapter 7. Troubleshooting AS/400 Directory Services on page 57 | | | | For additional information about AS/400 Directory Services, visit the AS/400 Directory Services home page .

The LDAP server that AS/400 Directory Services provides is an IBM SecureWay Directory .

Copyright IBM Corp. 1998,2000

Networking AS/400 Directory Services (LDAP)

Chapter 1. Whats new for V4R5

| | | | | | | | | | | | | | | | | | | | | | | | | | AS/400 Directory Services has the following enhancements and new features for V4R5: v The OS/400 LDAP directory server is now based on LDAP Version 3. v The LDAP directory server and LDAP client now support data in the UTF-8 format. v There is now a change log for the LDAP directory server that can record all changes made to directory data. v The Windows 95 and Windows NT LDAP client shipped with AS/400 Directory Services now includes the IBM SecureWay Directory Management Tool, which provides a graphical user interface for working with the LDAP directory. v You now specify server names with the more common uniform resource locater (URL) format, rather than with DNS names. This includes the way servers are specified in LDAP referrals, as well as external server references in LDIF files. v LDIF files have an improved format. v You now use client authentication to add more security to SSL connections to your LDAP directory server. v You can now use access control lists (ACLs) to grant authority to directory objects to any users that bind to the LDAP directory server with non-anonymous connections. v AS/400 Directory Services now supports both UTC Time and Generalized Time. UTC Time uses two digits to store the year, and is not considered Y2K safe, but is included for historical reasons. Generalized Time uses four digits for the year and is considered Y2K safe. v The alias support has been enhanced. Aliases no longer have to be leaf nodes, and can be combined with other objectclasses. V4R4 enhancements: AS/400 Directory Services had the following enhancements and new features for V4R4: v You can view a list of jobs running on the server. v You can publish computer information from AS/400 to the directory server. v When you publish AS/400 user information to the directory server, AS/400 Directory Services automatically exports entries from the system distribution directory to the LDAP directory v Directory objects can now have multiple owners, and can also own themselves. v The directory server schema now includes support for integer and boolean attributes. v You can use a * character for a requested attribute value. By using the * character, you can retrieve all non-operational attributes. This makes retrieving both operational and non-operational attributes in one search much easier. To do this, you would list in your search the operational attributes you wanted information for, plus the *. v You can use aliases with the directory server.

Copyright IBM Corp. 1998,2000

Networking AS/400 Directory Services (LDAP)

Chapter 2. Print this topic

You can view or download a PDF version of this document for viewing or printing. You must have Adobe Acrobat Reader installed to view PDF files. You can download a copy from http://www.adobe.com/prodindex/acrobat/readstep.html .

To view or download the PDF version, select AS/400 Directory Services (LDAP) (about 475 KB or 65 pages). To 1. 2. 3. 4. 5. save a PDF on your workstation for viewing or printing: Open the PDF in your browser (click the link above). In the menu of your browser, click File. Click Save As... Navigate to the directory in which you would like to save the PDF. Click Save.

Copyright IBM Corp. 1998,2000

Networking AS/400 Directory Services (LDAP)

Chapter 3. Getting started with AS/400 Directory Services

AS/400 Directory Services provides a Lightweight Directory Access Protocol (LDAP) server on AS/400. LDAP runs over Transmission Control Protocol/Internet Protocol (TCP/IP), and is gaining popularity as a directory service for both Internet and non-Internet applications. You perform most setup and administering tasks of the LDAP directory server on AS/400 through the graphical user interface (GUI) of AS/400 Operations Navigator. To administer AS/400 Directory Services, you must have Operations Navigator installed on a PC that is connected to your AS/400. You can use AS/400 Directory Services with LDAP-enabled applications, such as mail applications that look up e-mail addresses from LDAP servers. Besides the LDAP server, AS/400 Directory Services also includes: v An AS/400-based LDAP client. This client includes a set of application program interfaces (APIs) that you can use in OS/400 programs to create your own client applications. For information about these APIs, see the Directory Services topic under Programming in the AS/400 Information Center. v A Windows 95 and Windows NT LDAP client. This client includes the IBM SecureWay Directory Management Tool, which provides you with a graphical user interface for managing directory content. The Windows LDAP client also includes a set of application programming interfaces (APIs) that you can use in your own applications. For more information about these APIs, see the IBM Lightweight Directory Access Protocol (LDAP) topic under Client Access Express in the AS/400 Information Center. If you have used AS/400 Directory Services with an earlier release of OS/400, see Migrating to V4R5 from an earlier release of AS/400 Directory Services on page 12. For an introduction to LDAP, see LDAP basics on page 8. Even if you have used LDAP servers on other platforms, you should take a few minutes to read this topic, as it contains some AS/400-specific information. When you have familiarized yourself with this basic information, proceed to Planning your LDAP directory server on page 12. For information on installing and configuring your directory server, see Installing and Configuring AS/400 Directory Services on page 14. | | | | | | | | | | This documentation provides an overview of LDAP, and concentrates specifically on managing the LDAP directory server on AS/400. For additional and more comprehensive LDAP information, consult LDAP references such as the following: v LDAP Implementation Cookbook .

| | | | | | | |

. v Understanding LDAP v LDAP: Programming Directory-enabled Applications with Lightweight Directory Access Protocol by Tim Howes and Mark Smith. v Understanding and Deploying LDAP Directory Services by Mark C. Smith, Gordon S. Good, and Tim Howes. v
Copyright IBM Corp. 1998,2000

Note: Some of the material contained in this document is a derivative of LDAP documentation provided by the University of Michigan. Copyright 1992-1996, Regents of the University of Michigan, All Rights Reserved.

LDAP basics
The Lightweight Directory Access Protocol (LDAP) is a directory service protocol that runs over Transmission Control Protocol/Internet Protocol (TCP/IP). LDAP version 2 is formally defined in Internet Engineering Task Force (IETF) Request for Comments (RFC) 1777, Lightweight Directory Access Protocol. LDAP version 3 is formally defined in IETF RFC 2251, Lightweight Directory Access Protocol (v3).You can view these RFCs on the Internet at the following URL:

http://www.ietf.org The LDAP directory service follows a client/server model. One or more LDAP servers contain the directory data. An LDAP client connects to an LDAP Server and makes a request. The server responds with a reply, or with a pointer (a referral) to another LDAP server. Uses of LDAP: Because LDAP is a directory service, rather than a database, the information in an LDAP directory is usually descriptive, attribute-based information. LDAP users generally read the information in the directory much more often than they change it. Updates are typically simple all-or-nothing changes. Common uses of LDAP directories include online telephone directories and e-mail directories. LDAP directory structure: The LDAP directory service model is based on entries (which are also referred to as objects). Each entry consists of one or more attributes, such as a name or address, and a type. The types typically consist of mnemonic strings, such as cn for common name or mail for e-mail address. The example directory in Figure 1 on page 10 shows an entry for Tim Jones that includes mail and telephoneNumber attributes. Some other possible attributes include fax, title, sn (for surname), and jpegPhoto. Each directory has a schema, which is a set of rules that determine the structure and contents of the directory. You should use the IBM SecureWay Directory Management Tool (DMT) to edit the schema files for your LDAP server. After you install AS/400 Directory Services, the files are located on your AS/400 at /QIBM/UserData/OS400/DirSrv. Note: Original copies of the default schema files are located at /QIBM/ProdData/OS400/DirSrv. If you need to replace the files in the UserData directory, you can copy these files to that directory. Each directory entry has a special attribute called objectClass. This attribute controls which attributes are required and allowed in an entry. In other words, the values of the objectClass attribute determine the schema rules the entry must obey. Each directory entry also has the following operational attributes, which the LDAP server automatically maintains:

Networking AS/400 Directory Services (LDAP)

v CreatorsName, which contains the bind DN used when creating the entry. v CreateTimestamp, which contains the time at which the entry was created. v modifiersName, which contains the bind DN used when the entry was last modified (initially this is the same as CreatorsName). v modifyTimestamp, which contains the time at which the entry was last modified (initially this is the same as CreateTimestamp). | | | | | | | | | | Traditionally, LDAP directory entries are arranged in a hierarchical structure that reflects political, geographic, or organizational boundaries (see Figure 1 on page 10). Entries that represent countries appear at the top of the hierarchy. Entries representing states or national organizations occupy the second level down in the hierarchy. The entries below that can then represent people, organizational units, printers, documents, or other items. You are not limited to the traditional hierarchy when structuring your directory. The domain component structure, for example, is gaining popularity. With this structure, entries are composed of the parts of TCP/IP domain names. For example, dc=ibm,dc=com may be preferable to o=ibm,c=us. LDAP refers to entries with Distinguished Names (DNs). Distinguished names consist of the name of the entry itself as well as the names, in order from bottom to top, of the objects above it in the directory. For example, the complete DN for the entry in the bottom left corner of Figure 1 on page 10 is cn=Tim Jones, o=IBM, c=US. Each entry has at least one attribute that is used to name the entry. This naming attribute is called the Relative Distinguished Name (RDN) of the entry. The entry above a given RDN is called its parent Distinguished Name. In the example above, cn=Tim Jones names the entry, so it is the RDN. o=IBM, c=US is the parent DN for the cn=Tim Jones. To give an LDAP server the capability to manage part of an LDAP directory, you specify the highest level parent distinguished names in the configuration of the server. These distinguished names are called suffixes. The server can access all objects in the directory that are below the specified suffix in the directory hierarchy. For example, if an LDAP server contained the directory shown in Figure 1 on page 10, it would need to have the suffix o=ibm, c=us specified in its configuration in order to be able to answer client queries regarding Tim Jones.

Chapter 3. Getting started with AS/400 Directory Services

Figure 1. A basic LDAP directory structure

| | | | | | | | | |

A few notes about LDAP and AS/400 Directory Services: v Beginning with V4R5, both the OS/400 LDAP server and the OS/400 LDAP client are based on LDAP Version 3. You can use a V2 client with a V3 server. However, you cannot use a V3 client with a V2 server unless you bind as a V2 client and use only V2 APIs. See LDAP V2/V3 considerations for more details. v The Windows LDAP client is also based on LDAP Version 3. v Because LDAP is a standard, all LDAP servers share many basic characteristics. However, due to implementation differences, they are not all completely compatible with each other. The LDAP server provided by AS/400 Directory Services is closely compatible with other LDAP directory servers in the IBM SecureWay product group. However, it may not be as compatible with other LDAP servers. v The data for the LDAP server that AS/400 Directory Services provides resides in an OS/400 database. More information: For examples of using LDAP directories, see Example of using AS/400 Directory Services on page 11.

10

Networking AS/400 Directory Services (LDAP)

To learn about more LDAP concepts, see Chapter 5. AS/400 Directory Services concepts and reference information on page 31.

Example of using AS/400 Directory Services

You can use AS/400 Directory Services and its features in a variety of ways. The following fictitious example shows just one possible implementation of LDAP directory servers on AS/400. Jonathon is the director of the Alumni Association at a small college in Minnesota. In the past, he has maintained a file cabinet full of information on the names and addresses of alumni. He wants to move this information to a computer to make it possible for alumni at remote locations to look up information. He calls Michelle at the colleges Information Services department and asks for her help. She tells him that he can set up an LDAP directory on the same AS/400 on which he runs the Alumni Associations Web server. Michelle and Jonathon plan an LDAP directory that will include the country, state, and name of each alumnus. It also will include each alumnuss e-mail address, telephone number, and mailing address. They configure the AS/400 Directory Services LDAP directory server, specifying suffixes such as st=MN, c=US and c=Canada, as well as similar entries for other states and countries. Next, Michelle and Jonathon plan the security of their LDAP directory. The information on the server is not confidential or sensitive, so they do not have concerns about hackers intercepting information during transmission. Therefore, they decide that they do not need to use Secure Sockets Layer (SSL) security (see Using Secure Sockets Layer (SSL) security with the LDAP directory server on page 40). They do not want to go so far as to have completely open access to all directory data, however. Jonathon contacts each alumni to see if they are willing to have the information about them publicly available. Most do not care, but a few prefer to keep the information private. For those users, Michelle and Jonathon create access control lists that limit access to their information, so that only Jonathon and other members of the Alumni Association staff can view or change it. | | | | | | | | | | | | | | | | | The directory is ready to have data added to it. Jonathon will be in charge of this. He could use the shell utilities that are included with AS/400 Directory Services to populate the directory. However, he does not have much experience using command line interfaces, so he prefers to use the graphical IBM SecureWay Directory Management Tool. With this interface, Jonathon can easily add, search, and change directory entries. Over the summer, he uses the Directory Management Tool to add the information for the most recent graduates. Meanwhile, Michelle uses the application program interfaces (APIs) included with the Windows LDAP client to create a custom graphical interface. The Alumni Associations student employees can use this interface without having any knowledge about the structure of the directory. When the student employees return to campus in the fall, they use the custom interface to add the remaining alumni to the directory.

Considerations for using LDAP V2 with LDAP V3

Beginning with V4R5, both the OS/400 LDAP server and the OS/400 LDAP client are based on LDAP Version 3. You cannot use a V3 client with a V2 server. However, you can use the ldap_set_option() API to change the version of a V3 client to V2. Then you can successfully send in client requests to a V2 server.

Chapter 3. Getting started with AS/400 Directory Services

11

| | | | | | | |

You can use a V2 client with a V3 server. Be aware that on a search request, however, the V3 server may send back data in the full range of UTF-8 format, while a V2 client may be only able to handle data in the IA5 character set. Note: LDAP version 2 is formally defined in Internet Engineering Task Force (IETF) Request for Comments (RFC) 1777, Lightweight Directory Access Protocol. LDAP version 3 is formally defined in IETF RFC 2251, Lightweight Directory Access Protocol (v3). You can view these RFCs on the Internet at the following URL:

| |

http://www.ietf.org

Planning your LDAP directory server

Before you install AS/400 Directory Services and begin to configure your LDAP directory, you should take a few minutes to plan the directory. Important things to consider include the following: v Organizing the directory. Plan the structure of your directory. Determine what suffixes and attributes your server will require. | | | | | | | | | | | v Deciding how large your directory will be, so that you can estimate how much AS/400 storage you need. The size of the directory depends on the following: The number of attributes in the servers schema. The number of entries on the server. The type of information that you store on the server. For example, an empty directory that uses the default AS/400 Directory Services schema requires approximately 10 MB of storage space. A directory that uses the default schema and which contains 1000 entries of typical employee information requires about 30 MB of storage space. This number would vary depending on the exact attributes that you used. It would also increase greatly if you stored large objects, such as pictures, in the directory. v Deciding what security measures you will take. AS/400 Directory Services supports the use of Secure Sockets Layer (SSL) and Digital Certificates for communication security. AS/400 Directory Services also allows you to control access to directory objects with access control lists (ACLs). You can use OS/400 security to protect the directory database.

| | | | | | | | | | | | | | | |

Migrating to V4R5 from an earlier release of AS/400 Directory Services

V4R5 introduces new features and capabilities to AS/400 Directory Services. These changes affect both the LDAP directory server and the graphical user interface (GUI) of AS/400 Operations Navigator. To take advantage of the new GUI features, you need to install Operations Navigator on a PC that can communicate over TCP/IP to your AS/400. Operations Navigator is a component of Client Access Express (V4R5). When you upgrade from V4R4 to V4R5 of AS/400 Directory Services, both the LDAP directory data and the directory schema files are automatically migrated to conform to V4R5 formats. However, you should be aware of a few migration issues: v When you upgrade to V4R5, AS/400 Directory Services automatically migrates your V4R4 schema files to V4R5 and deletes the old V4R4 schema files. However, if you have deleted or renamed the schema files, AS/400 Directory Services cannot migrate them. You may receive an error, or AS/400 Directory Services may assume that the files have already been migrated.

12

Networking AS/400 Directory Services (LDAP)

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

v AS/400 Directory Services migrates directory data to the V4R5 format the first time that you start the server or import an LDIF file. Plan to allow some time for this migration to complete. Also, be aware that the directory data will require approximately twice as much storage space in V4R5 than it required in V4R4. This is because in V4R4 AS/400 Directory Services supported only the IA5 character set and saved data in ccsid 37 (single byte format). AS/400 Directory Services now supports the full ISO 10646 character set.. After you upgrade to V4R5, you should start your server once to migrate existing data before importing new data. If you try to import data before starting the server once and you do not have enough authority, the import may fail. v Previous releases of AS/400 Directory Services did not take time zones into account when creating time stamp entries. Beginning with V4R5, the time zone will be used in all additions and modifications to the directory. Therefore, when you upgrade when you upgrade to V4R5, AS/400 Directory Services adjusts existing createtimestamp and modifytimestamp attributes to reflect the correct time zone. It does this by subtracting the time zone that is currently defined on the AS/400 system from the time stamps that are stored in the directory. Note that if the current timezone is not the same timezone that was active when the entries were originally created or modified, the new time stamp values will not reflect the original timezone. If you are upgrading from V4R3 of AS/400 Directory Services to V4R5, you may need to perform some additional migration tasks.

Migrating from V4R3 AS/400 Directory Services to a later release

When you upgrade from V4R3 to any later release, you should be aware of the following issues: v Migrating the key ring file to a key database: V3R2 Client Access used key ring files to establish Secure Sockets Layer (SSL) connections to the LDAP directory server. Client Access Express uses certificate stores, which are sometimes called key databases, to establish SSL connections. If you used a key ring file with your LDAP directory server previously, the key ring file must be converted to a key database in order to continue using SSL. The first time that you attempt to start an SSL connection to the LDAP directory server, Operations Navigator will alert you to this change. If you choose to convert the key, it will prompt you to enter some information for the key database, then will make the conversion. The LDAP directory server also used a key ring file for its own SSL connections in V4R3. Beginning with V4R4 it uses the system certificate store. If your server was set up to use SSL in V4R3, the contents of the key ring file will be migrated to the system certificate store. v Two stream files have been removed: The following stream files used by AS/400 Directory Services in V4R3 are no longer needed and are automatically removed when you install a later release:
/QIBM/ProdData/OS400/DirSrv/qgldcert.kyr /QIBM/ProdData/OS400/DirSrv/qgldcert.sth

You do not need to take any action with these files. This is mentioned only so that you are not concerned if you notice that they are no longer present on your system. Also be aware that there may be additional associated with upgrading to the current release from other releases.
Chapter 3. Getting started with AS/400 Directory Services

13

Installing and Configuring AS/400 Directory Services

To get started using the LDAP directory server on AS/400, you must install the Directory Services option and configure the server. You must have *ALLOBJ and *IOSYSCFG special authorities to configure the server. To install and configure AS/400 Directory Services, take these steps: 1. Install AS/400 Directory Services 2. Configure the LDAP directory server If at some point you no longer want to run an LDAP directory server on your AS/400, you can then uninstall AS/400 Directory Services.

Installing AS/400 Directory Services

Before you can configure your Directory server, you must install the Directory Services option of OS/400. Directory Services may already be installed on your AS/400. For information on checking to see what programs are installed on your AS/400, see the topic Verifying system and media software in the AS/400 Information Center. install the Directory Services option, take these steps: Insert the CD-ROM that contains OS/400. Type GO LICPGM on the AS/400 command line, then press Enter. Choose option 11 from the Work with Licensed Programs menu; then press Enter. 4. Enter 1 in the Option field to the left of Option 32, OS/400 Directory Services, then press Enter. 5. In the Installation device field, enter the name of the CD-ROM drive where you inserted the OS/400 CD-ROM. 6. Press Enter. Now that you have installed AS/400 Directory Services, you can configure your LDAP directory server. To 1. 2. 3.

Configuring the LDAP directory server

AS/400 Directory Services provides a wizard in Operations Navigator to assist you in configuring the LDAP directory server. Use this wizard when you initially configure the directory server. You may also use the wizard to reconfigure the directory server. Note: When you use the wizard to reconfigure the directory server, you start configuring from scratch. The original configuration is deleted rather than changed. The directory data, however, is not deleted. It remains stored in the QUSRDIRDB library. The change log also remains intact, in the QUSRDIRDCL library. If you want to start completely from scratch, clear those two libraries before starting the wizard. If you want to change the directory server configuration, but not clear it completely, right-click Directory and select Properties. This does not delete the original configuration. Before you can configure the directory server, you must have installed the Directory Services option of OS/400. For information on checking to see what programs are installed on your AS/400, see the topic Verifying system and media

| | | | | | | | | | | |

14

Networking AS/400 Directory Services (LDAP)

software in the AS/400 Information Center. You must have *ALLOBJ and *IOSYSCFG special authorities to configure the server. To 1. 2. 3. 4. start the Configure Directory Server wizard, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Configure. Note: If you have already configured the directory server, click Reconfigure rather than Configure. Follow the on-screen instructions that the Configure Directory Server wizard gives to configure your LDAP directory server. Note: You may also want to put the library that stores the directory data in a user auxiliary storage pool (ASP) rather than the system ASP. When the wizard finishes, your LDAP directory server has a basic configuration. If you are running Lotus Domino on your AS/400, port 389, the default port for the LDAP server, is already in use. You must either change the port that Lotus Domino uses or change the port that AS/400 Directory Services uses. If you want to use another port for a different reason, you can change it now as well. If you want to, you can start the server at this point. Before starting the server, however, you may want to do some or all of the following things: v Import data to the server v Enable Secure Sockets Layer (SSL) security v Set up a referral

Enabling SSL on the LDAP directory server

If you have Digital Certificate Manager installed on your AS/400, you can use Secure Sockets Layer (SSL) security to protect access to your LDAP directory server. Before enabling SSL on the directory server, you may find it helpful to read an overview on using SSL with AS/400 Directory Services. To use an SSL connection when you administer your LDAP directory server from Operations Navigator, or to use SSL with the Windows LDAP client, you must have one of the Client Encryptions products (5769CE1, 5769CE2, or 5769CE3) installed on your PC. To enable SSL on your LDAP server, use the Digital Certificate Manager interface. You can launch Digital Certificate Manger from the Internet folder in Operations Navigator, or from the Network page of the directory servers Properties dialog. To launch it from the Network page, follow these steps: 1. In Operations Navigator, expand Network. 2. Expand Servers. 3. Click TCP/IP. 4. Right-click Directory and select Properties. 5. Click the Network tab. 6. Click Digital Certificate Manager. Digital Certificate Manager will launch in your default Internet browser. | | See Securing the LDAP directory server for the specific steps that you need to follow in order to assign a digital certificate to the directory server.

Chapter 3. Getting started with AS/400 Directory Services

15

After SSL is enabled, you can change the port that the LDAP directory server uses for secured connections.

Changing the port that the LDAP directory server uses

The LDAP directory server enabled by AS/400 Directory Services uses the following default ports: v 389 for unsecured connections. v 636 for secured connections (if you have used Digital Certificate Manager to enable AS/400 Directory Services as an application that can use a secure port). If you are already using these ports for another application, you must assign different ports to AS/400 Directory Services. To 1. 2. 3. 4. 5. 6. change the ports that the LDAP directory server uses, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Properties. Click the Network tab. Enter the appropriate port numbers, then click OK.

Uninstalling AS/400 Directory Services

| | | | | If you no longer wish to run an LDAP directory server on your AS/400, you can remove it by uninstalling the AS/400 Directory Services option of OS/400. You also need to end OS/400 jobs that use the AS/400 Directory Services product. These include the Directory Services server job, as well as the QGLDPUBA and QGLDPUBE publishing jobs. To uninstall the AS/400 Directory Services option, take these steps from a 5250 session on AS/400: 1. Type GO LICPGM, then press Enter. 2. Choose option 12 from the Work with Licensed Programs menu, then press Enter. 3. Enter 4 in the Option field to the left of Option 32, OS/400 Directory Services, then press Enter. | | | | | | | | | | | | | | | | | After you complete this procedure, your server will be uninstalled. However, some of the AS/400 Directory Services files, including the schema files, and the libraries that contain the servers data and change log, remain on AS/400. You could reinstall AS/400 Directory Services and begin running the server again. If you are sure that you will not want to run the LDAP directory server in the future, you may delete these items. The files are located at:
/QIBM/UserData/OS400/DirSrv

The data library is QUSRDIRDB. The change log library is QUSRDBCL.

The IBM SecureWay Directory Management Tool

The IBM SecureWay Directory Management Tool (DMT) provides you with a graphical user interface for managing LDAP directory content. The tasks that you can perform with the DMT include the following: v v v v Browsing directory schema Adding, editing, and deleting object classes Adding, editing, and deleting attributes Browsing and searching the directory tree

16

Networking AS/400 Directory Services (LDAP)

| | | | | | | | | | | | | | | |

v Adding, editing, viewing, and deleting entries v Editing entry RDNs The DMT is part of the Windows LDAP client that is included with AS/400 Directory Services. The client is shipped in an integrated file system directory. To install the Windows LDAP client, including the DMT, onto a PC, follow these steps: 1. In Operations Navigator, expand File Systems. 2. Expand File Shares. 3. Double-click Qdirsrv. 4. Double-click UserTools. 5. Double-click Windows. 6. Double-click setup.exe to start installing the DMT. Follow the on-screen instructions to complete the installation. Documentation for the IBM SecureWay Directory Management Tool (DMT) is located in the file dparent.htm. This file is copied to the IBM SecureWay Directory folder on your PC when you install the client.

Chapter 3. Getting started with AS/400 Directory Services

17

18

Networking AS/400 Directory Services (LDAP)

Chapter 4. Administering the LDAP directory server

To administer the LDAP directory server that AS/400 Directory Services provides, you must have one of the following authority sets: v *ALLOBJ authority and *IOSYSCFG authority v *JOBCTL authority and object authority to the End TCP/IP (ENDTCP), Start TCP/IP (STRTCP), Start TCP/IP Server (STRTCPSVR), and End TCP/IP Server (ENDTCPSVR) commands. To manage directory objects (including access control lists, object ownership, and replicas), connect to the directory with either the administrator DN or another DN that has the proper LDAP authority. Administering the directory server includes the following tasks: v Starting the LDAP directory server v Stopping the LDAP directory server on page 20 v Checking the status of the directory server on page 20 v Moving LDAP directory data between systems on page 20 v Specifying a server for directory referrals on page 27 v Adding suffixes to the LDAP directory server on page 27 v Removing suffixes from the directory server on page 27 v Saving and restoring AS/400 Directory Services information on page 28 v Managing ownership and access of directory data on page 28 v Tracking changes to the LDAP directory on page 29 v Adjusting performance of the LDAP directory server on page 30

Starting the LDAP directory server

To 1. 2. 3. 4. | | | | | | | | start the LDAP directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Start. The directory server may take several minutes to start, depending on the speed of your AS/400, and the amount of available memory. The first time you start the directory server may take several minutes longer than usual, because the server must create new files. Similarly, when starting the directory server for the first time after upgrading from an earlier version of AS/400 Directory Services, it may take several minutes longer than usual because the server must migrate files. You can check the status of the server periodically to see if it has started yet.

Note: The directory server can also be started from a 5250 session by entering the command STRTCPSVR *DIRSRV. Additionally, if you have your directory server configured to start when TCP/IP starts, you can also start it by entering the STRTCP command.

Copyright IBM Corp. 1998,2000

19

Stopping the LDAP directory server

To 1. 2. 3. 4. stop the LDAP directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Stop. The directory server may take several minutes to stop, depending on the speed of your AS/400, the amount of server activity, and the amount of available memory. You can check the status of the server periodically to see if it has stopped yet.

Note: The directory server can also be stopped from a 5250 session by entering the commands ENDTCPSVR *DIRSRV, ENDTCPSVR *ALL, or ENDTCP. ENDTCPSVR *ALL and ENDTCP also affect any other TCP/IP servers that run on your AS/400. ENDTCP will also end TCP/IP itself.

Checking the status of the directory server

Operations Navigator displays the status of the directory server in the Status column in the right frame. To 1. 2. 3. check the status of the directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Operations Navigator displays the status of all TCP/IP servers, including the directory server, in the Status column. To update the status of the servers, click the View menu and select Refresh. 4. To view more information about the status of the directory server, right-click Directory and select Status. This will show you the number of active connections, as well as other information such as past and current activity levels. Besides providing additional information, viewing status through this option can save time. You can refresh the status of the directory server without taking the additional time that is required to check the status of the other TCP/IP servers.

Checking jobs on the LDAP directory server

At times you may want to monitor specific jobs on the LDAP directory server. To check server jobs, take these steps: 1. In Operations Navigator, expand Network. 2. Expand Servers. 3. Click TCP/IP. 4. Right-click Directory and select Server Jobs..

Moving LDAP directory data between systems

Your AS/400 Directory Services LDAP server can run independently of other servers. However, you may find it useful to have it work with other servers. This can include: v Importing an LDIF file on page 21 v Exporting an LDIF file on page 21 v Setting up a new replica of the directory server on page 21 v Publishing AS/400 information to the directory server on page 25

20

Networking AS/400 Directory Services (LDAP)

Importing an LDIF file

You can transfer information between different LDAP directory servers by using LDAP Data Interchange Format (LDIF) files. Before you begin this procedure, transfer the LDIF file to your AS/400 as a stream file. To import an LDIF file to the LDAP directory server, take these steps: 1. If the directory server is started, stop it, see Stopping the LDAP directory server on page 20. 2. In Operations Navigator, expand Network. 3. Expand Servers. 4. Click TCP/IP. 5. Right-click Directory and select Tools, then Import File. Note: You can also use the ldapadd utility to import LDIF files.

Exporting an LDIF file

You can transfer information between different LDAP directory servers by using LDAP Data Interchange Format (LDIF) files, see LDAP Directory Interchange Format on page 36. You can export all or part of your LDAP directory to an LDIF file. To 1. 2. 3. 4. export an LDIF file to the directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Tools, then Export File. Note: If you do not specify a location for the LDIF file to be exported to, it will be saved to the default directory specified in your AS/400 user profile. If you have not changed your default directory, the default directory is the root directory. Notes: 1. Be sure to set authority to the LDIF file to prevent unauthorized access to directory data. To do this, right-click on the file in Operations Navigator, then select Permissions. 2. You can also create a full or partial LDIF file with the ldapsearch utility, see ldapsearch utility on page 48. Use the -L option, and redirect the output to a file.

Setting up a new replica of the directory server

| | | | | | | | | | | You can set up replicas of the LDAP directory server to directory servers on other AS/400 systems. AS/400 Directory Services uses the standard LDAP version 3 protocol to replicate. Note: You cannot replicate between LDAP version 3 and LDAP version 2 servers. Therefore, the AS/400 that you replicate to must be using the same version of OS/400 as the AS/400 from which you replicate. You can replicate the directory server to LDAP directory servers that are not on AS/400 systems, provided that they use the same version of the protocol. Be aware, however, that these servers may handle some aspects, such as security, differently than AS/400 Directory Services does. This will result in a replica that is not completely compatible.

Chapter 4. Administering the LDAP directory server

21

Follow these steps to set up a new replica of the directory server: 1. If you have not already done so, install and configure both the master server and the replica server. Note: Make sure that the schema for the suffixes match on both servers for the parts of the directory that will be replicated. Stop the master server. (optional) Set up LDAP data for initial replication. You can skip this step if you do not have any initial data that you want to transfer to the replica server from the master server. (optional) Move LDAP data to the master server. Skip this step if one of the following applies to your replica server: v It is a new LDAP directory server. v It does not contain data that you want to continue to maintain. Set up the new replica server. Set up the master server to have a new replica. Make sure the master server is allowing updates: a. In Operations Navigator, expand the AS/400 on which the master directory server runs. b. Expand Network. c. Expand Servers. d. Click TCP/IP. e. Right-click Directory and select Properties. f. If it is not already checked, check Allow directory updates.

2. 3.

4.

5. 6. 7.

Note: These instructions assume that both the master server and the replica servers are on AS/400 systems that you manage from Operations Navigator on the same PC. If you are managing your AS/400 systems from separate PCs, you can move between two PCs to perform this task. If either the master or replica server is running on an IBM platform other than AS/400, refer to the documentation for that platform to set up that server.

Setting up LDAP data for initial replication

| | | | | | | | | | | | | | | | | | | | | | You may have existing data on your master LDAP directory server that you want to add to a new replica server. To do this, you first need to export the directory to an LDIF file. While the LDIF file is exporting, you must prevent the master server from being updated. You may do this in one of the following ways: v Stop the LDAP directory server. Depending on the size of your LDIF file, this may require that your server stay stopped for an extended period of time. v Change the server properties so that updates are not allowed. This allows the server to continue answering search requests while the LDIF file is being exported. To take this option, follow these steps: 1. In Operations Navigator, expand the AS/400 system on which the master directory server runs. 2. Expand Network. 3. Expand Servers. 4. Click TCP/IP. 5. Right-click Directory and select Properties. 6. If Allow directory updates is checked, uncheck it. This will prevent updates to the directory until replication is completely set up. 7. Click OK. 8. Stop, then restart, the LDAP directory server. After you have stopped the server or changed the server properties to disallow directory updates, perform these tasks: 1. Export the directory to an LDIF file.

22

Networking AS/400 Directory Services (LDAP)

| | |

2. Transfer the LDIF file to the AS/400 system on which the replica server will run. After the LDIF file is transferred to the AS/400 system on which the replica server will run, you need to import the data to the replica server: 1. In Operations Navigator, expand the AS/400 on which the replica directory server runs. 2. If the replica server is not already stopped, stop it now. Refresh the status of the servers until the status is Stopped. 3. Expand Network. 4. Expand Servers. 5. Click TCP/IP. 6. Right-click Directory and select Properties. 7. If Allow directory updates is unchecked, check it. This will allow the data to be imported. 8. Click OK. 9. Import the LDIF file that you transferred in step 2. 10. Right-click Directory and select Properties. 11. Uncheck Allow directory updates.

Moving LDAP data to the master server

Once you make an LDAP directory server into a replica server, you can no longer update the data on it. If you have existing data on the server that you are configuring to be a replica LDAP directory server, you will probably want to move it to the master server so that it can continue to be maintained. To do this, follow these steps: 1. In Operations Navigator, expand the AS/400 on which the replica directory server runs. 2. Expand Network. 3. Expand Servers. 4. Click TCP/IP. 5. Right-click Directory and select Properties. 6. If Allow directory updates is checked, uncheck it. This will prevent updates to the directory until replication is completely set up. 7. Click OK. 8. Stop the LDAP directory server. 9. Export the directory to an LDIF file. 10. Transfer the LDIF file to the AS/400 on which the master server will run. After the LDIF file is transferred to the AS/400 system on which the master server will run, you need to import the data to the master server: 1. In Operations Navigator, expand the AS/400 on which the master directory server runs. 2. If the master directory server is not already stopped, stop it now. Refresh the status of the servers until the status is Stopped. 3. Expand Network. 4. Expand Servers. 5. Click TCP/IP. 6. Right-click Directory and select Properties. 7. If Allow directory updates is unchecked, check it. This will allow the data to be imported. 8. Click OK. 9. Import the LDIF file that you transferred in step 10 of the previous procedure. 10. Right-click Directory and select Properties. 11. Uncheck Allow directory updates.

Chapter 4. Administering the LDAP directory server

23

Setting up the new replica

Follow these steps to set up the new replica server. Note: The replica server must be configured and stopped before you perform this procedure. 1. In Operations Navigator, expand the AS/400 on which the replica directory server runs. 2. Expand Network. 3. Expand Servers. 4. Click TCP/IP. 5. If the server is not already stopped, stop it now. Refresh the status of the servers until the status is Stopped. 6. Right-click Directory and select Properties. 7. Click the Replication tab. 8. Select Use as a replica server. 9. In the Name used by master server for updates field, specify a name for the master server to use when it logs on to the replica server when it performs updates. 10. Click the Password button next to the Name used by master server for updates field. Enter a password for the master server to use when it logs on to the replica server to perform updates. Note: You should make note of this password and the name you entered in step 9. You will need them when you set up the master server for replication. In the Master server URL field, enter the name of the master server in URL format. If your master server uses a port other than the default, enter this port number as part of the URL. Click the Database/Suffixes tab. If the suffix that you want to replicate is not on the list, add it. (optional) If you want to use Secure Sockets Layer (SSL) when replicating, use Digital Certificate Manager to enable SSL for the server. You can start Digital Certificate Manger from the Network tab. For additional information on enabling SSL on a directory server, see Enabling SSL on the LDAP directory server on page 15. Click OK.

| | | | | | | | | | | | | | | |

11.

12. 13.

14.

Setting up the master server to have a new replica

Follow these steps to set up the master server to have a new replica. Note: You must have configured and started before you perform this procedure. 1. In Operations Navigator, expand the AS/400 on which the master directory server runs. 2. Expand Network. 3. Expand Servers. 4. Click TCP/IP. 5. Right-click Directory and select Properties. 6. If it is not already checked, check Allow directory updates. 7. Click OK. 8. Stop, then restart the LDAP directory server. Refresh the status of the servers until the status is Started. 9. Again, right-click Directory and select Properties. 10. Click the Replication tab. Operations Navigator may prompt you to enter connection information. Enter this information, then click OK. 11. Click Add. 12. In the Server field, enter the name of the replica server in URL format.

| | |

24

Networking AS/400 Directory Services (LDAP)

| |

13. In the Connect as field, enter the name you specified in step 9 on page 24 when you set up the replica server. 14. Click Password and enter the password you specified in step 10 on page 24 when you set up the replica server. 15. If you want to use Secure Sockets Layer (SSL) when replicating, use Digital Certificate Manager to enable SSL for the server. You can start Digital Certificate Manger from the Network tab. For additional information on enabling SSL on a directory server, see Enabling SSL on the LDAP directory server on page 15. 16. If your server does not use the default port, enter the port number in the Port field. 17. If you do not want to update the replica server every time an entry on the master server changes, select Time. Then specify how often you want the master server to update the replica. 18. Click OK. 19. Click the Database/Suffixes tab. If the suffix that you want to replicate is not on the list, add it. 20. Enable directory updates on each replica server: a. In Operations Navigator, expand the AS/400 on which the replica directory server runs. b. Expand Network. c. Expand Servers. d. Click TCP/IP. e. Right-click Directory and select Properties. f. If Allow directory updates is unchecked, check it. g. Click OK. 21. If each replica server is not already started, start it now. Note: A server cannot be both a master server and a replica server.

Publishing AS/400 information to the directory server

You can configure AS/400 to publish certain AS/400 information into an LDAP directory server on the same AS/400 or on a different AS/400. AS/400 will then automatically publish this information to the LDAP directory server when you use Operations Navigator to change this information on AS/400. You can also publish information about computers on your network. Additionally, you can call application program interfaces (APIs) from your own programs to publish other types of information to the LDAP directory. Notes: | | | | | | | | | | | | | | 1. When you configure AS/400 to publish the information type Users to the LDAP directory server, it automatically exports entries from the system distribution directory to the LDAP server. It uses the QGLDSSDD application program interface (API) to do this. This also keeps the LDAP directory synchronized with changes that are made in the system distribution directory. For information about the QGLDSSDD API, see the OS/400 Directory Services topic under Programming in the AS/400 Information Center. The information available includes the following: v How to manually call it. v How to prevent specific users from being exported to the LDAP server. v How it exports the system distribution directory fields. 2. If you have changed the QALWUSRDMN system value, make sure that it includes QDIRSRV2. You will not be able to publish AS/400 information otherwise.

Chapter 4. Administering the LDAP directory server

25

3. You can also publish AS/400 information to an LDAP directory server that is not on an AS/400 if you configure that server to use the IBM schema. To configure AS/400 to automatically publish AS/400 information into an LDAP directory server, take these steps: 1. In Operations Navigator, right-click on your AS/400 and select Properties. 2. Click the Directory Services tab. 3. Click on the types of information that you want to publish. If you plan to publish more than one type of information to the same location, you can save time by selecting multiple information types to configure at one time. Operations Navigator will then use the values you enter when you configure the one information type as default values when you configure subsequent information types. Click Configure. Click the Publish AS/400 information for check box. In the Directory server field, enter the name of the LDAP directory server where you want to publish AS/400 information. In the Under DN field, enter the parent distinguished name (DN) where you want AS/400 information added on the directory server. In the Distinguished name field, enter a DN to use when connecting to the directory server to publish AS/400 information. In the Password field, enter the password for the DN you specified in the previous step. If your directory server uses Secure Sockets Layer (SSL), select Secured, using SSL. If your directory server does not use the default port, enter the correct port number in the Port field. Click Verify to ensure that the parent DN exists on the server. Tip: Note: If your directory server uses SSL, you must have enabled Operations Navigator to use SSL in order to verify the connection. If the directory path does not exist, a dialog will prompt you to create it. Note: If the parent DN does not exist, and you do not create it, then publishing will not be successful. 13. Click OK.

4. 5. 6. 7. 8. 9. 10. 11. 12.

APIs for publishing AS/400 information to the directory server

AS/400 Directory Services provides built-in support for publishing user (for V4R3 and above) and computer (for V4R4 and above) information. These items are listed on the Directory Services page of the systems Properties dialog. You can use LDAP server configuration and publishing APIs to enable the AS/400 programs that you write to publish other types of information. These types of information then appear on the Directory Services page as well. Like users and computers, they are initially disabled, and you configure them using the same procedure. The program that adds the data to the LDAP directory is called the publishing agent. The type of information that is published, as it appears on the Directory Services page, is called the agent name. The following APIs will allow you to incorporate publishing into your own programs: QgldChgDirSvrA Use the CSVR0500 format and indicate an agent name that is marked as a disabled entry. Examples of agent names are the computers and users agent names automatically available on the Directory Services page.

26

Networking AS/400 Directory Services (LDAP)

QgldLstDirSvrA Use this APIs LSVR0500 format to list what agents are currently available on your AS/400 system. QgldPubDirObj Use this API to do the actual publishing of information. | | For detailed information about these APIs, see the OS/400 Directory Services topic under Programming in the AS/400 Information Center.

Specifying a server for directory referrals

| To 1. 2. 3. 4. 5. 6. assign referral servers for the directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory, then select Properties. Click Add. At the prompt, specify the name of the referral server in URL format.The following are examples of acceptable LDAP URLs: v ldap://test.server.com v ldap://test.server.com:400 v ldap://9.9.99.255

| | | | | | | | | |

Note: If the referral server does not use the default port, specify the correct port number as part of the URL, as port 400 is specified in the second example above. 7. Click OK.

Adding suffixes to the LDAP directory server

Adding a suffix to the LDAP directory server allows the server to manage that part of the directory tree. Note: You should not add a suffix that is under another suffix already on the server. For example, if o=ibm, c=us were a suffix on your server, you should not add ou=rochester, o=ibm, c=us. To 1. 2. 3. 4. 5. 6. 7. 8. add a suffix to the directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Properties. Click the Database/Suffixes tab. In the New suffix field, type the name of the new suffix. Click Add. Click OK.

Removing suffixes from the directory server

To 1. 2. 3. 4. 5. remove a suffix from the LDAP directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Properties. Click the Database/Suffixes tab.
Chapter 4. Administering the LDAP directory server

27

| | | | |

6. Click on the suffix that you want to remove to select it. 7. Click Remove. Note: You can choose to delete a suffix without deleting the directory objects under it. This makes the data inaccessible from the directory server. However, you can later regain access to the data by re-adding the suffix.

Saving and restoring AS/400 Directory Services information

| | | | | | | | | | | | | | | AS/400 Directory Services uses the following libraries: v The database library, QUSRIDRDB. This library contains the directory servers contents. v QDIRSRV, which contains the AS/400 Directory Services code and the configuration objects. v If you configure the directory server to log directory changes, a database library called QUSRDIRCL that the change log uses. If the contents of the directory change regularly, you should save your database library and the objects in it on a regular basis. Save QDIRSRV and the objects in it whenever you change the directory server configuration or apply Program Temporary Fixes (PTFs). Configuration data is also stored in the following directory:
/QIBM/UserData/OS400/Dirsrv/

You should also save the files in that directory whenever you change the configuration or apply PTFs.

See Backup and Recovery, SC41-5304 AS/400 data.

for information on saving and restoring

Managing ownership and access of directory data

Managing ownership and access of directory data includes the following tasks: v Working with the ownership properties of directory objects v Working with the Access Control Lists (ACLs) v Working with ACL Groups on page 29

Working with the ownership properties of directory objects

To 1. 2. 3. 4. set the ownership properties of directory objects, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Authority. If you are not already connected to the directory server, the Connect to Directory Server dialog appears. Connect as the server administrator or as the owner of the object whose ownership properties you want to work with. 5. From the directory tree, select the object whose ownership properties you want to work with, then click OK.

Working with the Access Control Lists (ACLs)

Working with access control lists (ACLs) includes assigning explicit and implicit ACLs to directory objects, adding users to ACLs, removing users from ACLs, and browsing directory objects.

28

Networking AS/400 Directory Services (LDAP)

To 1. 2. 3. 4.

work with ACLs, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Authority. If you are not already connected to the directory server, the Connect to Directory Server dialog appears. Connect as the server administrator or as the owner of the object whose ACL you want to work with. 5. From the directory tree, select the object whose ACL you want to work with, then click OK. 6. Click the ACL tab.

Working with ACL Groups

To 1. 2. 3. 4. work with ACL groups, take these steps: In Operations Navigator, select Network. Select Servers. Click TCP/IP. Right-click Directory and select ACL Groups.

Tracking changes to the LDAP directory

| | | Beginning with V4R5, you can use the LDAP directorys change log to keep track of changes to the directory. The change log is located under the special suffix cn=changelog. It is stored in the /QSYS.LIB/QUSRDIRCL.LIB library. To 1. 2. 3. 4. 5. 6. 7. enable the change log, follow these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Properties. Click the Database/Suffixes tab. Select Log directory changes. (optional) In the Maximum entries specify the maximum number of entries for the change log to keep. Note: Though this parameter is optional, you should strongly consider specifying a number of maximum entries. If you do not specify a maximum number of entries, the change log will keep all entries and may become very large. The changeLogEntry object class is used to represent the changes applied to the directory server. The set of changes is given by the ordered set of all entries within the changelog container as defined by changeNumber. The change log information is read-only. Any user who is on the Access Control List for the cn=changelog suffix can search on the entries in the change log. Only execute searches on the change log suffix, cn=changelog. Do not attempt to add, change, or delete to the change log suffix, even if you have authority to do so. This will cause unpredictable results. Example: The following example uses the ldapsearch command line utility to retrieve all change log entries logged on the server:
ldapsearch -h ldaphost -D cn=admin -w password -b "cn=changelog" "(changetype=*)"

Chapter 4. Administering the LDAP directory server

29

Adjusting performance of the LDAP directory server

You can adjust the performance of your LDAP directory server by changing any of the following: v The number of simultaneous connections that are allowed. v The size of searches. v The maximum time allowed for searches. Tip: The amount of resources that AS/400 allocates for searching the LDAP directory increases when you increase the number of maximum connections allowed. You can experiment with different maximum connection values to determine what value works best for your situation.

To 1. 2. 3. 4. 5. | | | | | | | |

adjust the performance values of the directory server, take these steps: In Operations Navigator, expand Network. Expand Servers. Click TCP/IP. Right-click Directory and select Properties. Click the Performance tab.

You can also adjust the performance of the directory server by changing the number of database connections that the server uses. To change this value, follow these steps: 1. In Operations Navigator, expand Network. 2. Expand Servers. 3. Click TCP/IP. 4. Right-click Directory and select Properties. 5. Click the Database/Suffixes tab.

30

Networking AS/400 Directory Services (LDAP)

Chapter 5. AS/400 Directory Services concepts and reference information

The following conceptual and reference information will help you to learn about and run your AS/400 Directory Services LDAP server: v LDAP access control lists (ACLs) v LDAP Directory Interchange Format on page 36 v National language support (NLS) considerations on page 39 v Ownership of LDAP directory objects on page 39 v LDAP directory referrals on page 39 v Replica LDAP directory servers on page 40 v Using Secure Sockets Layer (SSL) security with the LDAP directory server on page 40 v AS/400 Directory Services and OS/400 journaling support on page 41 For information on LDAP basics and planning your LDAP server, also see Chapter 3. Getting started with AS/400 Directory Services on page 7.

LDAP access control lists (ACLs)

In many cases, you probably would not want to restrict access to data on your LDAP directory server. For example, an LDAP server on your company Intranet might contain a telephone directory of company employees. You would probably want all employees to be able to view the data in this directory. Imagine, however, that the president of your company does not want all employees to be able to access her telephone number. In that case, you could create an access control list (ACL). With this ACL, you could restrict access to her server entry to only those employees the president wanted to receive calls from. With ACLs, you can control who has the authority to add and delete directory objects. You can also specify whether or not users have the ability to read, write, search, and compare directory attributes. ACLs can be either inherited or explicit. That is, you can use ACLs in one of the following ways: v Explicitly set up an ACL for a specific object. v Specify that objects inherit ACLs from objects higher up in the LDAP directory hierarchy. Perhaps the president in the example above did not want all employees to be able to access her telephone number. She did, however, want all managers to be able to access it. In such a case, you could make use of an ACL Group to simplify granting authority to the managers. ACL groups allow you to grant access to specific groups of users rather than granting authority on an individual basis. This is particularly useful if the same group of people needs access to more than one set of objects. If the same managers that had access to the presidents telephone number, for example, later needed access to salary entries, you could reuse the ACL group. Each LDAP attribute type has a classification of Normal, Sensitive, or Critical. The attribute schema files control these classifications. When you add a user to an objects ACL, you specify which classifications the user can read, write, search, and compare. In most schema, the telephone number would be classified as a Normal attribute. Therefore, to give the managers in the above example access to the
Copyright IBM Corp. 1998,2000

31

presidents telephone number, you would give them read access to the Normal attributes in the presidents directory object. They would still not be able to access Sensitive and Critical information. Special ACL values Initially, all objects in the AS/400 Directory Services directory server have an ACL that contains a special ACL group, CN=Anybody, that includes all directory users. This group has read, search, and compare access to objects. | | | | | | You may want some objects to have the same access permissions for all users who bind to the directory server with a connection that is not anonymous. To do this, use the special access control list (ACL) group cn=Authenticated. To specify what access permissions an object has for itself, you can use the special DN cn=this. This enables child entries who inherit their ACLs to be automatically authorized to perform operations on their own objects. Additional information To administer ACLs through Operations Navigator, you do not need to know the details of how AS/400 Directory Services implements ACLs. However, if you want to specify ACL related attributes when using LDIF files or want to use ACLs with the LDAP command line utilities, you will need to familiarize yourself with the attributes that ACLs use. For information on setting up and changing ACLs and ACL groups, follow these links: Working with the Access Control Lists (ACLs) on page 28 Working with ACL Groups on page 29

Access control list (ACL) attributes

Access control lists (ACLs) define access to objects and attributes in the AS/400 Directory Services LDAP directory. Each object in a directory contains several attributes which describe who is allowed to access information within that object. Click one of the following links to see information on that attribute: v aclEntry v aclSource v aclPropagate v entryOwner v ownerSource v ownerPropagate Click here to see an example that incorporates all of the above attributes. Click here to see the default attribute settings for AS/400 Directory Services. aclEntry attribute: aclEntry is a multi-value attribute. It contains information that pertains to the access that is allowed to the entry object and to each of its attributes. An aclEntry lists the following types of information: v Who has rights to the entry object (scope of the protection). v What classes of attributes that users have access to (attribute access classes). v What rights users have (permission).

32

Networking AS/400 Directory Services (LDAP)

Scope of protection: The scope of the protection is based on the following two types of privilege attributes: access-Id The distinguished name (DN) of the entity being granted access. group The distinguished name (DN) of the group entity being granted access. Normal groups have an object class of GroupOfNames, GroupOfUniqueNames, or a user-defined group. Access control groups are object class AccessGroup. The AccessGroup object class is a subclass of the GroupOfNames object class. Groups identified in an aclEntry must be of object class AccessGroup. Privilege attributes take the form type:name, where type refers to either access-id or group, and name is the distinguished name. In the following example, the DN type is access-id, and the DN itself is cn=personA, ou=deptXYZ, o=IBM, c=US:
access-id:cn=personA, ou=deptXYZ, o=IBM, c=US

In the following example, the DN type is group, and the DN itself is cn=deptXYZRegs, o=IBM, c=US:
group:cn=deptXYZRegs, o=IBM, c=US

Attribute access classes: Attributes that require similar permission for access are grouped together in classes. Attributes are assigned to attribute classes within the schema files. The three user-modifiable attribute classes are: v Normal v Sensitive v Critical Each of these attribute classes is discrete. That is, access to information in one class does not give access to information in any other class. Attributes have a default attribute class of normal. In the following example attribute definition, userPassword has been assigned membership in the critical access class, while DN has been assigned membership in the normal access class:

attributetypes=( 2.5.4.49 NAME ( 'dn' 'distinguishedName' ) DESC ' ' SYNTAX 1.3.6.1.4.1.1466.115.1

Access permissions: The following access permissions apply to an entire object: Add Add an object.

Delete Delete an object. The following permissions apply to attribute access classes: Read Write Read an attribute value. Write an attribute.

Chapter 5. AS/400 Directory Services concepts and reference information

33

Search Search entries with specified attributes. Compare Compare attributes. Each of the LDAP access permissions is discrete. One permission does not imply another permission. If you give a user (access-id) an aclEntry for a particular object, the user receives that permission. If no permission is given to the user, the user receives permission based on the objects ACL, and the bound user receives the combined permissions of all listed access groups. Note: There are two types of LDAP searches. One retrieves both attributes and values, and the other retrieves only attributes. In order to retrieve both attributes and values, a user must have both read and search permission to the corresponding attributes class. If the user is not listed on the ACL, and is not a member of any listed access group, then the user receives permissions listed under the ACL group CN=Anybody. If this group does not exist, the user is denied access to the object. In the following example, members of the group CN=Anybody have the permission to read, search, and compare all attributes within the normal class:
group:cn=Anybody:normal:rsc

In the following example, the user that corresponds to access-id cn=personA, ou=deptXYZ, o=IBM, c=US has permission to do the following: v v v v Add objects below this object. Delete this object. Read, write, search and compare both normal and sensitive attributes. Read, search, and compare critical attributes.

access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rwsc:cr

aclSource attribute: Each directory object has an aclSource attribute. This attribute reflects the DN with which the ACL is associated. The server keeps this attribute, but it may be retrieved for administrative purposes. aclPropagate attribute: This true or false object attribute specifies whether or not the objects ACL is propagated to objects below it in the directory hierarchy. An object without an explicit ACL receives its ACL from the first propagating ACL above the object in the directory hierarchy. Propagated ACLs do not accumulate. The scope of a propagated ACL is from the explicitly set propagating ACL down through the directory hierarchy until another propagating ACL is found. Example 1: Propagation The entry ou=deptXYZ, o=IBM, c=US has the following explicit ACL:
aclPropagate: True aclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rsc aclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rsc aclEntry: group:cn=Anybody:normal:rsc aclSource: ou=deptXYZ, o=IBM, c=US

34

Networking AS/400 Directory Services (LDAP)

The entry cn=personA, ou=deptXYZ, o=IBM, c=US has the following implicit ACL::
aclPropagate: True aclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rsc aclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rsc aclEntry: group:cn=Anybody:normal:rsc aclSource: ou=deptXYZ, o=IBM, c=US

In this example, a propagating ACL has been set on ou=deptXYZ, o=IBM, c=US. On the descendant cn=personA, ou=deptXYZ, o=IBM, c=US, no ACL has been set. Therefore, the descendant inherits its ACL from the first ancestor with a propagating ACL, which in this case is ou=deptXYZ, o=IBM, c=US. This is reflected in the aclSource field. The aclEntry and aclPropagate values are identical to the explicit propagating ACL set at ou=deptXYZ, o=IBM, c=US. Example 2: Overrides The entry o=IBM, c=US has the following explicit ACL:
aclPropagate: TRUE aclEntry: group:cn=IBMRegs, o=IBM, c=US:normal:rcs:sensitive:rsc aclEntry: group:cn=Anybody:normal:rsc aclSource: o=IBM, c=US

The entry ou=deptXYZ, o=IBM, c=US has the following explicit ACL:
aclPropagate: FALSE aclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rsc aclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rwsc aclEntry: group:cn=Anybody:normal:rsc aclSource: ou=deptXYZ, o=IBM, c=US

The entry cn=personA, ou=deptXYZ, o=IBM, c=US has the following implicit ACL:
aclPropagate: TRUE aclEntry: group:cn=IBMRegs, o=IBM, c=US:normal:rcs:sensitive:rsc aclEntry: group:cn=Anybody:normal:rsc aclSource: o=IBM, c=US

In this example, a propagating ACL has been set on o=IBM, c=US. On the descendant ou=deptXYZ, o=IBM, c=US, an explicit ACL has been set which overrides the ACL that would otherwise have been inherited from o=IBM, c=US. The entry cn=personA, ou=deptXYZ, o=IBM, c=US inherits its ACL from the first ancestor with a propagating ACL. Because ou=deptXYZ, o=IBM, c=US has the aclPropagate attribute set to FALSE, cn=personA, ou=deptXYZ, o=IBM, c=US inherits its ACL from o=IBM, c=US. The aclSource attribute reflects this. entryOwner attribute: The entryOwner attribute specifies the owner of a directory object. The user or group specified by entryOwner receives complete access to all of the objects attributes. In essence, they are the administrator for a particular object. ownerSource attribute: The ownerSource attribute reflects the DN with which the owner values are associated. The server keeps this attribute, but it can be retrieved for administrative purposes. ownerPropagate attribute:
Chapter 5. AS/400 Directory Services concepts and reference information

35

Owner propagation works in exactly the same way as ACL propagation works. By default, objects inherit owners through the directory hierarchy, and their ownerPropagate attribute is set to TRUE. If ownerPropagate is set to FALSE, the owner becomes an override that pertains only to that particular object. A typical ACL entry: The following entry shows a typical ACL for the entry cn=personA, ou=deptXYZ, o=IBM, c=US:
entryOwner: access-id:cn=deptXYQMgr, ou=deptXYZ, o=IBM, c=US ownerPropagate: TRUE aclPropagate: TRUE aclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rsc aclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rwsc:critical:rsc aclEntry: group:cn=Anybody:normal:rsc aclSource: ou=deptXYZ, o=IBM, c=US ownerSource: ou=deptXYZ, o=IBM, c=US

The entry inherits both its owner properties and its ACL properties from object ou=deptXYZ, o=IBM, c=US. Members of the group cn=deptXYZRegs, o=IBM, c=US have permission to read, search, and compare objects in both the normal and sensitive attribute classes. They do not have permission to add or delete objects under this object. Nor do they have permission to access any information or change any information on attributes in the critical class. PersonA has add and delete permission on the object, read, write, search, and compare permissions on normal and sensitive attributes. PersonA also has read, search, and compare permission on critical attributes. All other users have permission to read, search, and compare attributes in the normal attribute class only. AS/400 Directory Services ACL defaults: AS/400 Directory Services has the following ACL defaults, assuming that the administrator DN is cn=admin, c=US:
entryOwner: access-id:cn=admin, c=US ownerPropagate: TRUE aclPropagate: TRUE aclEntry: group:cn=Anybody:normal:rsc aclSource: default ownerSource: default

LDAP Directory Interchange Format

| | | | | | | | | | | The LDAP Directory Interchange Format (LDIF) provides you with a simple way to transfer directory information between LDAP directory servers. LDIF files hold LDAP directory entries in a simple text format. The format of LDIF files the directory server uses has changed slightly beginning with V4R5 of AS/400 Directory Services. LDIF files consist of a sequence of lines that describe a directory entry or a set of changes to a directory entry. They cannot describe both. The general format of an LDIF entry is:
version: 1 dn: distinguished name attrtype1: attrvalue1 ...

36

Networking AS/400 Directory Services (LDAP)

| | | | | | | | | | |

where: v version shows the version of the LDIF file format. The version number must be 1. If the version number is absent, LDIF file is considered to be in an older LDIF file format. When the LDIF file is version 1, the content MUST be UTF-8 encoded. v distinguished name is the distinguished name of the directory entry v attrtype1 is an LDAP attribute type (such as cn or ou) v attrvalue1 is value of the attribute Each entry can have several attributes. Each attribute appears on a separate line. If an attribute value is longer than a single line, it may be continued on the next line, and is preceded by a space or tab character. Blank lines separate multiple entries within the same LDIF file. Any line that begins with a pound-sign (#) is a comment line, and must be ignored when parsing an LDIF file.

| | | | | | |

Any distinguished name or attribute value that meets one of the following conditions should be base-64 encoded: v It contains carriage returns or line feeds. v It starts with a colon (:), SPACE, or less-than (<). v It ends with space. Base-64 encoded attributes are designated by using two colons between the attribute name and the value. External references are in the file:// URL format. There should be colon and less than (:<) between the attribute type and the external reference value.

| | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Here are some examples of LDIF files: Example 1: A simple LDAP file with two entries
version: 1 dn: cn=Barbara Jensen, ou=Rochester, o=Big Company, c=US objectclass: top objectclass: person objectclass: organizationalPerson cn: Barbara Jensen cn: Barbara J Jensen cn: Babs Jensen sn: Jensen uid: bjensen telephonenumber: +1 408 555 1212 description: A big sailing fan. dn: cn=Bjorn Jensen, ou=Rochester, o=Big Company, c=US objectclass: top objectclass: person objectclass: organizationalPerson cn: Bjorn Jensen sn: Jensen telephonenumber: +1 408 555 1212 description:Babs is a big sailing fan, and travels extensively in sea rch of perfect sailing conditions. title:Product Manager, Rod and Reel Division

Example 2: A file containing a base-64-encoded value

version: 1 dn: cn=Gern Jensen, ou=Rochester, o=Big Company, c=US objectclass: top
Chapter 5. AS/400 Directory Services concepts and reference information

37

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

objectclass: person objectclass: organizationalPerson cn: Gern Jensen cn: Gern O Jensen sn: Jensen uid: gernj telephonenumber: +1 408 555 1212 description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJ hc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0ICh hIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu

Example 3: A file containing a series of change records and comments Note: LDIF files with change records cannot be imported into the server directly. However, they are supported by the LDAP shell utilities.
version: 1 # Add a new entry dn: cn=Fiona Jensen, ou=Rochester, o=Big Company, c=US changetype: add objectclass: top objectclass: person objectclass: organizationalPerson cn: Fiona Jensen sn: Jensen uid: fiona telephonenumber: +1 408 555 1212 jpegphoto:< file:///usr/local/directory/photos/fiona.jpg # Delete an existing entry dn: cn=Robert Jensen, ou=Rochester, o=Big Company, c=US changetype: delete # Modify an entry's relative distinguished name dn: cn=Paul Jensen, ou=Rochester, o=Big Company, c=US changetype: modrdn newrdn: cn=Paula Jensen deleteoldrdn: 1

The order of entries in the LDIF file is important. To successfully add an entry that is specified in the LDIF file to an LDAP directory, its parent entry must first exist in the directory namespace. In the example above, the second and third entries could not be added if the first entry did not exist. Similarly, to import an LDIF file into a server that supports certain suffixes, the LDIF file must have entries for those suffixes. For example, if your server had the suffix ou=Rochester, o=Big Company, c=US, the LDIF file shown above could be imported. But if your server instead had the suffix o=Big Company, c=US, you must have an entry for that suffix specified first in the LDIF file, as shown here:
dn: o=Big Company, c=US objectclass: organization o: Big Company

The specific format and contents of LDIF files are determined by the schema of the server from which they are exported. You can import an LDIF file to any LDAP server that uses the identical schema as the server from which the file was exported. Different vendors LDAP servers use different schema (with different object classes and attributes). Therefore, you may not be able to import an LDIF file that is created by one server to another server.

38

Networking AS/400 Directory Services (LDAP)

As of this writing, an Internet Draft of an Internet Engineering Task Force (IETF) Request for Comments (RFC) on LDIF file specifications is available at the following URL:

http://www.ietf.org Related procedures: Importing an LDIF file on page 21 Exporting an LDIF file on page 21

National language support (NLS) considerations

| | | | | | | | | | | | Beginning with V4R5, both the OS/400 LDAP server and the OS/400 LDAP client are based on LDAP Version 3. Be aware of the following NLS considerations: v Data is transferred between LDAP servers and clients in UTF-8 format. All ISO 10646 characters are allowed. v The LDAP directory server uses the UCS-2 mapping method to store data in the database. v The server and the client do case insensitive string comparisons. The uppercase algorithms will not be correct for all Languages (locales). See the following books for more information about UCS-2: v AS/400 National Language Support v AS/400 International Application Development

Ownership of LDAP directory objects

Each object in your LDAP directory has at least one owner. Object owners have the power to delete the object. Owners and the server administrator are the only users that can change the ownership properties and the access control list (ACL) attributes of an object. Ownership of objects can be either inherited or explicit. That is, to assign ownership you can do one of the following: v Explicitly set up ownership for a specific object. v Specify that objects inherit their owners from objects higher up in the LDAP directory hierarchy. V4R3 of AS/400 Directory Services allowed you to specify only one owner for each LDAP directory object. Beginning in V4R4, AS/400 Directory Services allows you to specify multiple owners for the same object. Also beginning inV4R4, you can specify that an object owns itself. To do this you include the special DN cn=this in the list of object owners. For example, assume that the object cn=A has the owner cn=this. Any user will have owner access to the cn=A object if he connects to the server as cn=A. Related procedure: Working with the ownership properties of directory objects on page 28

LDAP directory referrals

Referrals allow LDAP directory servers on AS/400 to work in teams. If the DN that a client requests is not in one directory, the server can automatically send (refer) the request to any other LDAP server.

Chapter 5. AS/400 Directory Services concepts and reference information

39

AS/400 Directory Services allows you to use two different types of referrals. You can specify default referral servers, where the LDAP server will refer clients whenever any DN is not in the directory. You can also use your LDAP client to add entries to the directory server that have the objectClass referral. This allows you to specify referrals that are based on what specific DN a client requests. Note: With AS/400 Directory Services, referral objects must contain only a distinguished name (dn), an objectClass (objectClass), and a referral (ref) attribute. See ldapsearch utility on page 48 for an example that illustrates this restriction. Referral servers are closely related to replica servers. Because data on replica servers cannot be changed from clients, the replica refers any requests to change directory data to the master server.

Replica LDAP directory servers

The information stored on replica LDAP directory servers is identical to the information on your main, or master, LDAP directory server. There are two principal benefits to having one or more replicas of your LDAP directory: v Replicas make directory searches faster. Instead of having all clients direct search requests to a single master server, you can split requests between the master server and the replica servers. v Replicas provide a backup to the master server. If the master server is unavailable, a replica can still fulfill search requests and provide access to directory data. Replica servers are read-only. When an authorized user attempts to change an entry on a replica server, it refers the request to the master directory server. Related procedure: Setting up a new replica of the directory server on page 21

Using Secure Sockets Layer (SSL) security with the LDAP directory server
To make communications with your LDAP directory server more secure, AS/400 Directory Services can use Secure Sockets Layer (SSL) security. To use SSL with AS/400 Directory Services, you must have one of the Cryptographic Access Provider products (5769AC1, 5769AC2, OR 5769AC3) installed on your AS/400 system. If you want to use SSL from Operations Navigator, you must also have one of the Client Encryption products (5769CE1, 5769CE2, or 5769CE3) installed on your PC. You need this software if you want to do any of the following: v To configure and administer AS/400 Directory Services from your workstation using an SSL connection. This includes tasks that you perform from Operations Navigator. v To use an SSL connection with applications that you create with the Windows client application program interfaces (APIs). | | | SSL is the standard for Internet security.You can use SSL to communicate with LDAP clients, as well as with replica LDAP servers. Beginning with V4R5, you can use client authentication, in addition to server authentication, to provide additional

40

Networking AS/400 Directory Services (LDAP)

| | | | | | | | | |

security to your SSL connections. Client authentication requires that the LDAP client present a digital certificate that confirms the clients identity to the server before a connection is established. To use SSL, you must have Digital Certificate Manager (DCM), option 34 of OS/400, installed on your system. DCM provides an interface for you to create and manage digital certificates and certificate stores. See the documentation for Digital Certificate Manager for information on digital certificates and on using DCM. For information about SSL on AS/400, see Securing applications with SSL. For information on enabling SSL on your LDAP directory server, see Enabling SSL on the LDAP directory server on page 15.

AS/400 Directory Services and OS/400 journaling support

AS/400 Directory Services uses OS/400 database support to store directory information. AS/400 Directory Services uses commitment control to store directory entries in the database. This requires OS/400 journaling support. | | | | | | When the server or the LDIF import tool is started for the first time, the following are built: v A journal v A journal receiver v Any database tables needed initially The journal and the journal receiver are created with the following parameters:
CRTJRNRCV JRNRCV(ldap-library/QSQJRN0001) ASP(*LIBASP) THRESHOLD(524288) CRTJRN JRN(ldap-library/QSQJRN) JRNRCV(ldap-library/QSQJRN0001) MNGRCV(*SYSTEM) DLTRCV(*YES) ASP(*LIBASP) MSGQ(*LIBL/QSYSOPR) RCVSIZOPT(*RMVINTENT)

Your environment, directory size and structure, or save and restore strategy may dictate some differences, including how these objects are managed and the size threshold used. You can change journaling command parameters if necessary. For information on journaling commands, see OS/400 commands .

Chapter 5. AS/400 Directory Services concepts and reference information

41

42

Networking AS/400 Directory Services (LDAP)

Chapter 6. LDAP command line utilities

AS/400 Directory Services includes five utilities that allow you to perform actions on the LDAP directory server from the QSH shell on AS/400. These utilities use the LDAP APIs. You can use these utilities from the shell command line or call them from your programs. You may also find them useful as programming examples. When you install the Windows LDAP client that is included with AS/400 Directory Services, you also install code that is very similar to the source code for the shell utilities. The utilities are as follows: v ldapmodify and ldapadd utilities, which add and modify LDAP directory entries. v ldapdelete utility on page 46, which removes entries from the LDAP directory. v ldapsearch utility on page 48, which searches the LDAP directory for entries. v ldapmodrdn utility on page 54, which modifies the Relative Distinguished Name (RDN) of LDAP directory entries. See Notes about using SSL with the LDAP command line utilities on page 56 for information on using SSL with the command line utilities.

ldapmodify and ldapadd utilities

The ldapmodify utility allows you to change entries or add entries to the LDAP directory server from the QSH command shell on AS/400. It uses the ldap_modify application program interface (API). The ldapadd utility, which uses the ldap_add API, works identically to the ldapmodify utility with the exception that the -a flag is turned on automatically. Format: | | | ldapmodify [-a] [-V] [-b] [-c] [-r] [-n] [-v] [-F] [-R] [-C charset] [-d debuglevel] [-D binddn] [-w passwd] [-h ldaphost] [-p ldapport] [-f file] [-Z] [-K keyfile] [-P keyfilepw] [-N certificatename] ldapadd [-V] [-b] [-c] [-r] [-n] [-v] [-F] [-R] [-C charset] [-d debuglevel] [-D binddn ] [-w passwd] [-h ldaphost] [-p ldapport] [-f file] [-Z] [-K keyfile] [-P keyfilepw] [-N certificatename] Note: If you do not provide entry information from file through the use of the -f option, the utility will wait to read entries from standard input. To break out of the wait, press the SysReq key, then choose 2. End previous request. Diagnostics: The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. Click here to see examples of using these utilities.

Copyright IBM Corp. 1998,2000

43

Parameters:
-V Specifies the LDAP version that the utility uses to bind to the LDAP server. By default, it uses an LDAP V3 connection. To explictly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 application. Only ldapmodify uses this parameter. It indicates that the utility will add entries rather than modifying them. Using this parameter is the same as using ldapadd. Assume that any values that start with a / are binary values and that the actual value is in a file whose path is specified in the place where values normally appear. Continuous operation mode. Errors are reported, but ldapmodify or ldapadd continues with modifications or adds. The default is to exit after reporting an error. Replace existing values by default. Show what would be done, but do not actually modify entries. Useful for debugging in conjunction with -v. Use verbose mode, with many diagnostics written to standard output. Force application of all changes regardless of the contents of input lines that begin with replica: (by default, replica: lines are compared against the LDAP server host and port in use to decide if a replication log record should actually be applied). Specifies that referrals are not to be automatically followed. Specifies that strings supplied as input to the utility are represented in a local character set (charset), and must be converted to UTF-8. Use the -C charset option if the input string codepage is different from the job codepage value. Refer to the documentation for the ldap_set_iconv_local_charset() API to see supported charset values. Sets the debug level to debuglevel. Use binddn to bind to the LDAP directory. binddn should be a string-represented DN. Use passwd as the password for simple authentication. Specify an alternate host on which the LDAP server is running. Specify an alternate Transmission Control Protocol (TCP) port where the LDAP server is listening. The default LDAP port is 389. If not specified and -Z is specified, the default LDAP SSL port 636 is used. Read the entry modification information from an LDIF file instead of from standard input. If an LDIF file is not specified, you must use standard input to specify the update records in LDIF format. Use a secure SSL connection to communicate with the LDAP server. The -Z option is only supported by SSL-enabled versions of this tool. Specify the name of the SSL key database file. If the key database file is not in the current directory, specify the fully-qualified key database filename. If the utility cannot locate a key database, it will use a hard-codced set of default trusted certificate authority roots. The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. This parameter effectively enables the -Z switch.

-a

-b

-c

-r -n -v -F

-R -C charset

-d debuglevel -D binddn -w passwd -h ldaphost -p ldapport

-f file

-Z

-K keyfile

44

Networking AS/400 Directory Services (LDAP)

-P keyfilepw

Specify the key database password. This password is required to access the encrypted information in the key database file (including the private key). If a password stash file is associated with the key database file, the pasword is obtained from the stash file and this parameter is not required. This parameter is ignored if neither -Z nor -K are specified. Specify the label associated with the client certificate in the key database file. Note that if the LDAP server is configured to perform Server Authentication only, a client certificate is not required. If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K are specified.

-N certificatename

Alternative Input Format: ldapmodify supports an alternative input format in order to maintain compatibility with older versions of the utility. This format consists of one or more entries that are separated by blank lines. Each entry has the following format:
Distinguished Name (DN) attr=value [attr=value ...]

where attr is the name of the attribute and value is the value. By default, values are added. If you give the -r command line flag, the default is to replace existing values with the new one. Note that it is permissible for a given attribute to appear more than once (for example, you can add more than one value for an attribute). Also note that you can use a trailing backslash (\) to continue values across lines and to preserve new lines in the value itself. To remove a value, precede the attr value with a dash (-). The equal sign (=) and value should be omitted to remove an entire attribute. attr should be preceded by a plus sign (+) to add a value in the presence of the -r flag.

Examples: ldapmodify and ldapadd

Example 1: If the file /tmp/entrymods exists and has the following contents:
dn: cn=Modify Me, o=University of Higher Learning, c=US changetype: modify replace: mail mail: [email protected] add: title title: Grand Poobah add: jpegPhoto jpegPhoto:< file:///tmp/modme.jpeg delete: description -

The command ldapmodify -b -r -f /tmp/entrymods will do the following: v replace the contents of the Modify Me entrys mail attribute with the value [email protected]. v add a title of Grand Poobah.
Chapter 6. LDAP command line utilities

45

v add the contents of the file /tmp/modme.jpeg as a jpegPhoto. v completely remove the description attribute. You can perform the same modifications as above with the older ldapmodify input format:
cn=Modify Me, o=University of Higher Learning, c=US [email protected] +title=Grand Poobah +jpegPhoto=/tmp/modme.jpeg -description

The command for using the old format would be:

ldapmodify -b -r -f /tmp/entrymods

Example 2: Assume that the file /tmp/newentry exists and has the following contents:
dn: cn=John Doe, o=University of Higher Learning, c=US objectClass: person cn: John Doe cn: Johnny sn: Doe title: Manager mail: [email protected] uid: jdoe

The command ldapadd -f /tmp/entrymods will add a new entry for John Doe, using the values from the file /tmp/newentry. Example 3: If the file /tmp/newentry exists and has the contents:
dn: cn=John Doe, o=University of Higher Learning, c=US changetype: delete

The command ldapmodify -f /tmp/entrymods will remove the entry for John Doe.

ldapdelete utility
The ldapdelete utility allows you to delete one or more entries from an LDAP directory server. It runs through the QSH command shell on AS/400. It uses the ldap_delete application program interface (API). Format: ldapdelete [-V] [-n] [-v] [-c] [-R] [-C charset] [-d debuglevel] [-ffile] [-D binddn] [-w passwd] [-m mechanism] [-O hopcount] [-h ldaphost] [-p ldapport] [-Z] [-K keyfile] [-P keyfilepw] [-N certificatename] [dn]... Note: If you do not provide dn arguments, the ldapdelete command will wait to read a list of DNs from standard input. To break out of the wait, press the SysReq key, then choose 2. End previous request. Diagnostics:

46

Networking AS/400 Directory Services (LDAP)

The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. Click here to see examples of using the ldapdelete utility. Parameters:
-V Specifies the LDAP version that the utility uses to bind to the LDAP server. By default, it uses an LDAP V3 connection. To explictly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 application. Show what would be done, but do not actually delete entries. Useful for debugging in conjunction with -v. Use verbose mode, with many diagnostics written to standard output. Continuous operation mode. Errors are reported, but ldapdelete will continue with deletions. The default is to exit after reporting an error. Specifies that referrals are not to be automatically followed. Specifies that the distinguished names (DNs) supplied as input to the ldapdelete utility are represented in a local character set (charset). Use -C charset to override the default, where strings must be supplied in UTF-8. Use the -C charset option if the input string codepage is different from the job codepage value. Refer to the documentation for the ldap_set_iconv_local_charset() API to see supported charset values. Sets the debug level to debuglevel. Read a series of lines from file, performing one LDAP delete for each line in the file. Each line in the file should contain a single distinguished name (DN). Use binddn to bind to the LDAP directory. binddn should be a string-represented DN. Use passwd as the password for simple authentication. Use mechanism specify the SASL mechanism to be used to bind to the server.The ldap_sasl_bind_s() API will be used. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used. Specify hopcount to set the maximum number of hops that the client library will take when chasing referrals. The default hopcount is 10. Specify an alternate host on which the LDAP server is running. Specify an alternate Transmission Control Protocol (TCP) port where the LDAP server is listening. The default LDAP port is 389. If not specified and -Z is specified, the default LDAP SSL port 636 is used. Use a secure SSL connection to communicate with the LDAP server. The -Z option is only supported by SSL-enabled versions of this tool.

-n -v -c

-R -C charset

-d debuglevel -f file

-D binddn -w passwd -m mechanism

-O hopcount -h ldaphost -p ldapport

-Z

Chapter 6. LDAP command line utilities

47

-K keyfile

Specify the name of the SSL key database file. If the key database file is not in the current directory, specify the fully-qualified key database filename. If the utility cannot locate a key database, it will use a hard-codced set of default trusted certificate authority roots. The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. This parameter effectively enables the -Z switch. Specify the key database password. This password is required to access the encrypted information in the key database file (including the private key). If a password stash file is associated with the key database file, the pasword is obtained from the stash file and this parameter is not required. This parameter is ignored if neither -Z nor -K are specified. Specify the label associated with the client certificate in the key database file. Note that if the LDAP server is configured to perform Server Authentication only, a client certificate is not required. If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K are specified. Specifies one or more dn arguments. Each dn should be a string-represented DN.

-P keyfilepw

-N certificatename

dn

Example: ldapdelete
The following command will attempt to delete the entry named with commonName Delete Me directly below the University of Life organizational entry :
ldapdelete "cn=Delete Me, o=University of Life, c=US"

It may be necessary to supply a binddn and passwd (see the -D and -w options).

ldapsearch utility
The ldapsearch utility allows you to search for an entry on your LDAP directory server the from the QSH command shell on AS/400. It uses the ldap_search application programming interface (API). The search uses a filter that conforms to the string representation for LDAP filters. For more information on LDAP search filters, see the ldap_search API information in one of the following locations: v In the OS/400 Directory Services topic under Programming in the AS/400 Information Center. v In the IBM Lightweight Directory Access Protocol (LDAP) topic under Client Access Express in the AS/400 Information Center. If the ldapsearch utility finds one or more entries, it retrieves the attributes that are specified by attrs and prints the entries and values to standard output. If you do not list any attributes, it returns all attributes. Format:

| | | | |

48

Networking AS/400 Directory Services (LDAP)

ldapsearch [-V] [-n] [-v] [-t] [-A] [-B] [-L] [-R] [-C charset] [-d debuglevel] [-F sep] [-f file] [-D binddn] [-w bindpasswd] [-m mechanism] [-O hopcount] [-h ldaphost] [-p ldapport] [-Z] [-K keyfile] [-P keyfilepw] [-N certificatename] [-b searchbase] [-s scope] [-a deref] [-l time limit] [-z size limit] filter [attrs...] Diagnostics: The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. Output Format: If ldapsearch finds one or more entries, it writes each entry to standard output in the form:
Distinguished Name (DN) attributename=value attributename=value attributename=value ...

Multiple entries are separated with a single blank line. If you use the -F option to specify a separator character, the output displays that character instead of the equal (=) character. If you use the -t option, the name of a temporary file replaces the actual value. If you specify the -A option, only the attributename part is written. Click here to see examples of using the ldapsearch utility. Parameters:
-V Specifies the LDAP version that the utility uses to bind to the LDAP server. By default, it uses an LDAP V3 connection. To explictly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 application. Show what would be done, but do not actually perform the search. Useful for debugging in conjunction with -v. Use verbose mode, with many diagnostics written to standard output. Write retrieved values to a set of temporary files. This is useful for dealing with binary values such as jpegPhoto or audio. Retrieve attributes only (no values). This is useful when you just want to see if an attribute is present in an entry and are not interested in the specific values. Do not suppress display of binary values. This is useful when dealing with values that appear in alternate characters sets such as ISO-8859.1. This option is implied by -L Display search results in LDIF format. This option also turns on the -B option, and causes the -F option to be ignored. Specifies that referrals are not to be automatically followed.

-n -v -t -A

-B

-L -R

Chapter 6. LDAP command line utilities

49

-C charset

Specifies that strings supplied as input to the ldapsearch utility are represented in a local character set (charset). String input includes the filter, the bind DN, and the base DN. Similarly, when displaying data, ldapsearch will convert data received from the LDAP server to the specified character sUse the -C charset option if the input string codepage is different from the job codepage value. Refer to the documentation for the ldap_set_iconv_local_charset() API to see supported charset values. Also, if the -C option and the -L option are both specified, input is assumed to be in the specified character set, but output from ldapsearch is always preserved in its UTF-8 representation, or a base 64-encoded representation of the data when non-printable characters are detected. This is the case since standard LDIF files only contain UTF-8 (or base 64-encoded UTF-8) representations of string data. Sets the debug level to debuglevel. Use sepas the field separator between attribute names and values. The default separator is =, unless the -L flag has been specified, in which case this option is ignored. Read a series of lines from file, performing one LDAP search for each line in the file. Each line in the file should contain a single distinguished name (DN). Use binddn to bind to the LDAP directory. binddn should be a string-represented DN. Use passwd as the password for simple authentication. Use mechanism to specify the SASL mechanism to be used to bind to the server.The ldap_sasl_bind_s() API will be used. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used. Specify hopcount to set the maximum number of hops that the client library will take when chasing referrals. The default hopcount is 10. Specify an alternate host on which the LDAP server is running. Specify an alternate Transmission Control Protocol (TCP) port where the LDAP server is listening. The default LDAP port is 389. If not specified and -Z is specified, the default LDAP Secure Sockets Layer (SSL) port 636 is used. Use a secure SSL connection to communicate with the LDAP server. The -Z option is only supported by SSL-enabled versions of this tool. Specify the name of the SSL key database file. If the key database file is not in the current directory, specify the fully-qualified key database filename. If the utility cannot locate a key database, it will use a hard-codced set of default trusted certificate authority roots. The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. This parameter effectively enables the -Z switch. Specify the key database password. This password is required to access the encrypted information in the key database file (including the private key). If a password stash file is associated with the key database file, the pasword is obtained from the stash file and this parameter is not required. This parameter is ignored if neither -Z nor -K are specified.

-d debuglevel -F sep

-f file

-D binddn -w passwd -m mechanism

-O hopcount -h ldaphost -p ldapport

-Z

-K keyfile

-P keyfilepw

50

Networking AS/400 Directory Services (LDAP)

-N certificatename

Specify the label associated with the client certificate in the key database file. Note that if the LDAP server is configured to perform Server Authentication only, a client certificate is not required. If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K are specified. Use searchbase as the starting point for the search instead of the default. If -b is not specified, this utility will examine the LDAP_BASEDN environment variable for a searchbase definition. Specify the scope of the search. scope should be one of base, one, or sub to specify a base object, one-level, or subtree search. The default is sub. Specify how aliases dereferencing is done. deref should be one of never, always, search, or find to specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or dereferenced only when locating the base object for the search. The default is to never dereference aliases. Wait at most timelimit seconds for a search to complete. Limit the results of the search to at most sizelimit entries. This makes it possible to place an upper bound on the number of entries that are returned for a search operation. Specifies the name of the filter that the search uses. Specifies the attributes that the utility retrieves if the search finds one or more entries. If you do not list any values for attrs, the utility returns all attributes.

-b searchbase

-s scope

-a deref

-l timelimit -z sizelimit

filter attrs...

Examples: ldapsearch
Example 1: The command ldapsearch "cn=john doe" cn telephoneNumber performs a subtree search (using the default search base) for entries with a commonName of john doe. The search retrieves the commonName values and the telephoneNumber values, and prints them to standard output. If the search finds two entries, the output looks similar to this:
cn=John E Doe, ou="College of Literature, Science, and the Arts", ou=Students, ou=People, o=University of Higher Learning, c=US cn=John Doe cn=John Edward Doe cn=John E Doe 1 cn=John E Doe telephoneNumber=+1 313 555-5432 cn=John B Doe, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US cn=John Doe cn=John B Doe 1 cn=John B Doe telephoneNumber=+1 313 555-1111

Example 2: The command ldapsearch -t "uid=jed" jpegPhoto audio performs a subtree search using the default search base for entries with user id of jed. The search
Chapter 6. LDAP command line utilities

51

retrieves the jpegPhoto and audio values and writes them to temporary files. If the search finds one entry with one value for each of the requested attributes, the output looks similar to this:
cn=John E Doe, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US audio=/tmp/ldapsearch-audio-a19924 jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924

Example 3: The command ldapsearch -L -s one -b "c=US" "o=university*" o description performs a one-level search at the c=US level . This search looks for all organizations whose organizationName begins with university. The search displays its results in the LDIF format. It retrieves the organizationName attribute value and the description attribute values and prints them to standard output that looks similar to this:
dn: o=University of Alaska Fairbanks, c=US o: University of Alaska Fairbanks description: Preparing Alaska for a brave new tomorrow description: leaf node only dn: o=University of Colorado at Boulder, c=US o: University of Colorado at Boulder description: No personnel information description: Institution of education and research dn: o=University of Colorado at Denver, c=US o: University of Colorado at Denver o: UCD o: CU/Denver o: CU-Denver description: Institute for Higher Learning and Research dn: o=University of Florida, c=US o: University of Florida o: UFl description: Shaper of young minds ...

Example 4: As discussed in LDAP directory referrals on page 39, AS/400 Directory Services LDAP directories may contain referral objects , provided that they contain only the following: v A distinguished name (dn). v An objectClass (objectClass). v A referral (ref) attribute. This example demonstrates searches where a referral object is involved. Assume that System_A holds the referral entry:
dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=US ref: ldap://System_B:389/cn=Barb Jensen, ou=Rochester, o=Big Company, c=US objectclass: referral

All attributes associated with the entry should reside on System_B. System_B contains an entry:

52

Networking AS/400 Directory Services (LDAP)

dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=US cn: Barb Jensen objectclass: organizationalPerson sn: Jensen telephonenumber: (800) 555 1212

When a client issues a request to System_A, the LDAP server on System_A responds to the client with the URL:
ldap://System_B:389/cn=Barb Jensen, ou=Rochester, o=Big Company, c=US

The client uses this information to issue a request to System_B. If the entry on System_A contains attributes in addition to dn, objectclass, and ref, the server ignores those attributes (unless you specify the -R flag to indicate not to chase referrals). When the client receives a referral response from a server, it issues the request again, this time to the server to which the returned URL refers. The new request has the same scope as the original request. The results of this search vary depending on the value you specify for the scope of the search (-b). If you specify -s base, as shown here:
ldapsearch -h System_A -b 'ou=Rochester, o=Big Company, c=US' -s base 'sn=Jensen'

the search returns all attributes for all entries with sn=Jensen that reside in 'ou=Rochester, o=Big Company, c=US' on both System_A and System_B. If you specify -s sub, as shown here:
ldapsearch -h System_A -b 'ou=Rochester, o=Big Company, c=US' -s sub 'sn=Jensen'

the search returns all attributes for all entries with sn=Jensen that reside in or below 'ou=Rochester, o=Big Company, c=US' on both System_A and System_B. If you specify -s one, as shown here:
ldapsearch -h System_A -b 'ou=Rochester, o=Big Company, c=US' -s one 'sn=Jensen'

the search returns no entries on either system. Instead, the server returns the referral URL to the client:
ldap://System_B:389/cn=Barb Jensen, ou=Rochester, o=Big Company, c=US

The client in turn submits a request:

ldapsearch -h System_B -b 'ou=Rochester, o=Big Company, c=US' -s one 'sn=Jensen'

This does not give any results either, because the entry dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=US resides at ou=Rochester, o=Big Company, c=US. A search with -s one attempts to find entrie c=US.

Chapter 6. LDAP command line utilities

53

ldapmodrdn utility
The ldapmodrdn utility allows you to change the Relative Distinguished Name (RDN) of entries on the LDAP directory server. You use it from the QSH command shell on AS/400. It uses the ldap_modrdn application program interface (API). Format: ldapmodrdn [-V] [-r] [-n] [-v] [-c] [-R] [-C charset] [-d debuglevel] [-D binddn] [-w passwd] [-m mechanism] [-O hopcount] [-h ldaphost] [-p ldapport] [-Z] [-K keyfile] [-P keyfilepw] [-N certificatename] [-f file] [dn rdn] Notes: 1. If you give the command-line arguments dn and rdn, rdn will replace the RDN of the entry that is specified by the DN, dn. Otherwise, the contents of the file (or of the standard input if you do not give the -f flag) should consist of one or more entries.
Distinguished Name (DN) Relative Distinguished Name (RDN)

One or more blank lines separate each DN/RDN pair. 2. If do not supply entry information from file through the use of the -f option (or from the command-line pair dn and rdn), the ldapmodrdn command will wait to read entries from standard input. To break out of the wait, press the SysReq key, then choose 2. End previous request. Diagnostics: The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. Click here to see an example of using the ldapmodrdn utility. Parameters:
-V Specifies the LDAP version that the utility uses to bind to the LDAP server. By default, it uses an LDAP V3 connection. To explictly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 application. Remove old relative distinguished name (RDN) values from the entry. Default is to keep old values. Show what would be done, but do not actually change entries. Useful for debugging in conjunction with -v. Use verbose mode, with many diagnostics written to standard output. Continuous operation mode. Errors are reported, but ldapmodrdn will continue with modifies. The default is to exit after reporting an error. Specifies that referrals are not to be automatically followed. Specifies that strings supplied as input to the utility are represented in a local character set (charset), and must be converted to UTF-8. Use the -C charset option if the input string codepage is different from the job codepage value. Refer to the documentation for the ldap_set_iconv_local_charset() API to see supported charset values.

-r -n -v -c

-R -C charset

54

Networking AS/400 Directory Services (LDAP)

-d debuglevel -D binddn -w passwd -m mechanism

Sets the debug level to debuglevel. Use binddn to bind to the LDAP directory. binddn should be a string-represented DN. Use passwd as the password for simple authentication. Use mechanism specify the SASL mechanism to be used to bind to the server.The ldap_sasl_bind_s() API will be used. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used. Specify hopcount to set the maximum number of hops that the client library will take when chasing referrals. The default hopcount is 10. Specify an alternate host on which the LDAP server is running. Specify an alternate Transmission Control Protocol (TCP) port where the LDAP server is listening. The default LDAP port is 389. If not specified and -Z is specified, the default LDAP SSL port 636 is used. Use a secure SSL connection to communicate with the LDAP server. The -Z option is only supported by SSL-enabled versions of this tool. Specify the name of the SSL key database file. If the key database file is not in the current directory, specify the fully-qualified key database filename. If the utility cannot locate a key database, it will use a hard-codced set of default trusted certificate authority roots. The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. This parameter effectively enables the -Z switch. Specify the key database password. This password is required to access the encrypted information in the key database file (including the private key). If a password stash file is associated with the key database file, the pasword is obtained from the stash file and this parameter is not required. This parameter is ignored if neither -Z nor -K are specified. Specify the label associated with the client certificate in the key database file. Note that if the LDAP server is configured to perform Server Authentication only, a client certificate is not required. If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K are specified. Read the entry modification information from an LDIF file instead of from standard input or the command-line (by specifying dn and the new rdn). Standard input can also be supplied from a file (< file). Specify the distinguished name of an entry to rename and the new relative distinguished name for the entry.

-O hopcount -h ldaphost -p ldapport

-Z

-K keyfile

-P keyfilepw

-N certificatename

-f file

dn rdn

Example: ldapmodrdn
Assume that you have already created the text file /tmp/entrymods and that it has the following contents:
cn=Modify Me, o=University of Life, c=US cn=The New Me
Chapter 6. LDAP command line utilities

55

The following command:

ldapmodrdn -r -f /tmp/entrymods

will change the RDN of the Modify Me entry from Modify Me to The New Me. The old cn, Modify Me will be removed.

Notes about using SSL with the LDAP command line utilities
To use the Secure Sockets Layer (SSL) features of the command line utilities, you must have installed Cryptographic Access Provider 40-bit (5769AC1), Cryptographic Access Provider 56-bit (5769AC2), or Cryptographic Access Provider 128-bit (5769AC3) on your AS/400. | | | | | | | | | | | | | | | | | | | Using Secure Sockets Layer (SSL) security with the LDAP directory server on page 40 discusses using SSL with the AS/400 Directory Services LDAP server, including managing and creating trusted Certificate Authorities with Digital Certificate Manager. Some LDAP servers that the client accesses use only server authentication. For these servers, you only need to define one or more trusted root certificates in the certificate store. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted Certificate Authorities (CAs). In addition, all LDAP transactions that flow over the SSL connection with the server are encrypted. This includes the LDAP credentials that are supplied on application program interfaces (APIs) that are used to bind to the directory server. For example, if the LDAP server is using a high-assurance Verisign certificate, you should do the following: 1. Obtain a CA certificate from Verisign. 2. Use DCM to import it into your certificate store. 3. Use DCM to mark it as trusted. If the LDAP server is using a privately issued server certificate, the servers administrator can supply you with a copy of the servers certificate request file. Import the certificate request file into your certificate store and mark it as trusted. If you use the shell utilities to access LDAP servers that use both client authentication and server authentication, you must do the following: v Define one or more trusted root certificates in the system certificate store. This allows the client to be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL connection with the server are encrypted. This includes the LDAP credentials that are supplied on application program interfaces (APIs) that are used to bind to the directory server. v Create a key pair and request a client certificate from a CA. After receiving the signed certificate from the CA, receive the certificate into the key ring file on the client.

| | | | | |

56

Networking AS/400 Directory Services (LDAP)

Chapter 7. Troubleshooting AS/400 Directory Services

Unfortunately, even reliable servers such as the AS/400 Directory Services LDAP server sometimes have problems. When your LDAP directory server has problems, the following information can help you figure out what is wrong and how to fix the trouble. v Basic troubleshooting procedure for AS/400 Directory Services v Common LDAP client errors on page 58

Basic troubleshooting procedure for AS/400 Directory Services

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | You can find return codes for LDAP errors in the ldap.h file, which is located on AS/400 in QSYSINC/H.LDAP. When you get an error on your LDAP directory server and want more detail, another action to take is toview the QDIRSRV job log. AS/400 Directory Services uses several Structured Query Language (SQL) servers. When an SQL error occurs, the QDIRSRV job log will usually contain the following message:
SQL error -1 occurred

In these instances the QDIRSRV job log will refer you to the SQL server job logs. However, in some cases QDIRSRV may not contain this message and this referral, even if an SQL server is the cause of the problem. In these instances, it will help you to know what SQL servers should be started, and what AS/400 Directory Services uses them for. When the LDAP directory server starts normally, it generates messages similar to the following: Note: The messages and the number of SQL server jobs started may differ in any of the following cases: v You are starting your server for the first time. v Migration needs to occur. v Your server is using the change log.
Job . . : QDIRSRV User . . : QDIRSRV System: Number . . . : processing. processing. processing. processing. processing. WARMERS 174440

>> CALL PGM(QDIRSRV/QGLDSVR) Job 057448/QUSER/QSQSRVR used for Job 057340/QUSER/QSQSRVR used for Job 057448/QUSER/QSQSRVR used for Job 057166/QUSER/QSQSRVR used for Job 057279/QUSER/QSQSRVR used for Directory Services server started

SQL server mode SQL server mode SQL server mode SQL server mode SQL server mode successfully.

AS/400 Directory Services uses the first SQL server, 057448/QUSER/QSQSRVR, during LDAP server startup. AS/400 Directory Services may start additional SQL servers during LDAP server startup as necessary if you are starting your server for the first time, if migration needs to occur, or if your server is using the change log. After startup, these SQL servers are dropped.

Copyright IBM Corp. 1998,2000

57

| | | | | | | | | | | |

AS/400 Directory Services uses the next SQL server, 057340/QUSER/QSQSRVR, for LDAP adds, deletes, and modifies. Unless you have changed the number of connections in your configurations file, this server is fourth from the end of this list. AS/400 Directory Services uses the next SQL server, 057448/QUSER/QSQSRVR, only for replication. In the example above, the SQL server used during startup has been reclaimed for replication. AS/400 Directory Services uses the remaining SQL servers for LDAP searches. On the directory servers Database/Suffixes Properties page in Operations Navigator you specify the total number of SQL servers that it uses. In the example above there are two SQL servers used for LDAP searches, 057166/QUSER/QSQSRVR and 057279/QUSER/QSQSRVR.

Monitoring errors and access with the AS/400 Directory Services job log
Viewing the job log for your LDAP server can alert you to errors and help you to monitor server access. If your server is started, take these steps to view the QDIRSRV job log: 1. In Operations Navigator, expand Network. 2. Expand Servers. 3. Click TCP/IP. 4. Right-click Directory and select Server Jobs.. 5. From the File menu, choose Job Log. If your server is stopped, take these steps to view the QDIRSRV job log: 1. In Operations Navigator, expand Basic Operations. 2. Click Printer Output. 3. QDIRSRV appears in the User column of Operations Navigators right panel. To view the job log, double-click on Qpjoblog to the left of QDIRSRV in the same row. Note: Operations Navigator may be configured to show only spooled files. If QDIRSRV does not appear on the list, click Printer Output, then choose Include from the Options menu. Specify All in the User field, then click OK. Note: AS/400 Directory Services uses other system resources to perform some tasks. If an error occurs with one of those resources, the job log will indicate where to go for information. In some cases AS/400 Directory Services may not be able to determine where to look. In those cases, look in the Structured Query Language (SQL) servers job log to see if the problem was related to SQL servers.

Common LDAP client errors

| | | | Knowing the causes of common LDAP client errors can help you to solve problems with your server. For a complete list of LDAP client error conditions, see the OS/400 Directory Services topic under Programming in the AS/400 Information Center. The client error messages have the following format:
[Failing LDAP operation]:[LDAP client API error conditions]

58

Networking AS/400 Directory Services (LDAP)

Note: The explanation of these errors assumes that the client is communicating with an LDAP server on OS/400. A client communicating with a server on a different platform might get similar errors, but the causes and resolutions would most likely be different. Common messages include the following: v v v v v v ldap_search: Timelimit exceeded [Failing LDAP operation]: Operations error ldap_bind: No such object ldap_bind: Inappropriate authentication [Failing LDAP operation]: Insufficient access [AS/400 System]: A remote host refused an attempted connect operation on page 60 v [AS/400 System]: Failed to connect to ssl server on page 60

ldap_search: Timelimit exceeded

This error occurs when ldapsearches are performing slowly. To correct this error, you can do one or both of the following: v Increase the search time limit for the LDAP directory server. See Adjusting performance of the LDAP directory server on page 30 for information on doing this. v Reduce the activity on the AS/400. You can also reduce the number of active LDAP client jobs running.

[Failing LDAP operation]: Operations error

Several things can generate this error. To get information about the cause of this error for a particular instance, look at the QDIRSRV and Structured Query Language (SQL) server job logs as described in Basic troubleshooting procedure for AS/400 Directory Services on page 57.

ldap_bind: No such object

| | | | | | A common cause of this error is a that a user makes a typing mistake when performing an operation. Another common cause is when the LDAP client attempts to bind with a DN that does not exist. This often occurs when the user specifies what he or she mistakenly thinks is the administrator DN. For example, the user may specify QSECOFR or Administrator, when the actual administrator DN may be something like cn=Administrator. For details about the error, look at the QDIRSRV job log as described in Basic troubleshooting procedure for AS/400 Directory Services on page 57.

ldap_bind: Inappropriate authentication

This error is usually generated when the client attempts to bind with a password that is not valid. To obtain detail about the error, look at the QDIRSRV job log as described in Basic troubleshooting procedure for AS/400 Directory Services on page 57.

[Failing LDAP operation]: Insufficient access

This error is usually generated when the binding DN does not have authority to do the operation (such as an add or delete) that the client requests. To get

Chapter 7. Troubleshooting AS/400 Directory Services

59

information about the error, look at the QDIRSRV job log as described in Basic troubleshooting procedure for AS/400 Directory Services on page 57.

[AS/400 System]: A remote host refused an attempted connect operation

The most common causes of this error include the following: v An LDAP client makes a request before the LDAP server on the specified AS/400 system is up and in select wait status. v The user specifies a port number that is not valid. For example, the server is listening on port 386, but the client request attempts to use port 387. To get information about the error, look at the QDIRSRV job log as described in Basic troubleshooting procedure for AS/400 Directory Services on page 57. If the Directory Services server started successfully, the message Directory Services server started successfully will be in the QDIRSRV job log.

[AS/400 System]: Failed to connect to ssl server

This error occurs when the LDAP server rejects the client connection because a secure socket connection cannot be established. This can occur when the Certificate Management support rejects the clients attempt to connect to the server. Use Digital Certificate Manager to make sure that your certificates are set up properly, then try to connect again.

60

Networking AS/400 Directory Services (LDAP)

Printed in U.S.A.