Synchronize System Distribution Directory to LDAP (QGLDSSDD)

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 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 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 procedures for 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.

If you use a V4R4 or later System i™ Navigator client to publish users to a V4R4 or later system, 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 System i 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.

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:

1. Add the user-defined field QREPL QLDAP to the system distribution directory. This needs to be done only once per system.

   CHGSYSDIRA USRDFNFLD((QREPL QLDAP *ADD *DATA 4))
   

2. 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.

3. 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 must 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 IBM^® i user profile field is used in LDAP.

See Directory Services (LDAP): Questions and Answers for additional information on publishing users.

inetOrgPerson and publisher Object Class

If your LDAP server is not on IBM i, 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. See IBM LDAP Directory Schema for documentation on the inetOrgPerson and publisher object class.

System Distribution Directory to LDAP Mapping

The system distribution directory entry is published to the LDAP directory by using the inetOrgPerson object class. The following table describes the mapping of system distribution directory fields to attributes of the inetOrgPerson object class.

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:

1. 'First name' 'Middle Name' 'Last name'
2. 'Preferred name' 'Last name'
3. 'Full name'
4. '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 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 IBM i 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 IBM i 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 IBM i 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 IBM i Users

For local users, the user profile field is used to set the UID attribute in the LDAP directory. This API does not publish passwords for security reasons. Therefore, when the LDAP server is on an IBM i, the UID attribute is used to see if that user exists on the IBM i. 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 IBM i or to a system that is not an IBM i, 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
changetype: modify
replace: userPassword
userPassword:secret
 
dn:cn=Barb Jones,ou=chicago,o=acme,c=us
changetype: modify
replace: userPassword
userPassword:secret

Authorities and Locks

*ALLOBJ and *IOSYSCFG special authority is required to use this API.

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 System i Navigator. These users will be placed in the LDAP tree under the distinguished name that is specified in the Directory Services dialog. See Table 1 for information concerning the system distribution directory fields that will be used in the LDAP directory. The *ALL option value also sets up the necessary 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 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(QSYS/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(QSYS/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 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(QSYS/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 System i Navigator). To use kerberos authentication, you must configure publishing users to authenticate using kerberos. When *CFG is specified for LDAP user ID, then depending on what has been configured to authenticate for users will be used whether that is an administrator ID and password or kerberos. 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. If a value is passed in other than *CFG and kerberos authentication was configured, then error GLD0310 will occur.
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 System i Navigator). Specify *CFG if kerberos authentication was configured. 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. If a value is passed in other than *CFG and kerberos authentication was configured, then error GLD0310 will occur.
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 (Formerly '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 (Formerly 'Key database password')

INPUT; CHAR(128)

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.

Error code

I/O; CHAR(*)

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

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. If, however, you do not do CVTNAMSMTP when you change the SMTP information using the Work with Names for SMTP (WRKNAMSMTP) command, 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:

1. The Directory Services property page for the LDAP server to publish to must be set up. Use System i Navigator, select 'Properties' of the system, and then 'Directory Services'. In V4R4 and later, Directory Services will bring up a list of information to publish. Select 'Users' from this list to configure this information. If your System i Navigator or 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 must exist. The distinguished name to publish under must be specified and must be one the server supports. All the users in the system distribution directory will be placed under the distinguished name (DN) that is specified.

   See IBM Tivoli^® Directory Server (LDAP) for more information about using System i Navigator to configure the system properties for Directory Services.

   Configuring the Directory Services property also can be done using the Change Directory Server Attributes (QgldChgDirSrvA) API.

2. If you are synchronizing the system distribution directory to an LDAP server that is not on an IBM i, 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 be sure publisherName is also defined in a schema file. See IBM LDAP Directory Schema for documentation on the inetOrgPerson and publisher object class.
   
   
3. Ensure the TCP/IP host and domain name are set. Use the Change TCP/IP Domain (CHGTCPDMN) command and prompt by using F4.
4. Use Change SMTP Attribute (CHGSMTPA) command to set the user ID delimiter value. You can keep the default set to '?'. Be sure you press Enter so the SMTP attributes are created.
5. If you need SSL certificate information configured, it is configured using Digital Certificate Manager. You can get to Digital Certificate Manager from System i Navigator under 'Network - Internet - Digital ID'.
6. 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(QSYS/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 call the API using *CFG. For example, from the command line, type:

   CALL PGM(QSYS/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.

7. 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(QSYS/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 call the API using *CFG. For example, from the command line, type:

   CALL PGM(QSYS/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

[ Back to top | UNIX-Type APIs | APIs by category ]