Synchronize System Distribution Directory to LDAP (QGLDSSDD)

Required Parameter Group:

1 Option Input Char(10)
2 LDAP user ID Input Char(1024)
3 LDAP user ID password Input Char(128)
4 No longer used Input Char(1024)
5 No longer used Input Char(128)
6 Error code I/O Char(*)

Threadsafe: No

The Synchronize System Distribution Directory to LDAP (QGLDSSDD) API publishes system distribution directory entries to an LDAP directory and keeps the LDAP directory synchronized with changes made in the system distribution directory. The following users from the system distribution directory are published:

Local users
Remote users that have been added to the local AS/400 system and have a Simple Mail Transfer Protocol (SMTP) address

The system distribution directory users that are not published are:

Shadowed users
Remote users that do not have a SMTP address

The Directory Services product needs to be installed on your system to run this API. This product is option 32 under the base operating system.

The Directory Services property page must be set up. In V4R4 and later, users are automatically published when you set up users in the Directory Services property page for the LDAP server to publish under. Prior to V4R4, this api (QGLDSSDD) must be called regularly to publish the users because publishing users is not automatic prior to V4R4. See Usage Notes for the procedure of setting up the Directory Services property page.

If you are using SSL, the SSL key database information is configured using Digital Certificate Manager. See Usage Notes for information on accessing the Digital Certificate Manager.

When using a V4R4 or later AS/400 Operations Navigator client to publish users to a V4R4 or later AS/400 server, the following no longer applies because this is done automatically. The synchronization is restricted to one LDAP server and one distinguished name to publish to. If you need to change the LDAP server or distinguished name that the system distribution directory information gets published to, first end the synchronization (using option value *END). Then change the LDAP server attributes from the AS/400 Operations Navigator or from the Change Directory Server Attributes (QgldChgDirSrvA) API. You can then use option *ALL to initialize all the system distribution directory data to the new LDAP server or distinguished name.

Before users can be published, the host and domain name must be set using the Change TCP/IP Domain (CHGTCPDMN) command. The keywords that must be set are HOSTNAME and DMNNAME.

Also, before users can be published, the SMTP information must be configured using the Change SMTP Attributes (CHGSMTPA) command. This command is used to set the user ID delimiter value when a user does not have an SMTP name. The user ID delimiter value can be the default value or one of the other values allowed.

LDAP uses the distinguished name (dn) as the key for the user. For the system distribution directory entries in LDAP, the distinguished name is the common name (cn) combined with the distinguished name that LDAP is being published to. See Distinguished Name (dn) and Common Name (cn) for more information.

Note that if changes are made in the LDAP directory, these changes are not synchronized back to the system distribution directory.

Some entries are automatically prevented from being published to LDAP. They are the *ANY system distribution directory entries and some other entries that are IBM-supplied starting with Q (QSECOFR, QDOC, QSYS, QDFTOWN, QUSER for example). A specific user can be prevented from being published to LDAP by doing the following:

Add the user-defined field QREPL QLDAP to the system distribution directory. This only needs to be done once per system.
```
CHGSYSDIRA USRDFNFLD((QREPL QLDAP *ADD *DATA 4))
```
Specify *NO as the value for the QREPL QLDAP user-defined field for those users that you do not want to replicate to LDAP. Any other value or absence of the QREPL QLDAP user-defined field will replicate the user. It is recommended that you either leave the QREPL QLDAP value blank or specify *YES if you want the user to be replicated.
For example, using Work with Directory Entries (WRKDIRE), option 1 to add a user or option 2 to change a user, press the F20 key to specify user-defined fields. When using the ADDDIRE or CHGDIRE commands, specify USRDFNFLD((QREPL QLDAP *NO)) to prevent the user from being replicated.
If the user is already replicated to LDAP, and *NO is specified in the QREPL QLDAP user-defined field, then the user will be deleted from the LDAP directory. Likewise, if the value of the QREPL QLDAP user-defined field is changed to anything but *NO, then the user will be added to the LDAP directory.

As an administrator, you will need to understand some additional items that are needed to synchronize the system distribution directory to LDAP. These include the following:

inetOrgPerson and publisher object classes used in synchronization.
How the system distribution directory fields map to LDAP attributes.
What is a distinguished name and common name and why they are important for synchronization.
How the AS/400 user profile field is used in LDAP.

inetOrgPerson and publisher Object Class

If your LDAP server is not on an AS/400, you must ensure that the inetOrgPerson and publisher object classes are defined in the schema file of the server. The inetOrgPerson object class is used in LDAP to store the system distribution directory information. The publisher object class requires a new attribute, publisherName. Documentation on the inetOrgPerson and publisher object class can be found in the AS/400 Information Center (under Networking). The AS/400 Information Center is located at the following URL:

http://publib.boulder.ibm.com/html/as400/infocenter.htm

System Distribution Directory to LDAP Mapping

The system distribution directory entry is published to the LDAP directory by using the inetOrgPerson object class. Figure 0-1 describes the mapping of system distribution directory fields to attributes of the inetOrgPerson object class.

Figure 0-1. System Distribution Directory Fields Mapped to LDAP Attributes

System Distribution Directory Field LDAP Attribute
User profile uid
Descriptions description
Last name sn (surname), cn (common name)
First name givenName, cn (common name)
Preferred name cn (common name)
Full name cn (common name)
User ID cn (common name)
Department departmentNumber
Job title title
Telephone number 1 & 2 telephoneNumber
FAX telephone number facsimileTelephoneNumber
Office roomNumber
Address lines 1-4 registeredAddress
SMTP name mail

If the field is blank in the system distribution directory, then the attribute is not created in LDAP for that user, with the following exceptions:

Last name: If last name is blank, then the user ID is used in the LDAP directory for the surname (sn) attribute.
SMTP name: When a user has a SMTP name, the SMTP userID (SMTPAUSRID) and SMTP domain (SMTPDMN), or SMTP route (SMTPRTE) is used in the following format: SMTPAUSRID@SMTPDMN or SMTPRTE if they just have a route. For local users, if the SMTP name is blank, then the User ID and address fields are used for the mail attribute in the format 'UserID?Address@Domain'. Domain is the value specified on the Change TCP/IP Domain (CHGTCPDMN) command and the '?' is the default SMTP User ID delimiter value specified on the Change SMTP Attributes (CHGSMTPA) command.

Distinguished Name (dn) and Common Name (cn)

LDAP uses the distinguished name (dn) as the key for the user. For the system distribution directory entries in LDAP, the distinguished name is the common name (cn) combined with the distinguished name that LDAP is being published to.

The user will have the following common names in LDAP. The first nonblank one will be used in the distinguished name:

'First name' 'Middle Name' 'Last name'
'Preferred name' 'Last name'
'Full name'
'UserID'

For example, if a user has the following field values in the system distribution directory,

First name: Jonathan
Middle name: T.
Preferred name: John
Last name: Smith
Full name: Smith, John T.
User ID: JSMITH

the user will have the following common names (cn):

cn=Jonathan T. Smith
cn=John Smith
cn="Smith, John T."
cn=JSMITH

If the distinguished name that LDAP is being published to is 'ou=chicago,o=acme,c=us', then the distinguished name of this user is 'cn=Jonathan T. Smith,ou=chicago,o=acme,c=us' using the first cn in the list. The cn value is enclosed in quotation marks if it contains a comma, pound sign, plus sign, equal sign, less than or greater than sign, or a semicolon. Leading blanks from the system distribution directory fields are removed for the cn value. For example, if the first name is ' Jane', the cn value will use 'Jane'. Also, the system distribution directory field values containing quotation marks will not be used when deriving the cn values as described above.

Attention: If you have two users in the system distribution directory that will resolve to the same distinguished name, they will overlay each other in the LDAP directory. Sometimes overlaying names is what you want if you are merging multiple AS/400 system distribution directories into one LDAP directory. If you have different users with the same name, ensure they have different distinguished names to prevent overlaying each other.

This API can run on other AS/400 systems to synchronize the system distribution directory on those systems to the same LDAP server and distinguished name being published to. If you have the same user on multiple AS/400 systems, they will become one user in the LDAP directory. The distinguished name (dn) identifies the user. Note that you can run this API from multiple AS/400 systems to different directory servers or to the same directory server, but different distinguished name that LDAP is being published to. You may want to do this if you would like to ensure that information from different system distribution directories does not overlay each other.

User Profile (uid) for AS/400 Users

For local users, the user profile field is used to set the uid attribute in the LDAP directory. This API does not publish AS/400 passwords for security reasons. Therefore, when the LDAP server is on an AS/400, the uid attribute is used to see if that user exists on the AS/400. The password is verified with the password that is passed from the client.

If you are publishing the system distribution directory information to a different AS/400 or to a system that is not an AS/400, then you will need to set the userPassword attribute for those users that you want to access the LDAP directory. You would set the userPassword attribute for the user after you use the QGLDSSDD API to publish the system distribution directory users. The following shows a client command from a UNIX shell that is used to set the userPassword attribute of two users:

ldapmodify -h ldapserver -f /path/filename
           -D cn=Admin -w password

The ldapserver is the server name that was configured in the Directory Services system property. The /path/filename file contains the distinguished name and password for the users. An example file with two user entries would be:

dn:cn=Jonathan T. Smith,ou=chicago,o=acme,c=us
userPassword:secret
 
dn:cn=Barb Jones,ou=chicago,o=acme,c=us
userPassword:secret

Required Parameter Group

Option

INPUT; CHAR(10)

The option to use for publishing system distribution directory information to the LDAP directory.

The valid values are:

*ALL

All the local users and all the remote users that have been added from this system and that have an SMTP name will be replicated from the system distribution directory to the LDAP directory. The LDAP directory is on the LDAP server specified in the Directory Services dialog of the AS/400 Operations Navigator. These users will be placed in the LDAP tree under the distinguished name that is specified in the Directory Services dialog. See Figure 0-1 as to what system distribution directory fields will be used in the LDAP directory.

The *ALL option value also sets up the necessary AS/400 objects needed to synchronize the system distribution directory changes to the LDAP directory after the LDAP directory is replicated.

You must request the *ALL option value first, but it can be specified more than once. For example, to reload the LDAP directory, you would use the *CHG option value to send any pending changes to the LDAP directory followed by the *ALL option value. If you change which LDAP server or distinguished name you want the system distribution directory entries to be replicated to, you can use the *ALL option value to replicate to that server or distinguished name.

*CHG

The system distribution directory entries that were added, changed, removed, or renamed since the *ALL or previous *CHG option value was used are updated in the LDAP directory.

Changes made to the system distribution directory users in the LDAP directory are overwritten by changes made in the system distribution directory on the AS/400 for the attributes listed above. All other attributes of inetOrgPerson that are changed in LDAP by using an LDAP client are not overwritten by the *CHG option value.

*END

End the synchronization of the system distribution directory to LDAP.

If the LDAP user ID is passed in, then this first synchronizes any changes from the system distribution directory to the LDAP directory since the last synchronization request. For example,

CALL PGM(QDIRSRV/QGLDSSDD)
   PARM(*END 'LDAPuserID' 'LDAPpassword' 0 0 0)

If the LDAP user ID is not passed in, then the synchronization is just ended and the changes left in the queue from the last synchronization request are not published. For example,

CALL PGM(QDIRSRV/QGLDSSDD)
     PARM(*END 0 0 0 0 0)

The users in the LDAP directory where publishing is being ended are not deleted. They are left in the LDAP directory. Changes made to the system distribution directory after publishing is ended are no longer queued.

To start replication again after this value is used, call this API with the *ALL option value. A *CHG option value will result in an error.

*RESET

Ensures that all the AS/400 objects exist for this replication function and clears the queue that keeps track of the changes made to the system distribution directory.

Specify zero for the LDAP user ID, LDAP user ID password, key database file, and key database password when you use this value. For example,

CALL PGM(QDIRSRV/QGLDSSDD)
     PARM(*RESET 0 0 0 0 0)

LDAP user ID

INPUT; CHAR(1024)

The LDAP user ID that has administrator authority to add, change, and remove entries in the LDAP entry.

The valid values are:

*CFG

Use the configured LDAP user ID that can be specified when publishing users (using AS/400 Operations Navigator).

See Usage Notes for the procedure of configuring the Directory Services property page. If the Directory Services property page is not configured, and the *CFG value is passed, then error GLD0310 with reason code 12 is signalled.

A null-terminated string containing the LDAP user ID that has administrator authority to add, change, and remove entries in the LDAP entry.

An example user ID is cn=Admin. Specify a zero-length string if the LDAP server does not require authority checking or the option value *RESET is specified.

LDAP user ID password

INPUT; CHAR(128)

The password for the LDAP user ID.

The valid values are:

*CFG

Use the configured LDAP user ID password that can be specified when publishing users (using AS/400 Operations Navigator).

A null-terminated string containing the password for the LDAP user ID.

Specify a zero-length string if the LDAP server does not require authority checking or the option value *RESET is specified.

No longer used (Used to be 'Key database file')

INPUT; CHAR(1024)

Specify zero (0) as a placeholder for this parameter as it is no longer used. If a value is specified, it will be ignored for compatibility reasons. If you need SSL key database information configured, it is now configured using Digital Certificate Manager. See Usage Notes below for more information on Digital Certificate Manager.

No longer used (Used to be 'Key database password')

INPUT; CHAR(128)

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see .

Note: All character data is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, the data is assumed to be represented in the default CCSID of the job.

Usage Notes

If the system distribution directory field values for two users result in the same distinguished name, then these names will overlay each other in the LDAP directory. To ensure this does not happen when not intended, you must have unique names for your users before you synchronize the system distribution directory to an LDAP directory.

Use the Convert SMTP Names (CVTNAMSMTP) command if you have not already done so to convert the Simple Mail Transfer Protocol (SMTP) fields to the system distribution directory. The SMTP information is loaded when the option value *ALL is used from this API. However, if you do not do CVTNAMSMTP, then when you change the SMTP information using the Work with Names for SMTP (WRKNAMSMTP) command, then those changes do not go to the LDAP directory. After you use the CVTNAMSMTP command, the SMTP name is in the system distribution directory in the user-defined fields SMTPAUSRID SMTP, SMTPDMN SMTP, and SMTPRTE SMTP. When these fields are updated by using the system distribution directory commands (WRKDIRE, ADDDIRE, CHGDIRE), then LDAP is kept synchronized. If you cannot do CVTNAMSMTP, then the other option is to periodically use the option value *ALL to reload the LDAP directory to update all the system distribution directory information including the SMTP information.

Synchronization Procedure

A procedure of synchronizing the system distribution directory with an LDAP directory is as follows:

First ensure the Directory Services product is loaded on your system. From the command line, type: GO LICPGM, then take option 10. This product is option 32 under the base operating system.
The Directory Services property page for the LDAP server to publish to must be set up. Use AS/400 Operations Navigator, select 'Properties' of the system, and then 'Directory Services'. In V4R4 and later, Directory Services will bring up a list of AS/400 information to publish. Select 'Users' from this list to configure this information. If your AS/400 Operations Navigator or AS/400 system is prior to V4R4, then just the Directory Services properties are set and no list is displayed.
The LDAP server to publish to must be specified and exist. The distinguished name to publish under must be specified and must be one that the server supports. All the users in the system distribution directory will be placed under the distinguished name (DN) specified.
See LDAP documentation in the AS/400 Information Center (under Networking) for more information on using the AS/400 Operations Navigator to configure the system properties for Directory Services.
Configuring the Directory Services property can also be done using the Change Directory Server Attributes (QgldChgDirSrvA) API.
If you are synchronizing the system distribution directory to an LDAP server that is not on an AS/400, then you need to ensure that the inetOrgPerson and publisher object classes are defined in the schema file for the server. The publisher object class requires a new attribute, publisherName, so ensure publisherName is also defined in a schema file. Documentation on the inetOrgPerson and publisher object class is found in the AS/400 Information Center (under Networking)
Ensure the TCP/IP host and domain name are set. Use the Change TCP/IP Domain (CHGTCPDMN) command and prompt by using F4.
Use Change SMTP Attribute (CHGSMTPA) command to set the user ID delimiter value. You can keep the default set to '?'. Ensure you press Enter so that the SMTP attributes are created.
If you need SSL certificate information configured, it is configured using Digital Certificate Manager. You can get to Digital Certificate Manager from the AS/400 Operations Navigator under 'Network - Internet - Digital ID'.
If you are on V4R4 or later, and selected 'Users' in the list when configuring Directory Services property page, then the system distribution directory users will automatically be published to LDAP and you will not need to do the following step. You could optionally call it to reinitialize system distribution directory data to an LDAP server if needed.
Call the Synchronize System Distribution Directory to LDAP API with the *ALL option value. For example, from the command line, type:
```
CALL PGM(QDIRSRV/QGLDSSDD)
     PARM(*ALL 'LDAPuserID' 'LDAPpassword' 0 0 0)
```
The LDAP user ID must have sufficient authority to add, change, and remove entries in the LDAP directory.
If you have the LDAP user ID and password configured in the Directory Services property page, you can invoke the API using *CFG. For example, from the command line, type:
```
CALL PGM(QDIRSRV/QGLDSSDD)
     PARM(*ALL *CFG *CFG  0 0 0)
```
For security reasons, it is recommended that you call this API using the *CFG option if the call is being logged in a job log.
If you are on V4R4 or later, and selected 'Users' in the list when configuring Directory Services property page, then the system distribution directory users will automatically be published to LDAP and you will not need to do the following step (although you can optionally call it manually).
Periodically call QGLDSSDD to synchronize the LDAP directory with the system distribution directory. The command to synchronize the LDAP directory is:
```
CALL PGM(QDIRSRV/QGLDSSDD)
     PARM(*CHG 'LDAPuserID' 'LDAPpassword' 0 0 0)
```
If you have the LDAP user ID and password configured in the Directory Services property page, you can invoke the API using *CFG. For example, from the command line, type:
```
CALL PGM(QDIRSRV/QGLDSSDD)
     PARM(*CHG *CFG *CFG  0 0 0)
```
For security reasons, it is recommended that you call this API using the *CFG option if the call is being logged in a job log.
The CL program can be run from a job schedule entry to automatically run with scheduled frequency. Use the Add Job Schedule Entry (ADDJOBSCDE) command or the Work with Job Schedule Entries (WRKJOBSCDE) command to automatically schedule jobs.

Error Messages

Top | LDAP APIs List
APIs by category

[Information Center Home Page | Feedback ]

[Legal | AS/400 Glossary]