as400 ldap

NetworkingAS/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 Contractwith IBM Corp.

Contents

Part 1. Directory Services (LDAP) . . 1

Chapter 1. What’s new for V4R5 . . . . 3

Chapter 2. Print this topic . . . . . . . 5

Chapter 3. Getting started with AS/400Directory Services . . . . . . . . . . 7LDAP basics . . . . . . . . . . . . . . 8

Example of using AS/400 Directory Services . . 11Considerations for using LDAP V2 with LDAPV3 . . . . . . . . . . . . . . . . 11

Planning your LDAP directory server . . . . . 12Migrating to V4R5 from an earlier release of AS/400Directory Services . . . . . . . . . . . . 12

Migrating from V4R3 AS/400 Directory Servicesto a later release . . . . . . . . . . . . 13

Installing and Configuring AS/400 DirectoryServices . . . . . . . . . . . . . . . 14

Installing AS/400 Directory Services . . . . . 14Configuring the LDAP directory server . . . . 14Uninstalling AS/400 Directory Services . . . . 16

The IBM SecureWay Directory Management Tool . . 16

Chapter 4. Administering the LDAPdirectory server . . . . . . . . . . . 19Starting the LDAP directory server . . . . . . 19Stopping the LDAP directory server . . . . . . 20Checking the status of the directory server . . . . 20Checking jobs on the LDAP directory server . . . 20Moving LDAP directory data between systems . . 20

Importing an LDIF file . . . . . . . . . 21Exporting an LDIF file. . . . . . . . . . 21Setting up a new replica of the directory server 21Publishing AS/400 information to the directoryserver . . . . . . . . . . . . . . . 25

Specifying a server for directory referrals . . . . 27Adding suffixes to the LDAP directory server . . . 27Removing suffixes from the directory server . . . 27Saving and restoring AS/400 Directory Servicesinformation . . . . . . . . . . . . . . 28Managing ownership and access of directory data 28

Working with the ownership properties ofdirectory objects . . . . . . . . . . . . 28Working with the Access Control Lists (ACLs). . 28

Working with ACL Groups . . . . . . . . 29Tracking changes to the LDAP directory . . . . . 29Adjusting performance of the LDAP directory server 30

Chapter 5. AS/400 Directory Servicesconcepts and reference information . . 31LDAP access control lists (ACLs) . . . . . . . 31

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

Chapter 6. LDAP command line utilities 43ldapmodify and ldapadd utilities . . . . . . . 43

Examples: ldapmodify and ldapadd . . . . . 45ldapdelete utility . . . . . . . . . . . . 46

Example: ldapdelete . . . . . . . . . . 48ldapsearch utility . . . . . . . . . . . . 48

Examples: ldapsearch . . . . . . . . . . 51ldapmodrdn utility . . . . . . . . . . . . 54

Example: ldapmodrdn . . . . . . . . . . 55Notes about using SSL with the LDAP commandline utilities . . . . . . . . . . . . . . 56

Chapter 7. Troubleshooting AS/400Directory Services . . . . . . . . . . 57Basic troubleshooting procedure for AS/400Directory Services . . . . . . . . . . . . 57

Monitoring errors and access with the AS/400Directory Services job log. . . . . . . . . 58

Common LDAP client errors . . . . . . . . 58ldap_search: Timelimit exceeded . . . . . . 59[Failing LDAP operation]: Operations error . . . 59ldap_bind: No such object . . . . . . . . 59ldap_bind: Inappropriate authentication . . . . 59[Failing LDAP operation]: Insufficient access . . 59[AS/400 System]: A remote host refused anattempted connect operation. . . . . . . . 60[AS/400 System]: Failed to connect to ssl server 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/InternetProtocol (TCP/IP), and is gaining popularity as a directory service for bothInternet and non-Internet applications.

If you are already familiar with AS/400 Directory Services, you might want to firstread start with what’s new for this release. If you want, you can print or display aPDF version of the AS/400 Directory Services information.

The following topics introduce AS/400 Directory Services and provide you withinformation to help you administer the LDAP server on your AS/400:v “Chapter 3. Getting started with AS/400 Directory Services” on page 7v “Chapter 4. Administering the LDAP directory server” on page 19v “Chapter 5. AS/400 Directory Services concepts and reference information” on

page 31v “Chapter 6. LDAP command line utilities” on page 43v “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 1

|

|

|

|

http://www.as400.ibm.com/ldap

http://www.as400.ibm.com/ldap

http://www.software.ibm.com/network/directory/

http://www.software.ibm.com/network/directory/

2 Networking AS/400 Directory Services (LDAP)

Chapter 1. What’s new for V4R5

AS/400 Directory Services has the following enhancements and new features forV4R5: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, whichprovides 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 arespecified 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-anonymousconnections.

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, butis included for historical reasons. Generalized Time uses four digits for the yearand 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 forV4R4: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 distributiondirectory 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. Thismakes retrieving both operational and non-operational attributes in one searchmuch easier. To do this, you would list in your search the operational attributesyou wanted information for, plus the ″*″.

v You can use aliases with the directory server.


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

|

Chapter 2. Print this topic

You can view or download a PDF version of this document for viewing orprinting. You must have Adobe® Acrobat® Reader installed to view PDF files. Youcan 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 save a PDF on your workstation for viewing or printing:1. Open the PDF in your browser (click the link above).2. In the menu of your browser, click File.3. Click Save As...4. Navigate to the directory in which you would like to save the PDF.5. Click Save.


http://www.adobe.com/prodindex/acrobat/readstep.html

rzahymst.pdf

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/InternetProtocol (TCP/IP), and is gaining popularity as a directory service for bothInternet and non-Internet applications. You perform most setup and administeringtasks 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 yourAS/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 clientapplications. For information about these APIs, see the ″Directory Services″ topicunder ″Programming″ in the AS/400 Information Center.

v A Windows 95 and Windows NT LDAP client. This client includes the IBMSecureWay Directory Management Tool, which provides you with a graphicaluser interface for managing directory content.The Windows LDAP client also includes a set of application programminginterfaces (APIs) that you can use in your own applications. For moreinformation about these APIs, see the ″IBM Lightweight Directory AccessProtocol (LDAP)″ topic under ″Client Access Express″ in the AS/400 InformationCenter.

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” onpage 12.

For an introduction to LDAP, see “LDAP basics” on page 8. Even if you have usedLDAP servers on other platforms, you should take a few minutes to read thistopic, 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 “Installingand Configuring AS/400 Directory Services” on page 14.

This documentation provides an overview of LDAP, and concentrates specificallyon managing the LDAP directory server on AS/400. For additional and morecomprehensive 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


|||

|||||

|||

|

||||||

./apis/ldap_intro.html

RZAIKLDAP.HTM

RZAIKLDAP.HTM

http://www.redbooks.ibm.com/abstracts/sg245110.html

http://www.redbooks.ibm.com/abstracts/sg244986.html

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

LDAP basicsThe Lightweight Directory Access Protocol (LDAP) is a directory service protocolthat runs over Transmission Control Protocol/Internet Protocol (TCP/IP). LDAPversion 2 is formally defined in Internet Engineering Task Force (IETF) Request forComments (RFC) 1777, Lightweight Directory Access Protocol. LDAP version 3 isformally defined in IETF RFC 2251, Lightweight Directory Access Protocol (v3).Youcan 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 LDAPservers contain the directory data. An LDAP client connects to an LDAP Serverand makes a request. The server responds with a reply, or with a pointer (areferral) to another LDAP server.

Uses of LDAP:

Because LDAP is a directory service, rather than a database, the information in anLDAP directory is usually descriptive, attribute-based information. LDAP usersgenerally read the information in the directory much more often than they changeit. Updates are typically simple all-or-nothing changes. Common uses of LDAPdirectories include online telephone directories and e-mail directories.

LDAP directory structure:

The LDAP directory service model is based on entries (which are also referred toas objects). Each entry consists of one or more attributes, such as a name oraddress, and a type. The types typically consist of mnemonic strings, such as cn forcommon name or mail for e-mail address.

The example directory in Figure 1 on page 10 shows an entry for Tim Jones thatincludes mail and telephoneNumber attributes. Some other possible attributes includefax, title, sn (for surname), and jpegPhoto.

Each directory has a schema, which is a set of rules that determine the structureand contents of the directory. You should use the IBM SecureWay DirectoryManagement Tool (DMT) to edit the schema files for your LDAP server. After youinstall 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 theUserData directory, you can copy these files to that directory.

Each directory entry has a special attribute called objectClass. This attributecontrols which attributes are required and allowed in an entry. In other words, thevalues of the objectClass attribute determine the schema rules the entry must obey.

Each directory entry also has the following operational attributes, which theLDAP server automatically maintains:


|

http://www.ietf.org/

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 thatreflects political, geographic, or organizational boundaries (see Figure 1 onpage 10). Entries that represent countries appear at the top of the hierarchy. Entriesrepresenting states or national organizations occupy the second level down in thehierarchy. 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 thisstructure, entries are composed of the parts of TCP/IP domain names. Forexample, dc=ibm,dc=com may be preferable to o=ibm,c=us.

LDAP refers to entries with Distinguished Names (DNs). Distinguished namesconsist of the name of the entry itself as well as the names, in order from bottomto top, of the objects above it in the directory. For example, the complete DN forthe entry in the bottom left corner of Figure 1 on page 10 iscn=Tim Jones, o=IBM, c=US. Each entry has at least one attribute that is used toname the entry. This naming attribute is called the Relative Distinguished Name(RDN) of the entry. The entry above a given RDN is called its parentDistinguished Name. In the example above, cn=TimJones 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, youspecify the highest level parent distinguished names in the configuration of theserver. These distinguished names are called suffixes. The server can access allobjects in the directory that are below the specified suffix in the directoryhierarchy. For example, if an LDAP server contained the directory shown inFigure 1 on page 10, it would need to have the suffix o=ibm, c=us specified in itsconfiguration in order to be able to answer client queries regarding ″Tim Jones″.

Chapter 3. Getting started with AS/400 Directory Services 9

||||||

||||

A few notes about LDAP and AS/400 Directory Services:

v Beginning with V4R5, both the OS/400 LDAP server and the OS/400 LDAPclient 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 V2client 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 completelycompatible with each other. The LDAP server provided by AS/400 DirectoryServices is closely compatible with other LDAP directory servers in the IBMSecureWay product group. However, it may not be as compatible with otherLDAP servers.

v The data for the LDAP server that AS/400 Directory Services provides resides inan OS/400 database.

More information:

For examples of using LDAP directories, see “Example of using AS/400 DirectoryServices” on page 11.

Figure 1. A basic LDAP directory structure


||||

||||||

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

Example of using AS/400 Directory ServicesYou can use AS/400 Directory Services and its features in a variety of ways. Thefollowing fictitious example shows just one possible implementation of LDAPdirectory 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 andaddresses of alumni. He wants to move this information to a computer to make itpossible for alumni at remote locations to look up information. He calls Michelle atthe college’s Information Services department and asks for her help. She tells himthat he can set up an LDAP directory on the same AS/400 on which he runs theAlumni Association’s 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 alumnus’s e-mail address,telephone number, and mailing address. They configure the AS/400 DirectoryServices LDAP directory server, specifying suffixes such as st=MN, c=US andc=Canada, as well as similar entries for other states and countries.

Next, Michelle and Jonathon plan the security of their LDAP directory. Theinformation on the server is not confidential or sensitive, so they do not haveconcerns 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” onpage 40). They do not want to go so far as to have completely open access to alldirectory data, however. Jonathon contacts each alumni to see if they are willing tohave the information about them publicly available. Most do not care, but a fewprefer to keep the information private. For those users, Michelle and Jonathoncreate access control lists that limit access to their information, so that onlyJonathon 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 topopulate the directory. However, he does not have much experience usingcommand line interfaces, so he prefers to use the graphical IBM SecureWayDirectory Management Tool. With this interface, Jonathon can easily add, search,and change directory entries. Over the summer, he uses the Directory ManagementTool to add the information for the most recent graduates. Meanwhile, Michelleuses the application program interfaces (APIs) included with the Windows LDAPclient to create a custom graphical interface. The Alumni Association’s studentemployees can use this interface without having any knowledge about thestructure of the directory. When the student employees return to campus in thefall, they use the custom interface to add the remaining alumni to the directory.

Considerations for using LDAP V2 with LDAP V3Beginning with V4R5, both the OS/400 LDAP server and the OS/400 LDAP clientare 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 V3client to V2. Then you can successfully send in client requests to a V2 server.


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

|

||||

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 AccessProtocol. LDAP version 3 is formally defined in IETF RFC 2251, LightweightDirectory Access Protocol (v3). You can view these RFCs on the Internet at thefollowing URL:

http://www.ietf.org

Planning your LDAP directory serverBefore you install AS/400 Directory Services and begin to configure your LDAPdirectory, you should take a few minutes to plan the directory. Important things toconsider 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 server’s 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 Servicesschema requires approximately 10 MB of storage space. A directory that uses thedefault schema and which contains 1000 entries of typical employee informationrequires about 30 MB of storage space. This number would vary depending onthe exact attributes that you used. It would also increase greatly if you storedlarge objects, such as pictures, in the directory.

v Deciding what security measures you will take. AS/400 Directory Servicessupports the use of Secure Sockets Layer (SSL) and Digital Certificates forcommunication security. AS/400 Directory Services also allows you to controlaccess to directory objects with access control lists (ACLs). You can use OS/400security to protect the directory database.

Migrating to V4R5 from an earlier release of AS/400 Directory ServicesV4R5 introduces new features and capabilities to AS/400 Directory Services. Thesechanges 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 overTCP/IP to your AS/400. Operations Navigator is a component of Client AccessExpress (V4R5). When you upgrade from V4R4 to V4R5 of AS/400 DirectoryServices, both the LDAP directory data and the directory schema files areautomatically migrated to conform to V4R5 formats. However, you should beaware 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 DirectoryServices cannot migrate them. You may receive an error, or AS/400 DirectoryServices may assume that the files have already been migrated.


|||

|||||

|

|

|||||

||||||

||

|||||||||

|||||


v AS/400 Directory Services migrates directory data to the V4R5 format the firsttime that you start the server or import an LDIF file. Plan to allow some time forthis migration to complete. Also, be aware that the directory data will requireapproximately twice as much storage space in V4R5 than it required in V4R4.This is because in V4R4 AS/400 Directory Services supported only the IA5character set and saved data in ccsid 37 (single byte format). AS/400 DirectoryServices now supports the full ISO 10646 character set..After you upgrade to V4R5, you should start your server once to migrateexisting data before importing new data. If you try to import data before startingthe 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 intoaccount when creating time stamp entries. Beginning with V4R5, the time zonewill be used in all additions and modifications to the directory. Therefore, whenyou upgrade when you upgrade to V4R5, AS/400 Directory Services adjustsexisting createtimestamp and modifytimestamp attributes to reflect the correcttime zone. It does this by subtracting the time zone that is currently defined onthe AS/400 system from the time stamps that are stored in the directory. Notethat if the current timezone is not the same timezone that was active when theentries were originally created or modified, the new time stamp values will notreflect the original timezone.

If you are upgrading from V4R3 of AS/400 Directory Services to V4R5, you mayneed to perform some additional migration tasks.

Migrating from V4R3 AS/400 Directory Services to a laterrelease

When you upgrade from V4R3 to any later release, you should be aware of thefollowing 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 certificatestores, which are sometimes called key databases, to establish SSL connections. Ifyou used a key ring file with your LDAP directory server previously, the keyring 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 directoryserver, Operations Navigator will alert you to this change. If you choose toconvert the key, it will prompt you to enter some information for the keydatabase, then will make the conversion.The LDAP directory server also used a key ring file for its own SSL connectionsin V4R3. Beginning with V4R4 it uses the system certificate store. If your serverwas set up to use SSL in V4R3, the contents of the key ring file will be migratedto the system certificate store.

v Two stream files have been removed:

The following stream files used by AS/400 Directory Services in V4R3 are nolonger 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 sothat you are not concerned if you notice that they are no longer present on yoursystem.

Also be aware that there may be additional associated with upgrading to thecurrent release from other releases.


|||||||

|||

||||||||||

||

|

|

|||

|||||||||

|||||

||

||

|||

||

Installing and Configuring AS/400 Directory ServicesTo get started using the LDAP directory server on AS/400, you must install theDirectory 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 Services2. Configure the LDAP directory server

If at some point you no longer want to run an LDAP directory server on yourAS/400, you can then uninstall AS/400 Directory Services.

Installing AS/400 Directory ServicesBefore you can configure your Directory server, you must install the DirectoryServices option of OS/400. Directory Services may already be installed on yourAS/400. For information on checking to see what programs are installed on yourAS/400, see the topic ″Verifying system and media software″ in the AS/400Information Center.

To install the Directory Services option, take these steps:1. Insert the CD-ROM that contains OS/400.2. Type GO LICPGM on the AS/400 command line, then press Enter.3. 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 yourLDAP directory server.

Configuring the LDAP directory serverAS/400 Directory Services provides a wizard in Operations Navigator to assist youin configuring the LDAP directory server. Use this wizard when you initiallyconfigure the directory server. You may also use the wizard to reconfigure thedirectory server.

Note: When you use the wizard to reconfigure the directory server, you startconfiguring from scratch. The original configuration is deleted rather thanchanged. The directory data, however, is not deleted. It remains stored inthe QUSRDIRDB library. The change log also remains intact, in theQUSRDIRDCL library.

If you want to start completely from scratch, clear those two libraries beforestarting the wizard.

If you want to change the directory server configuration, but not clear itcompletely, right-click Directory and select Properties. This does not deletethe original configuration.

Before you can configure the directory server, you must have installed theDirectory Services option of OS/400. For information on checking to see whatprograms are installed on your AS/400, see the topic ″Verifying system and media


|

|||||

||

||||

RZAHCVERIFY.HTM

software″ in the AS/400 Information Center. You must have *ALLOBJ and*IOSYSCFG special authorities to configure the server.

To start the Configure Directory Server wizard, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. Right-click Directory and select Configure.

Note: If you have already configured the directory server, click Reconfigurerather than Configure.

Follow the on-screen instructions that the Configure Directory Server wizard givesto configure your LDAP directory server.

Note: You may also want to put the library that stores the directory data in a userauxiliary storage pool (ASP) rather than the system ASP.

When the wizard finishes, your LDAP directory server has a basic configuration. Ifyou are running Lotus Domino on your AS/400, port 389, the default port for theLDAP server, is already in use. You must either change the port that Lotus Dominouses or change the port that AS/400 Directory Services uses. If you want to useanother 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 serverv Enable Secure Sockets Layer (SSL) securityv Set up a referral

Enabling SSL on the LDAP directory serverIf you have Digital Certificate Manager installed on your AS/400, you can useSecure Sockets Layer (SSL) security to protect access to your LDAP directoryserver. Before enabling SSL on the directory server, you may find it helpful to readan overview on using SSL with AS/400 Directory Services.

To use an SSL connection when you administer your LDAP directory server fromOperations Navigator, or to use SSL with the Windows LDAP client, you musthave 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 OperationsNavigator, or from the Network page of the directory server’s 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 tofollow in order to assign a digital certificate to the directory server.


||

RZAHCVERIFY.HTM

RZAHURAZHUDIGITALCERTMNGMNT.HTM

RZAINRZAINLDA.HTM

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

Changing the port that the LDAP directory server usesThe LDAP directory server enabled by AS/400 Directory Services uses thefollowing 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 assigndifferent ports to AS/400 Directory Services.

To change the ports that the LDAP directory server uses, take 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. Enter the appropriate port numbers, then click OK.

Uninstalling AS/400 Directory ServicesIf you no longer wish to run an LDAP directory server on your AS/400, you canremove it by uninstalling the AS/400 Directory Services option of OS/400. Youalso 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 andQGLDPUBE publishing jobs.

To uninstall the AS/400 Directory Services option, take these steps from a 5250session 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, someof the AS/400 Directory Services files, including the schema files, and the librariesthat contain the server’s data and change log, remain on AS/400. You couldreinstall AS/400 Directory Services and begin running the server again. If you aresure that you will not want to run the LDAP directory server in the future, youmay 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 ToolThe IBM SecureWay Directory Management Tool (DMT) provides you with agraphical user interface for managing LDAP directory content. The tasks that youcan perform with the DMT include the following:v Browsing directory schemav Adding, editing, and deleting object classesv Adding, editing, and deleting attributesv Browsing and searching the directory tree


|||||

||||||

|

|

||

|||

|

|

|

|

v Adding, editing, viewing, and deleting entriesv Editing entry RDNs

The DMT is part of the Windows LDAP client that is included with AS/400Directory Services. The client is shipped in an integrated file system directory.

To install the Windows LDAP client, including the DMT, onto a PC, follow thesesteps: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) islocated in the file dparent.htm. This file is copied to the IBM SecureWay Directoryfolder on your PC when you install the client.


|

|

||

|||||||||

|||

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 authorityv *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, andreplicas), connect to the directory with either the administrator DN or another DNthat 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 20v “Checking the status of the directory server” on page 20v “Moving LDAP directory data between systems” on page 20v “Specifying a server for directory referrals” on page 27v “Adding suffixes to the LDAP directory server” on page 27v “Removing suffixes from the directory server” on page 27v “Saving and restoring AS/400 Directory Services information” on page 28v “Managing ownership and access of directory data” on page 28v “Tracking changes to the LDAP directory” on page 29v “Adjusting performance of the LDAP directory server” on page 30

Starting the LDAP directory serverTo start the LDAP directory server, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. Right-click Directory and select Start.

The directory server may take several minutes to start, depending on the speedof your AS/400, and the amount of available memory. The first time you startthe directory server may take several minutes longer than usual, because theserver must create new files. Similarly, when starting the directory server forthe first time after upgrading from an earlier version of AS/400 DirectoryServices, it may take several minutes longer than usual because the server mustmigrate files. You can check the status of the server periodically to see if it hasstarted yet.

Note: The directory server can also be started from a 5250 session by entering thecommand STRTCPSVR *DIRSRV.

Additionally, if you have your directory server configured to start whenTCP/IP starts, you can also start it by entering the STRTCP command.


|

||||||||

Stopping the LDAP directory serverTo stop the LDAP directory server, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. Right-click Directory and select Stop.

The directory server may take several minutes to stop, depending on the speedof your AS/400, the amount of server activity, and the amount of availablememory. You can check the status of the server periodically to see if it hasstopped yet.

Note: The directory server can also be stopped from a 5250 session by entering thecommands ENDTCPSVR *DIRSRV, ENDTCPSVR *ALL, or ENDTCP. ENDTCPSVR *ALLand 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 serverOperations Navigator displays the status of the directory server in the Statuscolumn in the right frame.

To check the status of the directory server, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. 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 theservers, click the View menu and select Refresh.

4. To view more information about the status of the directory server, right-clickDirectory and select Status. This will show you the number of activeconnections, as well as other information such as past and current activitylevels.Besides providing additional information, viewing status through this optioncan save time. You can refresh the status of the directory server without takingthe additional time that is required to check the status of the other TCP/IPservers.

Checking jobs on the LDAP directory serverAt times you may want to monitor specific jobs on the LDAP directory server. Tocheck 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 systemsYour AS/400 Directory Services LDAP server can run independently of otherservers. However, you may find it useful to have it work with other servers. Thiscan include:v “Importing an LDIF file” on page 21v “Exporting an LDIF file” on page 21v “Setting up a new replica of the directory server” on page 21v “Publishing AS/400 information to the directory server” on page 25


Importing an LDIF fileYou can transfer information between different LDAP directory servers by usingLDAP 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 fileYou can transfer information between different LDAP directory servers by usingLDAP Data Interchange Format (LDIF) files, see “LDAP Directory InterchangeFormat” on page 36. You can export all or part of your LDAP directory to an LDIFfile.

To export an LDIF file to the directory server, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. 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 willbe saved to the default directory specified in your AS/400 user profile. Ifyou have not changed your default directory, the default directory is theroot directory.

Notes:

1. Be sure to set authority to the LDIF file to prevent unauthorized access todirectory data. To do this, right-click on the file in Operations Navigator, thenselect 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 afile.

Setting up a new replica of the directory serverYou can set up replicas of the LDAP directory server to directory servers on otherAS/400 systems. AS/400 Directory Services uses the standard LDAP version 3protocol 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 versionof OS/400 as the AS/400 from which you replicate.

You can replicate the directory server to LDAP directory servers that are not onAS/400 systems, provided that they use the same version of the protocol. Beaware, 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 isnot 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 theparts of the directory that will be replicated.

2. Stop the master server.3. (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 fromthe master server.

4. (optional) Move LDAP data to the master server. Skip this step if one of thefollowing 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.

5. Set up the new replica server.6. Set up the master server to have a new replica.7. Make sure the master server is allowing updates:

a. In Operations Navigator, expand the AS/400 on which the master directoryserver 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.

Note: These instructions assume that both the master server and the replicaservers are on AS/400 systems that you manage from Operations Navigatoron the same PC. If you are managing your AS/400 systems from separatePCs, you can move between two PCs to perform this task. If either themaster 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 replicationYou may have existing data on your master LDAP directory server that you wantto add to a new replica server. To do this, you first need to export the directory toan LDIF file. While the LDIF file is exporting, you must prevent the master serverfrom 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 beingexported. 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 disallowdirectory updates, perform these tasks:1. Export the directory to an LDIF file.


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

||

|

2. Transfer the LDIF file to the AS/400 system on which the replica server willrun.

After the LDIF file is transferred to the AS/400 system on which the replica serverwill 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 serverOnce you make an LDAP directory server into a replica server, you can no longerupdate the data on it. If you have existing data on the server that you areconfiguring to be a replica LDAP directory server, you will probably want to moveit to the master server so that it can continue to be maintained. To do this, followthese 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 serverwill 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.


||

|

Setting up the new replicaFollow these steps to set up the new replica server.

Note: The replica server must be configured and stopped before you perform thisprocedure.

1. In Operations Navigator, expand the AS/400 on which the replica directoryserver 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 performsupdates.

10. Click the Password button next to the Name used by master server forupdates field. Enter a password for the master server to use when it logs onto the replica server to perform updates.

Note: You should make note of this password and the name you entered instep 9. You will need them when you set up the master server forreplication.

11. In the Master server URL field, enter the name of the master server in URLformat. If your master server uses a port other than the default, enter this portnumber as part of the URL.

12. Click the Database/Suffixes tab. If the suffix that you want to replicate is noton the list, add it.

13. (optional) If you want to use Secure Sockets Layer (SSL) when replicating, useDigital Certificate Manager to enable SSL for the server. You can start DigitalCertificate Manger from the Network tab. For additional information onenabling SSL on a directory server, see “Enabling SSL on the LDAP directoryserver” on page 15.

14. Click OK.

Setting up the master server to have a new replicaFollow 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 enterconnection 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.


||||||||

||||||||

||

|

13. In the Connect as field, enter the name you specified in step 9 on page 24when you set up the replica server.

14. Click Password and enter the password you specified in step 10 on page 24when you set up the replica server.

15. If you want to use Secure Sockets Layer (SSL) when replicating, use DigitalCertificate Manager to enable SSL for the server. You can start DigitalCertificate Manger from the Network tab. For additional information onenabling SSL on a directory server, see “Enabling SSL on the LDAP directoryserver” on page 15.

16. If your server does not use the default port, enter the port number in the Portfield.

17. If you do not want to update the replica server every time an entry on themaster server changes, select Time. Then specify how often you want themaster 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 replicadirectory 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 serverYou can configure AS/400 to publish certain AS/400 information into an LDAPdirectory server on the same AS/400 or on a different AS/400. AS/400 will thenautomatically publish this information to the LDAP directory server when you useOperations Navigator to change this information on AS/400. You can also publishinformation about computers on your network. Additionally, you can callapplication program interfaces (APIs) from your own programs to publish othertypes of information to the LDAP directory.

Notes:

1. When you configure AS/400 to publish the information type ″Users″ to theLDAP directory server, it automatically exports entries from the systemdistribution directory to the LDAP server. It uses the QGLDSSDD applicationprogram interface (API) to do this. This also keeps the LDAP directorysynchronized with changes that are made in the system distribution directory.For information about the QGLDSSDD API, see the ″OS/400 DirectoryServices″ topic under ″Programming″ in the AS/400 Information Center. Theinformation 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 itincludes QDIRSRV2. You will not be able to publish AS/400 informationotherwise.


||

|||||||||||

|||



3. You can also publish AS/400 information to an LDAP directory server that isnot 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 LDAPdirectory 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.

Tip: If you plan to publish more than one type of information to the samelocation, you can save time by selecting multiple information types toconfigure at one time. Operations Navigator will then use the valuesyou enter when you configure the one information type as defaultvalues when you configure subsequent information types.

4. Click Configure.5. Click the Publish AS/400 information for check box.6. In the Directory server field, enter the name of the LDAP directory server

where you want to publish AS/400 information.7. In the Under DN field, enter the parent distinguished name (DN) where you

want AS/400 information added on the directory server.8. In the Distinguished name field, enter a DN to use when connecting to the

directory server to publish AS/400 information.9. In the Password field, enter the password for the DN you specified in the

previous step.10. If your directory server uses Secure Sockets Layer (SSL), select Secured, using

SSL.11. If your directory server does not use the default port, enter the correct port

number in the Port field.12. Click Verify to ensure that the parent DN exists on the server.

Note: If your directory server uses SSL, you must have enabled OperationsNavigator 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, thenpublishing will not be successful.

13. Click OK.

APIs for publishing AS/400 information to the directory serverAS/400 Directory Services provides built-in support for publishing user (for V4R3and above) and computer (for V4R4 and above) information. These items are listedon the Directory Services page of the system’s Properties dialog. You can useLDAP server configuration and publishing APIs to enable the AS/400 programsthat you write to publish other types of information. These types of informationthen appear on the Directory Services page as well. Like users and computers,they are initially disabled, and you configure them using the same procedure. Theprogram 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 Servicespage, is called the agent name.

The following APIs will allow you to incorporate publishing into your ownprograms:

QgldChgDirSvrAUse the CSVR0500 format and indicate an agent name that is marked as adisabled entry. Examples of agent names are the computers and usersagent names automatically available on the Directory Services page.


RZAINRZAINCAPI.HTM

RZAINRZAINCAPI.HTM

QgldLstDirSvrAUse this API’s LSVR0500 format to list what agents are currently availableon your AS/400 system.

QgldPubDirObjUse 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 referralsTo assign referral servers for the directory server, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. Right-click Directory, then select Properties.5. Click Add.6. 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.comv ldap://test.server.com:400v ldap://9.9.99.255

Note: If the referral server does not use the default port, specify the correctport number as part of the URL, as port 400 is specified in the secondexample above.

7. Click OK.

Adding suffixes to the LDAP directory serverAdding a suffix to the LDAP directory server allows the server to manage that partof the directory tree.

Note: You should not add a suffix that is under another suffix already on theserver. For example, if o=ibm, c=us were a suffix on your server, you shouldnot add ou=rochester, o=ibm, c=us.

To add a suffix to the directory server, take 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.6. In the New suffix field, type the name of the new suffix.7. Click Add.8. Click OK.

Removing suffixes from the directory serverTo remove a suffix from the LDAP directory server, take 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.


||

|

||||||

||||

|

|


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 objectsunder 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 informationAS/400 Directory Services uses the following libraries:v The database library, QUSRIDRDB. This library contains the directory server’s

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 databaselibrary and the objects in it on a regular basis. Save QDIRSRV and the objects in itwhenever you change the directory server configuration or apply ProgramTemporary Fixes (PTFs). Configuration data is also stored in the followingdirectory:/QIBM/UserData/OS400/Dirsrv/

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

See Backup and Recovery, SC41-5304 for information on saving and restoringAS/400 data.

Managing ownership and access of directory dataManaging 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 objectsTo set the ownership properties of directory objects, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. Right-click Directory and select Authority.

If you are not already connected to the directory server, the Connect toDirectory Server dialog appears. Connect as the server administrator or as theowner of the object whose ownership properties you want to work with.

5. From the directory tree, select the object whose ownership properties you wantto work with, then click OK.

Working with the Access Control Lists (ACLs)Working with access control lists (ACLs) includes assigning explicit and implicitACLs to directory objects, adding users to ACLs, removing users from ACLs, andbrowsing directory objects.


|

|||

|

|

||

||

||

|||||

|

||

http://publib.boulder.ibm.com:80/cgi-bin/bookmgr/DOCNUM/SC41-5304

To work with ACLs, take these steps:1. In Operations Navigator, expand Network.2. Expand Servers.3. Click TCP/IP.4. Right-click Directory and select Authority.

If you are not already connected to the directory server, the Connect toDirectory Server dialog appears. Connect as the server administrator or as theowner 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 GroupsTo work with ACL groups, take these steps:1. In Operations Navigator, select Network.2. Select Servers.3. Click TCP/IP.4. Right-click Directory and select ACL Groups.

Tracking changes to the LDAP directoryBeginning with V4R5, you can use the LDAP directory’s change log to keep trackof changes to the directory. The change log is located under the special suffixcn=changelog. It is stored in the /QSYS.LIB/QUSRDIRCL.LIB library.

To enable the change log, 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.6. Select Log directory changes.7. (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 considerspecifying a number of maximum entries. If you do not specify amaximum number of entries, the change log will keep all entries andmay become very large.

The changeLogEntry object class is used to represent the changes applied to thedirectory server. The set of changes is given by the ordered set of all entries withinthe 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 searchon 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 allchange log entries logged on the server:ldapsearch -h ldaphost -D cn=admin -w password -b "cn=changelog" "(changetype=*)"


|||

Adjusting performance of the LDAP directory serverYou can adjust the performance of your LDAP directory server by changing any ofthe 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 LDAPdirectory increases when you increase the number of maximumconnections allowed. You can experiment with different maximumconnection values to determine what value works best for your situation.

To adjust the performance values of the directory server, take 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 Performance tab.

You can also adjust the performance of the directory server by changing thenumber of database connections that the server uses. To change this value, followthese 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.


||||||||

Chapter 5. AS/400 Directory Services concepts and referenceinformation

The following conceptual and reference information will help you to learn aboutand run your AS/400 Directory Services LDAP server:v “LDAP access control lists (ACLs)”v “LDAP Directory Interchange Format” on page 36v “National language support (NLS) considerations” on page 39v “Ownership of LDAP directory objects” on page 39v “LDAP directory referrals” on page 39v “Replica LDAP directory servers” on page 40v “Using Secure Sockets Layer (SSL) security with the LDAP directory server” on

page 40v “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 yourLDAP directory server. For example, an LDAP server on your company Intranetmight contain a telephone directory of company employees. You would probablywant 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 toaccess 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 thoseemployees the president wanted to receive calls from.

With ACLs, you can control who has the authority to add and delete directoryobjects. 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 ableto access her telephone number. She did, however, want all managers to be able toaccess it. In such a case, you could make use of an ACL Group to simplifygranting authority to the managers. ACL groups allow you to grant access tospecific groups of users rather than granting authority on an individual basis. Thisis particularly useful if the same group of people needs access to more than one setof objects. If the same managers that had access to the president’s telephonenumber, for example, later needed access to salary entries, you could reuse theACL 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 anobject’s ACL, you specify which classifications the user can read, write, search, andcompare. 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


|

president’s telephone number, you would give them read access to the ″Normal″attributes in the president’s 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 ACLthat 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 whobind 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 specialDN cn=this. This enables child entries who inherit their ACLs to be automaticallyauthorized to perform operations on their own objects.

Additional information

To administer ACLs through Operations Navigator, you do not need to know thedetails of how AS/400 Directory Services implements ACLs. However, if you wantto specify ACL related attributes when using LDIF files or want to use ACLs withthe LDAP command line utilities, you will need to familiarize yourself with theattributes that ACLs use.

For information on setting up and changing ACLs and ACL groups, follow theselinks:

“Working with the Access Control Lists (ACLs)” on page 28“Working with ACL Groups” on page 29

Access control list (ACL) attributesAccess control lists (ACLs) define access to objects and attributes in the AS/400Directory Services LDAP directory. Each object in a directory contains severalattributes which describe who is allowed to access information within that object.Click one of the following links to see information on that attribute:v aclEntryv aclSourcev aclPropagatev entryOwnerv ownerSourcev 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 theaccess that is allowed to the entry object and to each of its attributes. An aclEntrylists 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).


|||

|||

Scope of protection:

The scope of the protection is based on the following two types of privilegeattributes:

access-IdThe 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 inclasses. Attributes are assigned to attribute classes within the schema files. Thethree user-modifiable attribute classes are:v Normalv Sensitivev Critical

Each of these attribute classes is discrete. That is, access to information in one classdoes not give access to information in any other class. Attributes have a defaultattribute class of ″normal″.

In the following example attribute definition, userPassword has been assignedmembership in the ″critical″ access class, while DN has been assigned membershipin 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 Read an attribute value.

Write Write an attribute.

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

SearchSearch entries with specified attributes.

CompareCompare attributes.

Each of the LDAP access permissions is discrete. One permission does not implyanother permission. If you give a user (access-id) an aclEntry for a particularobject, the user receives that permission. If no permission is given to the user, theuser receives permission based on the object’s ACL, and the bound user receivesthe combined permissions of all listed access groups.

Note: There are two types of LDAP searches. One retrieves both attributes andvalues, and the other retrieves only attributes. In order to retrieve bothattributes and values, a user must have both read and search permission tothe corresponding attributes class.

If the user is not listed on the ACL, and is not a member of any listed accessgroup, 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 thepermission 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 Add objects below this object.v Delete this object.v Read, write, search and compare both normal and sensitive attributes.v 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 withwhich the ACL is associated. The server keeps this attribute, but it may beretrieved for administrative purposes.

aclPropagate attribute:

This ″true″ or ″false″ object attribute specifies whether or not the object’s ACL ispropagated to objects below it in the directory hierarchy. An object without anexplicit ACL receives its ACL from the first propagating ACL above the object inthe directory hierarchy. Propagated ACLs do not accumulate. The scope of apropagated ACL is from the explicitly set propagating ACL down through thedirectory hierarchy until another propagating ACL is found.

Example 1: Propagation

The entry ″ou=deptXYZ, o=IBM, c=US″ has the following explicit ACL:aclPropagate: TrueaclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rscaclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rscaclEntry: group:cn=Anybody:normal:rscaclSource: ou=deptXYZ, o=IBM, c=US


The entry ″cn=personA, ou=deptXYZ, o=IBM, c=US″ has the following implicitACL::aclPropagate: TrueaclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rscaclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rscaclEntry: group:cn=Anybody:normal:rscaclSource: 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 beenset. Therefore, the descendant inherits its ACL from the first ancestor with apropagating ACL, which in this case is ″ou=deptXYZ, o=IBM, c=US″. This isreflected in the aclSource field. The aclEntry and aclPropagate values are identicalto 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: TRUEaclEntry: group:cn=IBMRegs, o=IBM, c=US:normal:rcs:sensitive:rscaclEntry: group:cn=Anybody:normal:rscaclSource: o=IBM, c=US

The entry ″ou=deptXYZ, o=IBM, c=US″ has the following explicit ACL:aclPropagate: FALSEaclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rscaclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM, c=US:object:ad:normal:rwsc:sensitive:rwscaclEntry: group:cn=Anybody:normal:rscaclSource: ou=deptXYZ, o=IBM, c=US

The entry ″cn=personA, ou=deptXYZ, o=IBM, c=US″ has the following implicitACL:aclPropagate: TRUEaclEntry: group:cn=IBMRegs, o=IBM, c=US:normal:rcs:sensitive:rscaclEntry: group:cn=Anybody:normal:rscaclSource: o=IBM, c=US

In this example, a propagating ACL has been set on ″o=IBM, c=US″. On thedescendant ″ou=deptXYZ, o=IBM, c=US″, an explicit ACL has been set whichoverrides 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 firstancestor with a propagating ACL. Because ″ou=deptXYZ, o=IBM, c=US″ has theaclPropagate 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 orgroup specified by entryOwner receives complete access to all of the object’sattributes. In essence, they are the administrator for a particular object.

ownerSource attribute:

The ownerSource attribute reflects the DN with which the owner values areassociated. The server keeps this attribute, but it can be retrieved foradministrative purposes.

ownerPropagate attribute:


Owner propagation works in exactly the same way as ACL propagation works. Bydefault, objects inherit owners through the directory hierarchy, and theirownerPropagate 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=USownerPropagate: TRUEaclPropagate: TRUEaclEntry: group:cn=deptXYZRegs, o=IBM, c=US:normal:rcs:sensitive:rscaclEntry: access-id:cn=personA, ou=deptXYZ, o=IBM,

c=US:object:ad:normal:rwsc:sensitive:rwsc:critical:rscaclEntry: group:cn=Anybody:normal:rscaclSource: ou=deptXYZ, o=IBM, c=USownerSource: 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 normaland sensitive attribute classes. They do not have permission to add or deleteobjects under this object. Nor do they have permission to access any informationor change any information on attributes in the critical class.

PersonA has add and delete permission on the object, read, write, search, andcompare 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 thenormal attribute class only.

AS/400 Directory Services ACL defaults:

AS/400 Directory Services has the following ACL defaults, assuming that theadministrator DN is ″cn=admin, c=US″:entryOwner: access-id:cn=admin, c=USownerPropagate: TRUEaclPropagate: TRUEaclEntry: group:cn=Anybody:normal:rscaclSource: defaultownerSource: default

LDAP Directory Interchange FormatThe LDAP Directory Interchange Format (LDIF) provides you with a simple wayto transfer directory information between LDAP directory servers. LDIF files holdLDAP directory entries in a simple text format. The format of LDIF files thedirectory server uses has changed slightly beginning with V4R5 of AS/400Directory Services. LDIF files consist of a sequence of lines that describe adirectory entry or a set of changes to a directory entry. They cannot describe both.

The general format of an LDIF entry is:version: 1dn: distinguished nameattrtype1: attrvalue1...


||||||

|

||||

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 olderLDIF file format. When the LDIF file is version 1, the content MUST be UTF-8encoded.

v distinguished name is the distinguished name of the directory entryv 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. Ifan 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 thatbegins with a pound-sign (″#″) is a comment line, and must be ignored whenparsing an LDIF file.

Any distinguished name or attribute value that meets one of the followingconditions 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 theattribute name and the value.

External references are in the file:// URL format. There should be colon and lessthan (″:<″) between the attribute type and the external reference value.

Here are some examples of LDIF files:

Example 1: A simple LDAP file with two entriesversion: 1

dn: cn=Barbara Jensen, ou=Rochester, o=Big Company, c=USobjectclass: topobjectclass: personobjectclass: organizationalPersoncn: Barbara Jensencn: Barbara J Jensencn: Babs Jensensn: Jensenuid: bjensentelephonenumber: +1 408 555 1212description: A big sailing fan.

dn: cn=Bjorn Jensen, ou=Rochester, o=Big Company, c=USobjectclass: topobjectclass: personobjectclass: organizationalPersoncn: Bjorn Jensensn: Jensentelephonenumber: +1 408 555 1212description:Babs is a big sailing fan, and travels extensively in search of perfect sailing conditions.title:Product Manager, Rod and Reel Division

Example 2: A file containing a base-64-encoded valueversion: 1

dn: cn=Gern Jensen, ou=Rochester, o=Big Company, c=USobjectclass: top


|

||||

|

|

|

|||

|||||

||

|

|

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

|

|||

objectclass: personobjectclass: organizationalPersoncn: Gern Jensencn: Gern O Jensensn: Jensenuid: gernjtelephonenumber: +1 408 555 1212description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJhc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0IChhIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu

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 entrydn: cn=Fiona Jensen, ou=Rochester, o=Big Company, c=USchangetype: addobjectclass: topobjectclass: personobjectclass: organizationalPersoncn: Fiona Jensensn: Jensenuid: fionatelephonenumber: +1 408 555 1212jpegphoto:< file:///usr/local/directory/photos/fiona.jpg

# Delete an existing entrydn: cn=Robert Jensen, ou=Rochester, o=Big Company, c=USchangetype: delete

# Modify an entry's relative distinguished namedn: cn=Paul Jensen, ou=Rochester, o=Big Company, c=USchangetype: modrdnnewrdn: cn=Paula Jensendeleteoldrdn: 1

The order of entries in the LDIF file is important. To successfully add an entry thatis specified in the LDIF file to an LDAP directory, its parent entry must first existin the directory namespace. In the example above, the second and third entriescould not be added if the first entry did not exist.

Similarly, to import an LDIF file into a server that supports certain suffixes, theLDIF file must have entries for those suffixes. For example, if your server had thesuffix ou=Rochester, o=Big Company, c=US, the LDIF file shown above could beimported. But if your server instead had the suffix o=Big Company, c=US, you musthave an entry for that suffix specified first in the LDIF file, as shown here:dn: o=Big Company, c=USobjectclass: organizationo: Big Company

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


||||||||||

|

||

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

|

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 thefollowing 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) considerationsBeginning with V4R5, both the OS/400 LDAP server and the OS/400 LDAP clientare 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 objectsEach object in your LDAP directory has at least one owner. Object owners have thepower to delete the object. Owners and the server administrator are the only usersthat can change the ownership properties and the access control list (ACL)attributes of an object. Ownership of objects can be either inherited or explicit. Thatis, 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 eachLDAP directory object. Beginning in V4R4, AS/400 Directory Services allows youto specify multiple owners for the same object. Also beginning inV4R4, you canspecify that an object owns itself. To do this you include the special DN cn=this inthe list of object owners. For example, assume that the object cn=A has the ownercn=this. Any user will have owner access to the cn=A object if he connects to theserver as cn=A.

Related procedure:“Working with the ownership properties of directory objects” on page 28

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


||||||||

|

|

|

|




AS/400 Directory Services allows you to use two different types of referrals. Youcan specify default referral servers, where the LDAP server will refer clientswhenever any DN is not in the directory. You can also use your LDAP client toadd entries to the directory server that have the objectClass ″referral″. This allowsyou to specify referrals that are based on what specific DN a client requests.

Note: With AS/400 Directory Services, referral objects must contain only adistinguished name (dn), an objectClass (objectClass), and a referral (ref)attribute. See “ldapsearch utility” on page 48 for an example that illustratesthis restriction.

Referral servers are closely related to replica servers. Because data on replicaservers cannot be changed from clients, the replica refers any requests to changedirectory data to the master server.

Replica LDAP directory serversThe information stored on replica LDAP directory servers is identical to theinformation on your main, or ″master″, LDAP directory server. There are twoprincipal 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 masterserver and the replica servers.

v Replicas provide a backup to the master server. If the master server isunavailable, a replica can still fulfill search requests and provide access todirectory data.

Replica servers are read-only. When an authorized user attempts to change anentry 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 directoryserver

To make communications with your LDAP directory server more secure, AS/400Directory Services can use Secure Sockets Layer (SSL) security.

To use SSL with AS/400 Directory Services, you must have one of theCryptographic Access Provider products (5769AC1, 5769AC2, OR 5769AC3)installed on your AS/400 system. If you want to use SSL from OperationsNavigator, 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 todo 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 OperationsNavigator.

v To use an SSL connection with applications that you create with the Windowsclient application program interfaces (APIs).

SSL is the standard for Internet security.You can use SSL to communicate withLDAP clients, as well as with replica LDAP servers. Beginning with V4R5, you canuse client authentication, in addition to server authentication, to provide additional


|||

security to your SSL connections. Client authentication requires that the LDAPclient present a digital certificate that confirms the client’s identity to the serverbefore a connection is established.

To use SSL, you must have Digital Certificate Manager (DCM), option 34 ofOS/400, installed on your system. DCM provides an interface for you to create andmanage digital certificates and certificate stores. See the documentation for DigitalCertificate Manager for information on digital certificates and on using DCM. Forinformation about SSL on AS/400, see Securing applications with SSL. Forinformation on enabling SSL on your LDAP directory server, see “Enabling SSL onthe LDAP directory server” on page 15.

AS/400 Directory Services and OS/400 journaling supportAS/400 Directory Services uses OS/400 database support to store directoryinformation. AS/400 Directory Services uses commitment control to store directoryentries in the database. This requires OS/400 journaling support.

When the server or the LDIF import tool is started for the first time, the followingare built:v A journalv A journal receiverv 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)

CRTJRNJRN(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 maydictate some differences, including how these objects are managed and the sizethreshold used. You can change journaling command parameters if necessary. For

information on journaling commands, see OS/400 commands .


|||

|||||||

||

|

|

|

|



RZAINOVERVIEW.HTM

RBAM6MST06.HTM

Chapter 6. LDAP command line utilities

AS/400 Directory Services includes five utilities that allow you to perform actionson the LDAP directory server from the QSH shell on AS/400. These utilities usethe LDAP APIs. You can use these utilities from the shell command line or callthem from your programs. You may also find them useful as programmingexamples. When you install the Windows LDAP client that is included withAS/400 Directory Services, you also install code that is very similar to the sourcecode 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 forinformation on using SSL with the command line utilities.

ldapmodify and ldapadd utilitiesThe ldapmodify utility allows you to change entries or add entries to the LDAPdirectory server from the QSH command shell on AS/400. It uses the ldap_modifyapplication program interface (API). The ldapadd utility, which uses the ldap_addAPI, works identically to the ldapmodify utility with the exception that the -a flagis turned on automatically.

Format:

ldapmodify [-a] [-V] [-b] [-c] [-r] [-n] [-v] [-F] [-R] [-C charset] [-d debuglevel] [-Dbinddn] [-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] [-Ncertificatename]

Note: If you do not provide entry information from file through the use of the -foption, the utility will wait to read entries from standard input. To break outof 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 adiagnostic message being written to standard error.

Click here to see examples of using these utilities.


|||

./java/rzahz/qshell.htm

Parameters:

-V Specifies the LDAP version that the utility uses to bind to the LDAPserver. By default, it uses an LDAP V3 connection. To explictlyselect LDAP V3, specify ″-V 3″. Specify ″-V 2″ to run as an LDAPV2 application.

-a Only ldapmodify uses this parameter. It indicates that the utilitywill add entries rather than modifying them. Using this parameteris the same as using ldapadd.

-b Assume that any values that start with a ′/’ are binary values andthat the actual value is in a file whose path is specified in the placewhere values normally appear.

-c Continuous operation mode. Errors are reported, but ldapmodify orldapadd continues with modifications or adds. The default is to exitafter reporting an error.

-r Replace existing values by default.

-n Show what would be done, but do not actually modify entries.Useful for debugging in conjunction with -v.

-v Use verbose mode, with many diagnostics written to standardoutput.

-F Force application of all changes regardless of the contents of inputlines that begin with replica: (by default, replica: lines are comparedagainst the LDAP server host and port in use to decide if areplication log record should actually be applied).

-R Specifies that referrals are not to be automatically followed.

-C charset Specifies that strings supplied as input to the utility are representedin a local character set (charset), and must be converted to UTF-8.Use the -C charset option if the input string codepage is differentfrom the job codepage value. Refer to the documentation for theldap_set_iconv_local_charset() API to see supported charset values.

-d debuglevel Sets the debug level to debuglevel.

-D binddn Use binddn to bind to the LDAP directory. binddn should be astring-represented DN.

-w passwd Use passwd as the password for simple authentication.

-h ldaphost Specify an alternate host on which the LDAP server is running.

-p ldapport Specify an alternate Transmission Control Protocol (TCP) portwhere the LDAP server is listening. The default LDAP port is 389. Ifnot specified and -Z is specified, the default LDAP SSL port 636 isused.

-f file Read the entry modification information from an LDIF file insteadof from standard input. If an LDIF file is not specified, you mustuse standard input to specify the update records in LDIF format.

-Z Use a secure SSL connection to communicate with the LDAP server.The -Z option is only supported by SSL-enabled versions of thistool.

-K keyfile Specify the name of the SSL key database file. If the key databasefile is not in the current directory, specify the fully-qualified keydatabase filename. If the utility cannot locate a key database, it willuse a ″hard-codced″ set of default trusted certificate authority roots.The key database file typically contains one or more certificates ofcertification authorities (CAs) that are trusted by the client. Thesetypes of X.509 certificates are also known as trusted roots. Thisparameter effectively enables the -Z switch.


./apis/ldap_set_iconv_local_charset.html

-P keyfilepw Specify the key database password. This password is required toaccess the encrypted information in the key database file (includingthe private key). If a password stash file is associated with the keydatabase file, the pasword is obtained from the stash file and thisparameter is not required. This parameter is ignored if neither -Znor -K are specified.

-N certificatename Specify the label associated with the client certificate in the keydatabase file. Note that if the LDAP server is configured to performServer Authentication only, a client certificate is not required. If theLDAP server is configured to perform Client and ServerAuthentication, a client certificate is required. certificatename is notrequired if a default certificate/private key pair has been designatedas the default. Similarly, certificatename is not required if there is asingle certificate/private key pair in the designated key databasefile. This parameter is ignored if neither -Z nor -K are specified.

Alternative Input Format:

ldapmodify supports an alternative input format in order to maintain compatibilitywith older versions of the utility. This format consists of one or more entries thatare 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 areadded. If you give the -r command line flag, the default is to replace existingvalues with the new one. Note that it is permissible for a given attribute to appearmore 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 linesand to preserve new lines in the value itself. To remove a value, precede the attrvalue with a dash (-). The equal sign (=) and value should be omitted to removean entire attribute. attr should be preceded by a plus sign (+) to add a value in thepresence of the -r flag.

Examples: ldapmodify and ldapaddExample 1:

If the file /tmp/entrymods exists and has the following contents:dn: cn=Modify Me, o=University of Higher Learning, c=USchangetype: modifyreplace: mailmail: [email protected]: titletitle: Grand Poobah-add: jpegPhotojpegPhoto:< 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″ entry’s mail attribute with the value

[email protected] 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 inputformat:cn=Modify Me, o=University of Higher Learning, [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=USobjectClass: personcn: John Doecn: Johnnysn: Doetitle: Managermail: [email protected]: 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=USchangetype: delete

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

ldapdelete utilityThe ldapdelete utility allows you to delete one or more entries from an LDAPdirectory server. It runs through the QSH command shell on AS/400. It uses theldap_delete application program interface (API).

Format:

ldapdelete [-V] [-n] [-v] [-c] [-R] [-C charset] [-d debuglevel] [-ffile] [-D binddn] [-wpasswd] [-m mechanism] [-O hopcount] [-h ldaphost] [-p ldapport] [-Z] [-K keyfile] [-Pkeyfilepw] [-N certificatename] [dn]...

Note: If you do not provide dn arguments, the ldapdelete command will wait toread a list of DNs from standard input. To break out of the wait, press theSysReq key, then choose 2. End previousrequest.

Diagnostics:



Click here to see examples of using the ldapdelete utility.

Parameters:


-n Show what would be done, but do not actually delete entries.Useful for debugging in conjunction with -v.


-c Continuous operation mode. Errors are reported, but ldapdelete willcontinue with deletions. The default is to exit after reporting anerror.


-C charset Specifies that the distinguished names (DNs) supplied as input tothe ldapdelete utility are represented in a local character set(charset). Use -C charset to override the default, where strings mustbe supplied in UTF-8. Use the -C charset option if the input stringcodepage is different from the job codepage value. Refer to thedocumentation for the ldap_set_iconv_local_charset() API to seesupported charset values.


-f file Read a series of lines from file, performing one LDAP delete foreach line in the file. Each line in the file should contain a singledistinguished name (DN).



-m mechanism Use mechanism specify the SASL mechanism to be used to bind tothe server.The ldap_sasl_bind_s() API will be used. The -mparameter is ignored if -V 2 is set. If -m is not specified, simpleauthentication is used.

-O hopcount Specify hopcount to set the maximum number of hops that the clientlibrary will take when chasing referrals. The default hopcount is 10.









dn Specifies one or more dn arguments. Each dn should be astring-represented DN.

Example: ldapdeleteThe following command will attempt to delete the entry named withcommonName ″Delete Me″ directly below the University of Life organizationalentry :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 utilityThe ldapsearch utility allows you to search for an entry on your LDAP directoryserver the from the QSH command shell on AS/400. It uses the ldap_searchapplication 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 informationin 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 arespecified by attrs and prints the entries and values to standard output. If you donot list any attributes, it returns all attributes.

Format:


|

||

||


RZAIKLDAP.HTM

ldapsearch [-V] [-n] [-v] [-t] [-A] [-B] [-L] [-R] [-C charset] [-d debuglevel] [-F sep] [-ffile] [-D binddn] [-w bindpasswd] [-m mechanism] [-O hopcount] [-h ldaphost] [-pldapport] [-Z] [-K keyfile] [-P keyfilepw] [-N certificatename] [-b searchbase] [-s scope] [-aderef] [-l time limit] [-z size limit] filter [attrs...]

Diagnostics:


Output Format:

If ldapsearch finds one or more entries, it writes each entry to standard output inthe form:Distinguished Name (DN)attributename=valueattributename=valueattributename=value...

Multiple entries are separated with a single blank line. If you use the -F option tospecify a separator character, the output displays that character instead of theequal (=) character. If you use the -t option, the name of a temporary file replacesthe actual value. If you specify the -A option, only the attributename part iswritten.

Click here to see examples of using the ldapsearch utility.

Parameters:


-n Show what would be done, but do not actually perform the search.Useful for debugging in conjunction with -v.


-t Write retrieved values to a set of temporary files. This is useful fordealing with binary values such as jpegPhoto or audio.

-A Retrieve attributes only (no values). This is useful when you justwant to see if an attribute is present in an entry and are notinterested in the specific values.

-B Do not suppress display of binary values. This is useful whendealing with values that appear in alternate characters sets such asISO-8859.1. This option is implied by -L

-L Display search results in LDIF format. This option also turns on the-B option, and causes the -F option to be ignored.



-C charset Specifies that strings supplied as input to the ldapsearch utility arerepresented in a local character set (charset). String input includesthe filter, the bind DN, and the base DN. Similarly, when displayingdata, ldapsearch will convert data received from the LDAP server tothe specified character sUse the -C charset option if the input stringcodepage is different from the job codepage value. Refer to thedocumentation for the ldap_set_iconv_local_charset() API to seesupported charset values. Also, if the -C option and the -L option areboth specified, input is assumed to be in the specified character set,but output from ldapsearch is always preserved in its UTF-8representation, or a base 64-encoded representation of the datawhen non-printable characters are detected. This is the case sincestandard LDIF files only contain UTF-8 (or base 64-encoded UTF-8)representations of string data.


-F sep Use sepas the field separator between attribute names and values.The default separator is ′=’, unless the -L flag has been specified, inwhich case this option is ignored.

-f file Read a series of lines from file, performing one LDAP search foreach line in the file. Each line in the file should contain a singledistinguished name (DN).



-m mechanism Use mechanism to specify the SASL mechanism to be used to bind tothe server.The ldap_sasl_bind_s() API will be used. The -mparameter is ignored if -V 2 is set. If -m is not specified, simpleauthentication is used.



-p ldapport Specify an alternate Transmission Control Protocol (TCP) portwhere the LDAP server is listening. The default LDAP port is 389. Ifnot specified and -Z is specified, the default LDAP Secure SocketsLayer (SSL) port 636 is used.







-b searchbase Use searchbase as the starting point for the search instead of thedefault. If -b is not specified, this utility will examine theLDAP_BASEDN environment variable for a searchbase definition.

-s scope Specify the scope of the search. scope should be one of base, one, orsub to specify a base object, one-level, or subtree search. The defaultis sub.

-a deref Specify how aliases dereferencing is done. deref should be one ofnever, always, search, or find to specify that aliases are neverdereferenced, always dereferenced, dereferenced when searching, ordereferenced only when locating the base object for the search. Thedefault is to never dereference aliases.

-l timelimit Wait at most timelimit seconds for a search to complete.

-z sizelimit Limit the results of the search to at most sizelimit entries. Thismakes it possible to place an upper bound on the number of entriesthat are returned for a search operation.

filter Specifies the name of the filter that the search uses.

attrs... Specifies the attributes that the utility retrieves if the search findsone or more entries. If you do not list any values for attrs, theutility returns all attributes.

Examples: ldapsearchExample 1:

The command ldapsearch "cn=john doe" cn telephoneNumber performs a subtreesearch (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 outputlooks 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=UScn=John Doecn=John Edward Doecn=John E Doe 1cn=John E DoetelephoneNumber=+1 313 555-5432cn=John B Doe, ou=Information Technology Division,ou=Faculty and Staff,ou=People, o=University of Higher Learning, c=UScn=John Doecn=John B Doe 1cn=John B DoetelephoneNumber=+1 313 555-1111

Example 2:

The command ldapsearch -t "uid=jed" jpegPhoto audio performs a subtreesearch using the default search base for entries with user id of ″jed″. The search


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

Example 3:

The command ldapsearch -L -s one -b "c=US" "o=university*" o descriptionperforms a one-level search at the c=US level . This search looks for allorganizations whose organizationName begins with university. The searchdisplays its results in the LDIF format. It retrieves the organizationName attributevalue and the description attribute values and prints them to standard output thatlooks similar to this:dn: o=University of Alaska Fairbanks, c=USo: University of Alaska Fairbanksdescription: Preparing Alaska for a brave new tomorrowdescription: leaf node onlydn: o=University of Colorado at Boulder, c=USo: University of Colorado at Boulderdescription: No personnel informationdescription: Institution of education and researchdn: o=University of Colorado at Denver, c=USo: University of Colorado at Denvero: UCDo: CU/Denvero: CU-Denverdescription: Institute for Higher Learning and Researchdn: o=University of Florida, c=USo: University of Floridao: UFldescription: Shaper of young minds...

Example 4:

As discussed in “LDAP directory referrals” on page 39, AS/400 Directory ServicesLDAP directories may contain referral objects , provided that they contain only thefollowing: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=USref: ldap://System_B:389/cn=Barb Jensen,

ou=Rochester, o=Big Company, c=USobjectclass: referral

All attributes associated with the entry should reside on ’System_B’.

System_B contains an entry:


dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=UScn: Barb Jensenobjectclass: organizationalPersonsn: Jensentelephonenumber: (800) 555 1212

When a client issues a request to ’System_A’, the LDAP server on System_Aresponds 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 onSystem_A contains attributes in addition to dn, objectclass, and ref, the serverignores those attributes (unless you specify the -R flag to indicate not to chasereferrals).

When the client receives a referral response from a server, it issues the requestagain, this time to the server to which the returned URL refers. The new requesthas the same scope as the original request. The results of this search varydepending 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 orbelow '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 thereferral 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 entrydn: 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 entriec=US.


ldapmodrdn utilityThe ldapmodrdn utility allows you to change the Relative Distinguished Name(RDN) of entries on the LDAP directory server. You use it from the QSH commandshell 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] [-wpasswd] [-m mechanism] [-O hopcount] [-h ldaphost] [-p ldapport] [-Z] [-K keyfile] [-Pkeyfilepw] [-N certificatename] [-f file] [dn rdn]

Notes:

1. If you give the command-line arguments dn and rdn, rdn will replace the RDNof 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 ormore 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 waitto read entries from standard input. To break out of the wait, press the SysReqkey, then choose 2. End previous request.

Diagnostics:


Click here to see an example of using the ldapmodrdn utility.

Parameters:


-r Remove old relative distinguished name (RDN) values from theentry. Default is to keep old values.

-n Show what would be done, but do not actually change entries.Useful for debugging in conjunction with -v.


-c Continuous operation mode. Errors are reported, but ldapmodrdnwill continue with modifies. The default is to exit after reporting anerror.


-C charset Specifies that strings supplied as input to the utility are representedin a local character set (charset), and must be converted to UTF-8.Use the -C charset option if the input string codepage is differentfrom the job codepage value. Refer to the documentation for theldap_set_iconv_local_charset() API to see supported charset values.






-m mechanism Use mechanism specify the SASL mechanism to be used to bind tothe server.The ldap_sasl_bind_s() API will be used. The -mparameter is ignored if -V 2 is set. If -m is not specified, simpleauthentication is used.








-f file Read the entry modification information from an LDIF file insteadof from standard input or the command-line (by specifying dn andthe new rdn). Standard input can also be supplied from a file (″<file″).

dn rdn Specify the distinguished name of an entry to rename and the newrelative distinguished name for the entry.

Example: ldapmodrdnAssume that you have already created the text file /tmp/entrymods and that it hasthe following contents:cn=Modify Me, o=University of Life, c=UScn=The New Me


The following command:ldapmodrdn -r -f /tmp/entrymods

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

Notes about using SSL with the LDAP command line utilitiesTo use the Secure Sockets Layer (SSL) features of the command line utilities, youmust have installed Cryptographic Access Provider 40-bit (5769AC1),Cryptographic Access Provider 56-bit (5769AC2), or Cryptographic Access Provider128-bit (5769AC3) on your AS/400.

“Using Secure Sockets Layer (SSL) security with the LDAP directory server” onpage 40 discusses using SSL with the AS/400 Directory Services LDAP server,including managing and creating trusted Certificate Authorities with DigitalCertificate Manager.

Some LDAP servers that the client accesses use only server authentication. Forthese servers, you only need to define one or more trusted root certificates in thecertificate store. With server authentication, the client can be assured that the targetLDAP server has been issued a certificate by one of the trusted CertificateAuthorities (CAs). In addition, all LDAP transactions that flow over the SSLconnection with the server are encrypted. This includes the LDAP credentials thatare supplied on application program interfaces (APIs) that are used to bind to thedirectory server. For example, if the LDAP server is using a high-assuranceVerisign 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 server’sadministrator can supply you with a copy of the server’s 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 clientauthentication 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 acertificate by one of the trusted CAs. In addition, all LDAP transactions thatflow over the SSL connection with the server are encrypted. This includes theLDAP credentials that are supplied on application program interfaces (APIs) thatare used to bind to the directory server.

v Create a key pair and request a client certificate from a CA. After receiving thesigned certificate from the CA, receive the certificate into the key ring file on theclient.


||||

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

|||

||||||

Chapter 7. Troubleshooting AS/400 Directory Services

Unfortunately, even reliable servers such as the AS/400 Directory Services LDAPserver sometimes have problems. When your LDAP directory server has problems,the following information can help you figure out what is wrong and how to fixthe 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 ServicesYou can find return codes for LDAP errors in the ldap.h file, which is located onAS/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 Servicesuses 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 helpyou to know what SQL servers should be started, and what AS/400 DirectoryServices uses them for.

When the LDAP directory server starts normally, it generates messages similar tothe following:

Note: The messages and the number of SQL server jobs started may differ in anyof 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.

System: WARMERSJob . . : QDIRSRV User . . : QDIRSRV Number . . . : 174440

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

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


||

||||

|

|||||

||

|||||

||||||||||

|||||

AS/400 Directory Services uses the next SQL server, 057340/QUSER/QSQSRVR,for LDAP adds, deletes, and modifies. Unless you have changed the number ofconnections in your configurations file, this server is fourth from the end of thislist.

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 hasbeen reclaimed for replication.

AS/400 Directory Services uses the remaining SQL servers for LDAP searches. Onthe directory server’s Database/Suffixes Properties page in Operations Navigatoryou specify the total number of SQL servers that it uses. In the example abovethere are two SQL servers used for LDAP searches, 057166/QUSER/QSQSRVR and057279/QUSER/QSQSRVR.

Monitoring errors and access with the AS/400 DirectoryServices job log

Viewing the job log for your LDAP server can alert you to errors and help you tomonitor 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 Navigator’s right panel.

To view the job log, double-click on Qpjoblog to the left of QDIRSRV in thesame row.

Note: Operations Navigator may be configured to show only spooled files. IfQDIRSRV does not appear on the list, click Printer Output, then chooseInclude from the Options menu. Specify All in the User field, then clickOK.

Note: AS/400 Directory Services uses other system resources to perform sometasks. If an error occurs with one of those resources, the job log will indicatewhere to go for information. In some cases AS/400 Directory Services maynot be able to determine where to look. In those cases, look in theStructured Query Language (SQL) server’s job log to see if the problem wasrelated to SQL servers.

Common LDAP client errorsKnowing the causes of common LDAP client errors can help you to solve problemswith your server. For a complete list of LDAP client error conditions, see the″OS/400 Directory Services″ topic under ″Programming″ in the AS/400Information Center.

The client error messages have the following format:[Failing LDAP operation]:[LDAP client API error conditions]


||||

|||

|||||

||||


Note: The explanation of these errors assumes that the client is communicatingwith an LDAP server on OS/400. A client communicating with a server on adifferent platform might get similar errors, but the causes and resolutionswould most likely be different.

Common messages include the following:v “ldap_search: Timelimit exceeded”v “[Failing LDAP operation]: Operations error”v “ldap_bind: No such object”v “ldap_bind: Inappropriate authentication”v “[Failing LDAP operation]: Insufficient access”v “[AS/400 System]: A remote host refused an attempted connect operation” on

page 60v “[AS/400 System]: Failed to connect to ssl server” on page 60

ldap_search: Timelimit exceededThis 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 doingthis.

v Reduce the activity on the AS/400. You can also reduce the number of activeLDAP client jobs running.

[Failing LDAP operation]: Operations errorSeveral things can generate this error. To get information about the cause of thiserror for a particular instance, look at the QDIRSRV and Structured QueryLanguage (SQL) server job logs as described in “Basic troubleshooting procedurefor AS/400 Directory Services” on page 57.

ldap_bind: No such objectA common cause of this error is a that a user makes a typing mistake whenperforming an operation. Another common cause is when the LDAP clientattempts to bind with a DN that does not exist. This often occurs when the userspecifies what he or she mistakenly thinks is the administrator DN. For example,the user may specify QSECOFR or Administrator, when the actual administrator DNmay be something like ″cn=Administrator″.

For details about the error, look at the QDIRSRV job log as described in “Basictroubleshooting procedure for AS/400 Directory Services” on page 57.

ldap_bind: Inappropriate authenticationThis error is usually generated when the client attempts to bind with a passwordthat is not valid. To obtain detail about the error, look at the QDIRSRV job log asdescribed in “Basic troubleshooting procedure for AS/400 Directory Services” onpage 57.

[Failing LDAP operation]: Insufficient accessThis error is usually generated when the binding DN does not have authority todo 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 “Basictroubleshooting procedure for AS/400 Directory Services” on page 57.

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

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 theDirectory Services server started successfully, the message ″Directory Servicesserver started successfully″ will be in the QDIRSRV job log.

[AS/400 System]: Failed to connect to ssl serverThis error occurs when the LDAP server rejects the client connection because asecure socket connection cannot be established. This can occur when the CertificateManagement support rejects the client’s attempt to connect to the server. UseDigital Certificate Manager to make sure that your certificates are set up properly,then try to connect again.


��

Printed in U.S.A.

as400 ldap

Documents

v4r5 as400 directory

directory serversaving

directory serverspecifying

v4r3 as400 directory

os400 ldap directory

replica ldap directory

ldap operation

ldap version