597 lines
20 KiB
HTML
597 lines
20 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>ldap_server_locate()-- Locate Suitable LDAP Servers</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. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- File Edited April 2001 -->
|
||
|
|
<!-- This file has undergone html cleanup on 2/19/02 by JET -->
|
||
|
|
<!--End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
|
||
|
|
<h2>ldap_server_locate()-- Locate Suitable LDAP Servers</h2>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<div class="box" style="width: 80%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <ldap.h>
|
||
|
|
|
||
|
|
typedef struct LDAP_Server_Request {
|
||
|
|
int search_source; /* Source for server info */
|
||
|
|
#define LDAP_LSI_CONF_DNS 0 /* Config first, then DNS (def)*/
|
||
|
|
#define LDAP_LSI_CONF_ONLY 1 /* Local Config file only */
|
||
|
|
#define LDAP_LSI_DNS_ONLY 2 /* DNS only */
|
||
|
|
char *conf_filename; /* pathname of config file */
|
||
|
|
int reserved; /* Reserved, set to zero */
|
||
|
|
char *service_key; /* Service string */
|
||
|
|
char *enetwork_domain; /* eNetwork domain (eDomain) */
|
||
|
|
char **name_servers; /* Array of name server addrs */
|
||
|
|
char **dns_domains; /* Array of DNS domains */
|
||
|
|
int connection_type; /* Connection type */
|
||
|
|
#define LDAP_LSI_UDP_TCP 0 /* Use UDP, then TCP (default)*/
|
||
|
|
#define LDAP_LSI_UDP 1 /* Use UDP only */
|
||
|
|
#define LDAP_LSI_TCP 2 /* Use TCP only */
|
||
|
|
int connection_timeout; /* connect timeout (seconds) */
|
||
|
|
char *DN_filter; /* DN suffix filter */
|
||
|
|
unsigned char reserved2[64]; /* reserved fields, set to 0 */
|
||
|
|
} LDAPServerRequest;
|
||
|
|
|
||
|
|
|
||
|
|
typedef struct LDAP_Server_Info {
|
||
|
|
char *lsi_host; /* LDAP server's hostname */
|
||
|
|
unsigned short lsi_port; /* LDAP port */
|
||
|
|
char *lsi_suffix; /* Server's LDAP suffix */
|
||
|
|
char *lsi_query_key; /* service_key[.edomain]*/
|
||
|
|
char *lsi_dns_domain; /* Publishing DNS domain */
|
||
|
|
int lsi_replica_type;/* master or replica */
|
||
|
|
#define LDAP_LSI_MASTER 1 /* LDAP Master */
|
||
|
|
#define LDAP_LSI_REPLICA 2 /* LDAP Replica */
|
||
|
|
int lsi_sec_type; /* SSL or non-SSL */
|
||
|
|
#define LDAP_LSI_NOSSL 1 /* Non-SSL */
|
||
|
|
#define LDAP_LSI_SSL 2 /* Secure Server */
|
||
|
|
unsigned short lsi_priority; /* Server priority */
|
||
|
|
unsigned short lsi_weight; /* load balancing weight */
|
||
|
|
char *lsi_vendor_info; /* vendor information */
|
||
|
|
char *lsi_info; /* LDAP Info string */
|
||
|
|
struct LDAP_Server_Info *prev; /* linked list previous ptr */
|
||
|
|
struct LDAP_Server_Info *next; /* linked list next ptr */
|
||
|
|
} LDAPServerInfo;
|
||
|
|
|
||
|
|
|
||
|
|
int ldap_server_locate (
|
||
|
|
LDAPServerRequest *<em>server_request</em>,
|
||
|
|
LDAPServerInfo **<em>server_info_listpp</em> );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Library Name/Service Program: QSYS/QGLDCLNT<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>ldap_server_locate()</strong> API is used to locate one or more
|
||
|
|
suitable LDAP servers. In general, an application will use the <strong>
|
||
|
|
ldap_server_locate()</strong> API as follows:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Prior to connecting to an LDAP server in the enterprise, use <strong>
|
||
|
|
ldap_server_locate()</strong> to obtain a list of one or more LDAP servers that
|
||
|
|
have been published in DNS (or in the local configuration file). Typically an
|
||
|
|
application can simply use the default request settings (by passing a NULL for
|
||
|
|
the LDAPServerRequest parameter). By default, the API will look for server
|
||
|
|
information in the local configuration file first
|
||
|
|
(/QIBM/UserData/OS400/DirSrv/ldap_server_info.conf), then move on to DNS if the
|
||
|
|
local configuration file doesn't exist (or has expired).</li>
|
||
|
|
|
||
|
|
<li>Once the application has obtained the list of servers, it should walk the
|
||
|
|
list, using the first server that meets its needs. This will maximize the
|
||
|
|
advantage that can be derived from using the priority and weighting scheme
|
||
|
|
implemented by the administrator. The application may not want to use the first
|
||
|
|
server in the list for several reasons:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The client needs to specifically connect using SSL (or non-SSL). In this
|
||
|
|
case, the server needs to walk the list until it finds a server entry with the
|
||
|
|
appropriate type of security type. Note that an LDAP server may be listening on
|
||
|
|
both an SSL and non-SSL port. In this case, the server will have two entries in
|
||
|
|
the server list.</li>
|
||
|
|
|
||
|
|
<li>The client specifically needs to connect to a Master (or Replica).</li>
|
||
|
|
|
||
|
|
<li>The client needs to connect to a server that supports a particular suffix.
|
||
|
|
NOTE that the list of server's returned in the list can be filtered by
|
||
|
|
specifying DN_filter, which filters out servers that do not have a suffix under
|
||
|
|
which the DN resides.</li>
|
||
|
|
|
||
|
|
<li>There is some other characteristic associated with the desired server
|
||
|
|
(perhaps defined in the ldapinfo string).</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Once the client has selected a server, it then issues the <a href=
|
||
|
|
"ldap_init.htm">ldap_init()</a> or <a href="ldap_ssl_init.htm">
|
||
|
|
ldap_ssl_init()</a> API. If the selected server is unavailable, the application
|
||
|
|
is free to move down the list of servers until it either finds a suitable
|
||
|
|
server it can connect to, or the list is exhausted.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Object Authorities</strong></dt>
|
||
|
|
|
||
|
|
<dd>The caller must have Execute (*X) authority to each directory in the path
|
||
|
|
name preceding the name of the configuration file
|
||
|
|
(/QIBM/UserData/OS400/DirSrv). The caller must have Read (*R) authority to the
|
||
|
|
configuration file (ldap_server_info.conf).</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>server_request</em></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Specifies a pointer to an LDAPServerRequest structure. If the
|
||
|
|
default behavior is desired for all possible input parameters, simply set <em>
|
||
|
|
server_request</em> to NULL. Otherwise, supply the address of the
|
||
|
|
LDAPServerRequest structure, which contains the following fields:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td width="20%" valign="top"><em>search_source</em></td>
|
||
|
|
<td width="80%" valign="top">Specifies where to find the server information.
|
||
|
|
|
||
|
|
<p>The options are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>First access the local LDAP DNS configuration file. If the file is not
|
||
|
|
found, or the file does not contain information for a combination of the
|
||
|
|
service_key, eDomain and any of the DNS domains (as specified by the
|
||
|
|
application), then access DNS.</li>
|
||
|
|
|
||
|
|
<li>Search the local LDAP DNS configuration file only.</li>
|
||
|
|
|
||
|
|
<li>Search DNS only.</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>conf_filename</em></td>
|
||
|
|
<td valign="top">Specifies an alternative configuration filename. Specify NULL
|
||
|
|
to use the default filename and location.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>service_key</em></td>
|
||
|
|
<td valign="top">Specifies the search key (that is, the service name string) to be
|
||
|
|
used when obtaining a list of SRV, "pseudo-SRV TXT" or CNAME alias records from
|
||
|
|
DNS. If not specified, the default is "ldap". Administrators are encouraged to
|
||
|
|
use the ldap default when setting up information in DNS servers, to maximize a
|
||
|
|
client application's ability to find LDAP servers that have been published in
|
||
|
|
DNS.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>enetwork_domain</em></td>
|
||
|
|
<td valign="top">Indicates that LDAP servers belonging to the specified
|
||
|
|
eNetwork domain are to be located. The criteria for searching DNS to locate the
|
||
|
|
appropriate LDAP server(s) is constructed by concatenating the following
|
||
|
|
information:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>search_key (defaults to ldap)</li>
|
||
|
|
|
||
|
|
<li>enetwork_domain</li>
|
||
|
|
|
||
|
|
<li>DNS domain</li>
|
||
|
|
|
||
|
|
<li>"tcp"</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
For example, if:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The default search_key of ldap is used</li>
|
||
|
|
|
||
|
|
<li>The eNetwork domain is sales5</li>
|
||
|
|
|
||
|
|
<li>The client's default DNS domain is midwest.acme.com</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
Then the DNS "value" used to search DNS for the set of LDAP servers belonging
|
||
|
|
to the sales5 domain is ldap.sales5.midwest.acme.com.tcp.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"></td>
|
||
|
|
<td valign="top">If enetwork_domain is set to zero, the following steps are
|
||
|
|
taken to determine the enetwork_domain:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The locally configured default, if set, will be used (as set with the</li>
|
||
|
|
|
||
|
|
<li><a href="ldap_enetwork_domain_set.htm">ldap_enetwork_domain_set()</a>
|
||
|
|
API).</li>
|
||
|
|
|
||
|
|
<li>If a locally configured default is not set, then a platform-specific value
|
||
|
|
is used. On Windows NT, the user's logon domain is used.</li>
|
||
|
|
|
||
|
|
<li>If a platform-specific eNetwork domain is not defined, then the eNetwork
|
||
|
|
domain component in the DNS "value" is omitted. In the above example, this
|
||
|
|
would result in the following string being used:
|
||
|
|
ldap.midwest.acme.com.tcp.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
If enetwork_domain is set to a NULL string, then the eNetwork domain component
|
||
|
|
in the DNS "value" is omitted. This might be useful for finding a default
|
||
|
|
eNetwork domain (when a specific edomain name is not known).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>name_servers</em></td>
|
||
|
|
<td valign="top">Specifies an array of one or more string representations of
|
||
|
|
DNS name server IP address (in dotted decimal format; for example, "122.122.33.49"). If
|
||
|
|
not specified, the locally configured DNS name server(s) will be used.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>dns_domains</em></td>
|
||
|
|
<td valign="top">Specifies an array of one or more DNS domain names. If not
|
||
|
|
specified, the local DNS domain configuration is used.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"></td>
|
||
|
|
<td valign="top">Note that domain names supplied here can take the following
|
||
|
|
forms:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>austin.ibm.com (standard DNS format)</li>
|
||
|
|
|
||
|
|
<li>cn=fred, ou=accounting, dc=austin, dc=ibm, dc=com</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>With respect to providing a domain name, these are equivalent. Both result
|
||
|
|
in a domain name of "austin.ibm.com". This approach makes it easier for an
|
||
|
|
application to locate LDAP servers to which it needs to bind (based on a user
|
||
|
|
name space mapped into the DNS name space).</p>
|
||
|
|
|
||
|
|
<p>DNS DOMAINS and CONFIGURATION FILE</p>
|
||
|
|
|
||
|
|
<p>The local configuration file may contain server information for combinations
|
||
|
|
of the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Service key (typically set to ldap)</li>
|
||
|
|
|
||
|
|
<li>eNetwork domain</li>
|
||
|
|
|
||
|
|
<li>DNS domains</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>When the application sets search_source to LDAP_LSI_CONFIG_DNS, the
|
||
|
|
ldap_server_locate() API will attempt to find server information in the
|
||
|
|
configuration file for the designated service key, eNetwork domain and DNS
|
||
|
|
domain(s).</p>
|
||
|
|
|
||
|
|
<p>If the configuration file does not contain information that matches this
|
||
|
|
criteria, the locator API will search DNS, using the specified service key,
|
||
|
|
eNetwork domain and DNS domain(s). For example:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The application supplies the following three DNS domains:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>austin.ibm.com</li>
|
||
|
|
|
||
|
|
<li>raleigh.ibm.com</li>
|
||
|
|
|
||
|
|
<li>miami.ibm.com</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>plus, the application uses the default service key (that is, ldap and specifies
|
||
|
|
sales for the eNetwork domain).</li>
|
||
|
|
|
||
|
|
<li>The configuration file contains server information for austin.ibm.com and
|
||
|
|
miami.ibm.com (with the default service key and eNetwork domain of sales).</li>
|
||
|
|
|
||
|
|
<li>The search_source parameter is set to LDAP_LSI_CONFIG_DNS, which indicates
|
||
|
|
that both the configuration file and DNS are to be used if necessary.</li>
|
||
|
|
|
||
|
|
<li>The locator API will build a single ordered list of server entries, with
|
||
|
|
the following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Server entries for the austin.ibm.com DNS domain, as extracted from the
|
||
|
|
configuration file.</li>
|
||
|
|
|
||
|
|
<li>Server entries for the raleigh.ibm.com DNS domain, as obtained from DNS
|
||
|
|
over the network.</li>
|
||
|
|
|
||
|
|
<li>Server entries fo rthe miami.ibm.com DNS domain, as extracted from the
|
||
|
|
configuration file.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>In other words, the resulting list of servers will contain all the
|
||
|
|
austin.ibm.com servers first, followed by the raleigh.ibm.com servers, followed
|
||
|
|
by the miami.ibm.com servers. Within each grouping of servers (by DNS domain),
|
||
|
|
the entries are sorted by priority and weight.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>connection_type</em></td>
|
||
|
|
<td valign="top">Specifies the type of connection to use when communicating
|
||
|
|
with the DNS name server. The following options are supported:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Use UDP first. It no response is received, or data truncation occurs, then
|
||
|
|
use TCP.</li>
|
||
|
|
|
||
|
|
<li>Only use UDP.</li>
|
||
|
|
|
||
|
|
<li>Only use TCP.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>If set to zero, the default is to use UDP first (then TCP).</p>
|
||
|
|
|
||
|
|
<p>UDP is the preferred connection type, and typically performs well. You might
|
||
|
|
want to consider using TCP/IP if:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The amount of data being returned will not fit in the 512-byte UDP
|
||
|
|
packet.</li>
|
||
|
|
|
||
|
|
<li>The transmission and receipt of UDP packets turns out to be unreliable.
|
||
|
|
This may depend on network characteristics.</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>connection_timeout</em></td>
|
||
|
|
<td valign="top">Specifies a timeout value when querying DNS (for both TCP and
|
||
|
|
UDP). If LDAP_LSI_UDP_TCP is specified for connection_type and a response is
|
||
|
|
not received in the specified time period for UDP, TCP will be attempted. A
|
||
|
|
value of zero results in an infinite timeout. When the LDAPServerRequest
|
||
|
|
parameter is set to NULL, the default is ten seconds. When passing the
|
||
|
|
LDAPServerRequest parameter, this parameter should be set to a non-zero value
|
||
|
|
if an indefinite timeout is not desired.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>DN_filter</em></td>
|
||
|
|
<td valign="top">Specifies a Distinguished Name to be used as a filter, for
|
||
|
|
selecting candidate LDAP servers based on the server's suffix (or suffixes). If
|
||
|
|
the most significant portion of the DN is an exact match with a server's suffix
|
||
|
|
(after normalizing for case), an LDAPServerInfo structure is returned for the
|
||
|
|
server/suffix combination. If it doesn't match, an LDAPServerInfo structure is
|
||
|
|
not returned for the server/suffix combination.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>reserved2</em></td>
|
||
|
|
<td valign="top">Represents a reserved area for future function, which should
|
||
|
|
be initialized to zero.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>server_info_listpp</em></dt>
|
||
|
|
|
||
|
|
<dd>(output) Specifies the address that will be set to point to a linked list
|
||
|
|
of LDAPServerInfo structures. Each LDAPServerInfo structure defined in the list
|
||
|
|
contains server information obtained from either:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>DNS</li>
|
||
|
|
|
||
|
|
<li>Local configuration</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Upon successful return from <strong>ldap_server_locate()</strong>, <em>
|
||
|
|
server_info_listpp</em> points to a linked list of LDAPServerInfo structures.
|
||
|
|
The LDAPServerInfo structure (as defined above), contains the following
|
||
|
|
fields:</p>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top"><em>lsi_host</em></td>
|
||
|
|
<td width="85%" valign="top">Fully-qualified hostname of the target server
|
||
|
|
(NULL-terminated string).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_port</em></td>
|
||
|
|
<td valign="top">Integer representation of the LDAP server's port.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_suffix</em></td>
|
||
|
|
<td valign="top">String that specifies a supported suffix for the LDAP server
|
||
|
|
(NULL-terminated string).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_query_key</em></td>
|
||
|
|
<td valign="top">Specifies the The eNetwork domain to which the LDAP server
|
||
|
|
belongs, prefixed by the service key. For example, if service key is ldap and
|
||
|
|
eNetwork domain is sales, then lsi_query_key would be set to ldap.sales. If the
|
||
|
|
server is not associated with an eNetwork domain (as published in DNS), then
|
||
|
|
lsi_query_key consists solely of the service key value.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_dns_domain</em></td>
|
||
|
|
<td valign="top">DNS domain in which the LDAP server was published. For
|
||
|
|
example, the DNS search may have been for ldap.sales.tcp.austin.ibm.com, but
|
||
|
|
the resulting server(s) has a fully-qualified DNS host name of
|
||
|
|
ldap2.raleigh.ibm.com. In this example, lsi_host would be set to
|
||
|
|
ldap2.raleigh.ibm.com whilst lsi_dns_domain would be set to austin.ibm.com. The
|
||
|
|
actual domain in which the server was "published" may be of interest,
|
||
|
|
particularly when multiple DNS domains are configured (or supplied as
|
||
|
|
input).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_replica_type</em></td>
|
||
|
|
<td valign="top">Specifies the type of server, LDAP_LSI_MASTER or
|
||
|
|
LDAP_LSI_REPLICA. If set to zero, the type is unknown.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_sec_type</em></td>
|
||
|
|
<td valign="top">Specifies the port's security type, LDAP_LSI_NOSSL or
|
||
|
|
LDAP_LSI_SSL. This value is derived from the "ldap" or "ldaps" prefix on the
|
||
|
|
LDAP URL. If the LDAP URL is not defined, the security type is unknown and
|
||
|
|
lsi_sectype is set to zero.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_priority</em></td>
|
||
|
|
<td valign="top">The priority value obtained from the SRV RR (or the
|
||
|
|
"pseudo-SRV" TXT RR). Set to zero if unknown or not available.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_weight</em></td>
|
||
|
|
<td valign="top">The weight value obtained from the SRV RR (or the "pseudo-SRV"
|
||
|
|
TXT RR). Set to zero if unknown or not available.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_vendor_info</em></td>
|
||
|
|
<td valign="top">NULL-terminated string obtained from the ldapvendor TXT RR (if
|
||
|
|
defined). May be used to identify the LDAP server vendor/version
|
||
|
|
information.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>lsi_info</em></td>
|
||
|
|
<td valign="top">NULL-terminated information string obtained from the ldapinfo
|
||
|
|
TXT RR (if defined). If not defined, lsi_info is set to NULL. This information
|
||
|
|
string can be used by the LDAP or network administrator to publish additional
|
||
|
|
information about the target LDAP server.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>LDAP_SUCCESS</strong></dt>
|
||
|
|
|
||
|
|
<dd>if the request was successful.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>another LDAP error code</strong></dt>
|
||
|
|
|
||
|
|
<dd>if the request was not successful.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>If <strong>ldap_server_locate()</strong> is not successful, an error code
|
||
|
|
will be returned. See <a href="ldap_error_condt.htm">LDAP Client API Error
|
||
|
|
Conditions</a> for possible LDAP error code values.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<p>The following message may be sent from this function.</p>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="3">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">CPF3CF2 E</td>
|
||
|
|
<td width="85%" valign="top">Error(s) occurred during running of
|
||
|
|
ldap_server_locate API.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="ldap_init.htm">ldap_init()</a> -- Perform an LDAP initialization
|
||
|
|
operation.</li>
|
||
|
|
|
||
|
|
<li><a href="ldap_server_conf_save.htm">ldap_server_conf_save()</a> -- Store
|
||
|
|
server information into local configuration.</li>
|
||
|
|
|
||
|
|
<li><a href="ldap_server_free_list.htm">ldap_server_free_list()</a> -- Free the
|
||
|
|
list of LDAP servers.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V4R5
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<table align="center" cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"dirserv1.htm">LDAP APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|