906 lines
31 KiB
HTML
906 lines
31 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Synchronize System Distribution Directory to LDAP (QGLDSSDD)</title>
|
|
<!-- Begin Header Records ========================================== -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
|
<!-- This file has undergone html cleanup on 2/21/02 by JET -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<h2>Synchronize System Distribution Directory to LDAP (QGLDSSDD)</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="50%">Option</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">LDAP user ID</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(1024)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">LDAP user ID password</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(128)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">No longer used</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(1024)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">No longer used</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(128)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">Error Code</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Default Public Authority: *EXCLUDE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li>Local users</li>
|
|
|
|
<li>Remote users that have been added to the local system and have a Simple
|
|
Mail Transfer Protocol (SMTP) address</li>
|
|
</ul>
|
|
|
|
<p>The system distribution directory users that are not published are:</p>
|
|
|
|
<ul>
|
|
<li>Shadowed users</li>
|
|
|
|
<li>Remote users that do not have a SMTP address</li>
|
|
</ul>
|
|
|
|
<p>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 <a href="#HDRUSENOTE">
|
|
Usage Notes</a> for the procedures for setting up the Directory Services
|
|
property page.</p>
|
|
|
|
<p>If you are using SSL, the SSL key database information is configured using
|
|
Digital Certificate Manager. See <a href="#HDRUSENOTE">Usage Notes</a> for
|
|
information on accessing the Digital Certificate Manager.</p>
|
|
|
|
<p>When using a V4R4 or later iSeries Navigator client to publish users to a
|
|
V4R4 or later 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 iSeries 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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <a href="#HDRDNCN">Distinguished Name (dn) and Common Name
|
|
(cn)</a> for more information.</p>
|
|
|
|
<p>Note that if changes are made in the LDAP directory, these changes are not
|
|
synchronized back to the system distribution directory.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<ol>
|
|
<li>Add the user-defined field QREPL QLDAP to the system distribution
|
|
directory. This needs to be done only once per system.
|
|
|
|
<pre>
|
|
CHGSYSDIRA USRDFNFLD((QREPL QLDAP *ADD *DATA 4))
|
|
</pre>
|
|
</li>
|
|
|
|
<li>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.
|
|
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>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.</li>
|
|
</ol>
|
|
|
|
<p>As an administrator, you must understand some additional items that are
|
|
needed to synchronize the system distribution directory to LDAP. These include
|
|
the following:<br>
|
|
<br>
|
|
</p>
|
|
|
|
<ul>
|
|
<li>inetOrgPerson and publisher object classes used in synchronization.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>How the system distribution directory fields map to LDAP attributes.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>What is a distinguished name and common name and why they are important for
|
|
synchronization.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>How the i5/OS user profile field is used in LDAP.</li>
|
|
</ul>
|
|
|
|
<p>See <a href="http://www.ibm.com/servers/eserver/iseries/ldap/ldapfaq.htm">Directory
|
|
Services (LDAP): Question and Answers</a><img src="www.gif" width="18" height="15" alt="Link outside Information Center">
|
|
for additional information on publishing users.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>inetOrgPerson and publisher Object Class</h3>
|
|
|
|
<p>If your LDAP server is not on i5/OS, 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 <a href="http://www.ibm.com/servers/eserver/iseries/ldap/schema">SecureWay Directory
|
|
Schema</a><img src="www.gif" width="18" height="15" alt="Link outside Information Center">
|
|
for documentation on the inetOrgPerson and publisher object class.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>System Distribution Directory to LDAP Mapping</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="bottom" colspan="2"><em>Table 1: System Distribution
|
|
Directory Fields Mapped to LDAP Attributes</em></th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="left" valign="top">System Distribution Directory Field</th>
|
|
<th align="left" valign="top">LDAP Attribute</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">User profile</td>
|
|
<td align="left" valign="top">UID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Descriptions</td>
|
|
<td align="left" valign="top">description</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Last name</td>
|
|
<td align="left" valign="top">sn (surname), cn (common name)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">First name</td>
|
|
<td align="left" valign="top">givenName, cn (common name)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Preferred name</td>
|
|
<td align="left" valign="top">cn (common name)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Full name</td>
|
|
<td align="left" valign="top">cn (common name)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">User ID</td>
|
|
<td align="left" valign="top">cn (common name)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Department</td>
|
|
<td align="left" valign="top">departmentNumber</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Job title</td>
|
|
<td align="left" valign="top">title</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Telephone number 1 & 2</td>
|
|
<td align="left" valign="top">telephoneNumber</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">FAX telephone number</td>
|
|
<td align="left" valign="top">facsimileTelephoneNumber</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Office</td>
|
|
<td align="left" valign="top">roomNumber</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Address lines 1-4</td>
|
|
<td align="left" valign="top">registeredAddress</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">SMTP name</td>
|
|
<td align="left" valign="top">mail</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li>Last name: If last name is blank, then the user ID is used in the LDAP
|
|
directory for the surname (sn) attribute.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDNCN">Distinguished Name (dn) and Common Name (cn)</a></h3>
|
|
|
|
<p>LDAP uses the distinguished name (dn) as the key for the user. For the
|
|
system distribution directory entries in LDAP, the <strong>distinguished
|
|
name</strong> is the common name (cn) combined with the distinguished name that
|
|
LDAP is being published to.</p>
|
|
|
|
<p>The user will have the following common names in LDAP. The first nonblank
|
|
one will be used in the distinguished name:</p>
|
|
|
|
<ol>
|
|
<li>'First name' 'Middle Name' 'Last name'</li>
|
|
|
|
<li>'Preferred name' 'Last name'</li>
|
|
|
|
<li>'Full name'</li>
|
|
|
|
<li>'UserID'</li>
|
|
</ol>
|
|
|
|
<p>For example, if a user has the following field values in the system
|
|
distribution directory,</p>
|
|
|
|
<ul>
|
|
<li>First name: Jonathan</li>
|
|
|
|
<li>Middle name: T.</li>
|
|
|
|
<li>Preferred name: John</li>
|
|
|
|
<li>Last name: Smith</li>
|
|
|
|
<li>Full name: Smith, John T.</li>
|
|
|
|
<li>User ID: JSMITH</li>
|
|
</ul>
|
|
|
|
<p>the user will have the following common names (cn):</p>
|
|
|
|
<ul>
|
|
<li>cn=Jonathan T. Smith</li>
|
|
|
|
<li>cn=John Smith</li>
|
|
|
|
<li>cn="Smith, John T."</li>
|
|
|
|
<li>cn=JSMITH</li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><strong>Attention:</strong> 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.</p>
|
|
|
|
<p>This API can run on other i5/OS 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
|
|
i5/OS 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 i5/OS 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.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>User Profile (UID) for i5/OS Users</h3>
|
|
|
|
<p>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 i5/OS, the UID attribute is used to
|
|
see if that user exists on the i5/OS. The password is verified with the
|
|
password that is passed from the client.</p>
|
|
|
|
<p>If you are publishing the system distribution directory information to a
|
|
different i5/OS or to a system that is not an i5/OS, 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:</p>
|
|
|
|
<pre>
|
|
ldapmodify -h ldapserver -f /path/filename
|
|
-D cn=Admin -w password
|
|
</pre>
|
|
|
|
<p>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:</p>
|
|
|
|
<pre>
|
|
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
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<p>*ALLOBJ and *IOSYSCFG special authority is required to use this API.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Option</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>The option to use for publishing system distribution directory information
|
|
to the LDAP directory. The valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ALL</em></td>
|
|
<td align="left" valign="top">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
|
|
iSeries Navigator. These users will be placed in the LDAP tree under the
|
|
distinguished name that is specified in the Directory Services dialog. See <a
|
|
href="#Header_3">Table 1</a> for information concerning the system distribution
|
|
directory fields that will be used in the LDAP directory.
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CHG</em></td>
|
|
<td align="left" valign="top">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.
|
|
|
|
<p>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.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*END</em></td>
|
|
<td align="left" valign="top">End the synchronization of the system
|
|
distribution directory to LDAP.
|
|
|
|
<p>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,</p>
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*END 'LDAPuserID' 'LDAPpassword' 0 0 0)
|
|
</pre>
|
|
|
|
<p>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,</p>
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*END 0 0 0 0 0)
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*RESET</em></td>
|
|
<td align="left" valign="top">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.
|
|
|
|
<p>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,</p>
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*RESET 0 0 0 0 0)
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><strong>LDAP user ID</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1024)
|
|
|
|
<p>The LDAP user ID that has administrator authority to add, change, and remove
|
|
entries in the LDAP entry. The valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CFG</em></td>
|
|
<td align="left" valign="top">Use the configured LDAP user ID that can be
|
|
specified when publishing users (using iSeries 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.
|
|
|
|
<p>See <a href="#HDRUSENOTE">Usage Notes</a> 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.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>A null-terminated string
|
|
containing the LDAP user ID that has administrator authority to add, change,
|
|
and remove entries in the LDAP entry.</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"></td>
|
|
<td align="left" valign="top">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.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>LDAP user ID password</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(128)
|
|
|
|
<p>The password for the LDAP user ID. The valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CFG</em></td>
|
|
<td align="left" valign="top">Use the configured LDAP user ID password that can
|
|
be specified when publishing users (using iSeries Navigator). Specify *CFG if
|
|
kerberos authentication was configured.
|
|
|
|
<p>See <a href="#HDRUSENOTE">Usage Notes</a> 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.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>A null-terminated string
|
|
containing the password for the LDAP user ID.</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"> </td>
|
|
<td valign="top">Specify a zero-length string if the LDAP server does not
|
|
require authority checking or the option value *RESET is specified.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>No longer used (Formerly 'Key database file')</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1024)
|
|
|
|
<p>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 <a href="#HDRUSENOTE">Usage Notes</a> below
|
|
for more information on Digital Certificate Manager.</p>
|
|
</dd>
|
|
|
|
<dt><strong>No longer used (Formerly 'Key database password')</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(128)
|
|
|
|
<p>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 <a href="#HDRUSENOTE">Usage Notes</a> below
|
|
for more information on Digital Certificate Manager.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error code parameter</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><strong>Note:</strong> 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.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRUSENOTE">Usage Notes</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Synchronization Procedure</h3>
|
|
|
|
<p>A procedure of synchronizing the system distribution directory with an LDAP
|
|
directory is as follows:</p>
|
|
|
|
<ol>
|
|
<li>The Directory Services property page for the LDAP server to publish to must
|
|
be set up. Use iSeries 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 iSeries Navigator or system is prior to V4R4, then just
|
|
the Directory Services properties are set and no list is displayed.
|
|
|
|
<p>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.</p>
|
|
|
|
<p>See the <a href="../rzahy/rzahyrzahywelpo.htm">Directory Services (LDAP)</a>
|
|
topic for more information on using iSeries Navigator to configure the system
|
|
properties for Directory Services.</p>
|
|
|
|
<p>Configuring the Directory Services property also can be done using the
|
|
Change Directory Server Attributes (QgldChgDirSrvA) API.</p>
|
|
</li>
|
|
|
|
<li>If you are synchronizing the system distribution directory to an LDAP
|
|
server that is not on an i5/OS, 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 <a href=
|
|
"http://www.ibm.com/servers/eserver/iseries/ldap/schema">SecureWay Directory
|
|
Schema</a><img src="www.gif" width="18" height="15" alt=
|
|
"Link outside Information Center"> for documentation on the inetOrgPerson and
|
|
publisher object class.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Ensure the TCP/IP host and domain name are set. Use the Change TCP/IP
|
|
Domain (CHGTCPDMN) command and prompt by using F4.</li>
|
|
|
|
<li>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.</li>
|
|
|
|
<li>If you need SSL certificate information configured, it is configured using
|
|
Digital Certificate Manager. You can get to Digital Certificate Manager from
|
|
iSeries Navigator under 'Network - Internet - Digital ID'.</li>
|
|
|
|
<li>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.
|
|
|
|
<p>Call the Synchronize System Distribution Directory to LDAP API with the *ALL
|
|
option value. For example, from the command line, type:</p>
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*ALL 'LDAPuserID' 'LDAPpassword' 0 0 0)
|
|
</pre>
|
|
|
|
<p>The LDAP user ID must have sufficient authority to add, change, and remove
|
|
entries in the LDAP directory.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*ALL *CFG *CFG 0 0 0)
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>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).
|
|
|
|
<p>Periodically call QGLDSSDD to synchronize the LDAP directory with the system
|
|
distribution directory. The command to synchronize the LDAP directory is:</p>
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*CHG 'LDAPuserID' 'LDAPpassword' 0 0 0)
|
|
</pre>
|
|
|
|
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:
|
|
|
|
<pre>
|
|
CALL PGM(QSYS/QGLDSSDD)
|
|
PARM(*CHG *CFG *CFG 0 0 0)
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
|
<td align="left" valign="top">Literal value cannot be changed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0301 E</td>
|
|
<td align="left" valign="top">Error encountered when accessing the LDAP
|
|
Directory Server.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0302 E</td>
|
|
<td align="left" valign="top">Input option *CHG currently unavailable.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0303 E</td>
|
|
<td align="left" valign="top">The caller of this API must have &1 and
|
|
&2 special authorities.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0304 E</td>
|
|
<td align="left" valign="top">Unable to export the system distribution
|
|
directory entry &1 &2 to the LDAP Directory Server.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0305 C</td>
|
|
<td align="left" valign="top">Synchronization between the system distribution
|
|
directory and the LDAP directory server completed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0309 E</td>
|
|
<td align="left" valign="top">Value not valid for input parameter &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0310 E</td>
|
|
<td align="left" valign="top">Error occurred with QGLDSSDD API. Reason code
|
|
&1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0311 E</td>
|
|
<td align="left" valign="top">Input parameter &1 is not valid. Reason code
|
|
&2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">GLD0312 D</td>
|
|
<td align="left" valign="top">Error encountered when setting up a secure
|
|
connection to an LDAP server. The error number is &1.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V4R3
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
|
<a href="unix.htm">UNIX-Type APIs</a> |
|
|
<a href="aplist.htm">APIs by category</a> </td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|