ldap_server_locate()-- Locate Suitable LDAP Servers

#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  *server_request,
       LDAPServerInfo    **server_info_listpp );

The ldap_server_locate() API is used to locate one or more suitable LDAP servers. In general, an application will use the ldap_server_locate() API as follows:

• Prior to connecting to an LDAP server in the enterprise, use ldap_server_locate() 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).
• 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:
  • 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.
  • The client specifically needs to connect to a Master (or Replica).
  • 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.
  • There is some other characteristic associated with the desired server (perhaps defined in the ldapinfo string).
• Once the client has selected a server, it then issues the ldap_init() or ldap_ssl_init() 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.

Authorities and Locks

Object Authorities

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

Parameters

server_request

(Input) Specifies a pointer to an LDAPServerRequest structure. If the default behavior is desired for all possible input parameters, simply set server_request to NULL. Otherwise, supply the address of the LDAPServerRequest structure, which contains the following fields:

search_source	Specifies where to find the server information. The options are: 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. Search the local LDAP DNS configuration file only. Search DNS only.
conf_filename	Specifies an alternative configuration filename. Specify NULL to use the default filename and location.
service_key	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.
enetwork_domain	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: search_key (defaults to ldap) enetwork_domain DNS domain "tcp" For example, if: The default search_key of ldap is used The eNetwork domain is sales5 The client's default DNS domain is midwest.acme.com 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.
	If enetwork_domain is set to zero, the following steps are taken to determine the enetwork_domain: The locally configured default, if set, will be used (as set with the ldap_enetwork_domain_set() API). 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. 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. 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).
name_servers	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.
dns_domains	Specifies an array of one or more DNS domain names. If not specified, the local DNS domain configuration is used.
	Note that domain names supplied here can take the following forms: austin.ibm.com (standard DNS format) cn=fred, ou=accounting, dc=austin, dc=ibm, dc=com 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). DNS DOMAINS and CONFIGURATION FILE The local configuration file may contain server information for combinations of the following: Service key (typically set to ldap) eNetwork domain DNS domains 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). 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: The application supplies the following three DNS domains: austin.ibm.com raleigh.ibm.com miami.ibm.com plus, the application uses the default service key (that is, ldap and specifies sales for the eNetwork domain). The configuration file contains server information for austin.ibm.com and miami.ibm.com (with the default service key and eNetwork domain of sales). 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. The locator API will build a single ordered list of server entries, with the following: Server entries for the austin.ibm.com DNS domain, as extracted from the configuration file. Server entries for the raleigh.ibm.com DNS domain, as obtained from DNS over the network. Server entries fo rthe miami.ibm.com DNS domain, as extracted from the configuration file. 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.
connection_type	Specifies the type of connection to use when communicating with the DNS name server. The following options are supported: Use UDP first. It no response is received, or data truncation occurs, then use TCP. Only use UDP. Only use TCP. If set to zero, the default is to use UDP first (then TCP). UDP is the preferred connection type, and typically performs well. You might want to consider using TCP/IP if: The amount of data being returned will not fit in the 512-byte UDP packet. The transmission and receipt of UDP packets turns out to be unreliable. This may depend on network characteristics.
connection_timeout	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.
DN_filter	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.
reserved2	Represents a reserved area for future function, which should be initialized to zero.

server_info_listpp

(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:

• DNS
• Local configuration

Upon successful return from ldap_server_locate(), server_info_listpp points to a linked list of LDAPServerInfo structures. The LDAPServerInfo structure (as defined above), contains the following fields:

lsi_host	Fully-qualified hostname of the target server (NULL-terminated string).
lsi_port	Integer representation of the LDAP server's port.
lsi_suffix	String that specifies a supported suffix for the LDAP server (NULL-terminated string).
lsi_query_key	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.
lsi_dns_domain	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).
lsi_replica_type	Specifies the type of server, LDAP_LSI_MASTER or LDAP_LSI_REPLICA. If set to zero, the type is unknown.
lsi_sec_type	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.
lsi_priority	The priority value obtained from the SRV RR (or the "pseudo-SRV" TXT RR). Set to zero if unknown or not available.
lsi_weight	The weight value obtained from the SRV RR (or the "pseudo-SRV" TXT RR). Set to zero if unknown or not available.
lsi_vendor_info	NULL-terminated string obtained from the ldapvendor TXT RR (if defined). May be used to identify the LDAP server vendor/version information.
lsi_info	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.

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error code

if the request was not successful.

Error Conditions

If ldap_server_locate() is not successful, an error code will be returned. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_init() -- Perform an LDAP initialization operation.
• ldap_server_conf_save() -- Store server information into local configuration.
• ldap_server_free_list() -- Free the list of LDAP servers.