ShowTable of Contents
In this section, we give recommendations and best practices for configuring your Lotus Sametime server for best Name Lookup (also called STResolve) performance.
Introduction
The Sametime server acts as the central processing point for all name lookup requests. It takes the name lookup requests that the Sametime Connect clients and Notes clients generate and formats them into search strings that are then passed to the directory server for processing. Typical name lookup requests can include:
-
Resolves a string to a unique ID, that is, resolves a Sametime search for an exact distinguished name.
-
Example: Resolves John Doe to value UID=12345,O=IBM.
-
Searches for a user or group, that is, resolves a Sametime search for a directory string that might contain some or all of the user's provided search string.
-
Example: Using the quick find feature in the Sametime Connect client
-
Retrieves user details
-
Example: Using the e-mail address with the Sametime Gateway to provide on-line status for a user
When the Sametime server is under duress, users may not be able to perform certain operations. For symptoms that users can experience refer to "Symptoms of poor Name Lookup performance" on the main page of this guide.
In the past, the problem of STResolve load has been exasperated due to a limited availability of options to limit unnecessary resolve requests being sent to the server. However, there are several options now available to improve the efficiency of the STResolve task. We recommend applying all of the changes below to the environment to maximize the effectiveness of the filtering algorithms and improve throughput to the directory servers. Sametime Resolve requests are handled differently in Domino Directory versus LDAP environments. The sections below outline the best practices for each environment.
For a Sametime server configured to use Domino Directory
When the Sametime server is configured to use a Domino Directory, requests are processed immediately upon arrival. The Sametime Resolve tasks utilizes the Domino APIs to pass the query off to the Domino server for the processing. Because most names are resolvable in the local address book, problems with Sametime resolve do not occur as often. As a best practice, apply these three options:
Increase the Domino Server name lookup cache
The NameLookupCache reduces Domino server load driven by resolve requests from Sametime clients, including Notes IM. Resolve requests in this server configuration ultimately become Domino NameLookups. Provisioning an appropriate cache size enables Domino to minimize actual directory queries.
To implement, set the notes.ini parameter NLCACHE_SIZE equal to the number of bytes you want the maximum cache size to be.
Example:
For optimal performance, the size of this cache needs to exceed the maximum that will occur under normal situations. Any additional memory will not be used (nor will it "cost" anything).
IBM recommends a Domino NAMELookup cache size of 64 MB for Sametime server configurations.
To determine if your NameLookupCache is large enough, compare Database.NAMELookupCacheMaxSize with Database.NAMELookupCachePool.Peak and Database.NAMELookupCachePool.Used. To show database.namelookup stats enter the following on the Domino console:
show stat database.namelookup*
Neither value should have reached Database.NAMELookupCacheMaxSize. If the numbers are close, increase the cache size.
If system administrators do not want to examine the statistics on their system to tune the cache size (which is a trial and error process by nature), performance testing done in the Domino 6.x timeframe suggests that a 64 MB (67108864) setting would likely be adequate for most systems, and can be considered an adequate setting for Sametime servers (with tuning occurring if _Database.NAMELookupCachePool.Peak becomes equal to Database.NAMELookupCacheMaxSize.)
Refer to the Name lookup cache testing section of this developerWorks article "Domino 6 directory performance improvements" for additional insight into setting NAMELookup cache.
Use local replicas for secondary address books
IBM recommends that you use local replicas for secondary address books. This use of local replicas reduces the number of calls that need to be made to other directory servers. When a query is made to another server, network latency can affect the speed of the transaction.
Use full text indexing for all directories
Using full text indexing for all directories utilized by Sametime can significantly improve the search file for a user or group. Do not reindex the directory too often as reindexing the directory during normal business hours can lock the directory from certain functions, causing inconvenience to the end-users.
For a Sametime server configured to use LDAP
Sametime servers that are configured to use an LDAP environment operate based on a queuing system. When a name lookup request arrives, the request is then distributed to one of the STResolve threads. This thread examines the request and formulates a filter based on the information specified in the Sametime Configuration (stconfig.nsf) database, the sametime.ini, and the Java filters (if implemented). The purpose of the queue is to act as a buffer to prevent the LDAP directory servers from being overloaded with requests and potentially causing a directory server outage.
Determine if Sametime Resolve is under stress
To tell if the Sametime Resolve task in an LDAP environment is under stress, you can enable debug. The following debug parameter can be put in the Sametime.ini to enable LDAP tracing:
VP_LDAP_TRACE=1
With this debug in place, a file called StLdap_StResolve*.txt will be created in the \trace directory. This file contains all of the name lookup requests that are sent to the LDAP server. Information about the state of the STResolve operations is also logged. When the incoming request rate is greater than the processing capacity of the STResolve service, then the following message will be logged:
LDAP 08/Mar/05, 16:37:33 Warning: 10 operations waiting for response. Will not request new operations until at most 5 are left
This message is purely informational and indicates that the maximum number of requests submitted to the LDAP server has been reached. The STResolve task will stop sending requests until the lower threshold is met. In the message above, the maximum number of in flight requests is 10 and the minimum threshold is 5. If the size of the queue continues to grow, a low efficiency message will be logged to the trace file:
LDAP 08/Mar/05, 16:38:33 Warning: low efficiency [2 iterations]
If low efficiency messages or the warning message appear frequently in the log files, you should implement the additional tuning parameters below and the client strategy optimizations.
Sametime Resolve Hotfix
The Sametime Resolve Hotfix contains two enhancements that can be used to reduce STResolve load.
-
SPR RBLE7RALFT - Support a customized filter that returns null
In previous Sametime versions, it was not possible to prevent an unresolvable name lookup requests from reaching the LDAP server. With this latest enhancement, the Java filters can return a null value. When the Sametime server detects that a null is returned, the Sametime server will return a success response code with 0 matches. This results in the same user experience as when searching for a user (given a valid name) that does not exist in the directory. See the section below on writing custom Java filters for information on using this feature.
-
SPR JJON6ZQPUQ - Support multiple connections.
There was a defect with setting the parameter ST_DB_LDAP_CONNECTIONS_NUMBER to a value higher than 1. This change caused the process utilization on the server to increase to 100% whenever there was a disconnection between Sametime and LDAP.
Note that the above two Hotfixes are incorporated into Sametime 8.5.x gold version.
Changes to increase the number of concurrent connections should be used cautiously because it can have a negative performance on the server if more connections are created than the LDAP server is able to handle. The number of STResolve threads that should be utilized will depend on the specifications of the Sametime server and the STResolve load. The number of threads utilized should be increased ONLY if problems are detected with slow logins or slow name lookup requests, however, only if it has been verified that the LDAP server can handle more load. See the section ST_DB_LDAP_CONNECTIONS_NUMBER under the "Changes in the Sametime.ini" section for information on using this feature.
Download links for the STResolve hotfix from IBM Fix Central:
Note that those Hotfixes are already incorporated in Sametime 8.5.x based version.
Sametime ini file
To improve load and response times, the following parameters can be added to the Sametime.ini under the Directory section. The values in the example below are the default values as assigned by the server.
[Directory]
ST_DB_LDAP_CONNECTIONS_NUMBER=1
ST_DB_LDAP_KEEPALIVE_INTERVAL=1
ST_DB_LDAP_PENDING_LOW=5
ST_DB_LDAP_PENDING_MAX=10
ST_DB_LDAP_RESPRAY_INTERVAL=0
ST_DB_LDAP_MAX_RESULTS=1000
ST_DB_LDAP_MIN_WILDCARD=0
An explanation of each of the parameters and its purpose is provided below.
ST_DB_LDAP_CONNECTIONS_NUMBER
This parameter increases the number of concurrent connections from the Sametime server to the LDAP server(s) specified in stconfig.nsf per black box. The default setting is set to one (1) connection per black box for a total of four Sametime connections. This setting should only be modified if requests are taking an exceptionally long time to process due to long processing queues AND there are plenty of resources available on the Sametime and LDAP servers. Increasing the value of this parameter will increase the number of LDAP threads available to service the request and multiply the resource requirements for the black boxes. The maximum number of threads specified should never exceed 5.
ST_DB_LDAP_KEEPALIVE_INTERVAL
This parameter defines the duration (in minutes) to wait between keep-alive messages that are sent on idle LDAP connections. 0 means no keep-alive. A keep alive will only be sent when a respray is not scheduled for that minute. If firewalls or other network devices that can timeout the connection are situated between the Sametime server and the LDAP server, the keep alive interval must be set to a value less than the timeout value to prevent the connection from terminating.
ST_DB_LDAP_PENDING_LOW
This parameter defines the minimum number of requests that can be in flight on the network to the LDAP server before the server sends out new requests to the LDAP server.
ST_DB_LDAP_PENDING_MAX
This parameter defines the total maximum number of requests that can be sent to the LDAP server. After reaching the number specified by ST_DB_LDAP_PENDING_LOW, the Sametime server will send out requests until this value is reached. After reaching this value, the Sametime server will wait for responses from the LDAP server. The difference between the pending low and max values should be kept minimal to prevent excessive queuing of requests on the Sametime server and overloading of the LDAP server with burst requests.
ST_DB_LDAP_RESPRAY_INTERVAL
This parameter will define how often (in minutes) the connection to the LDAP server should be dropped and then re-established. This parameter is very important in load balanced or rotating DNS scenarios, as it allows the Sametime server to drop the current connection instead of continuously trying to connect to a non-responsive LDAP server. The respray interval must always be higher than the keepalive interval.
Do not set the respray interval too low since recreating any network connection is an expensive operation and can severely impact the performance of an environment.
ST_DB_LDAP_MAX_RESULTS
Maximum number of entries that may be returned in a single search when searching for people or groups. Default is 1000.
ST_DB_LDAP_MIN_WILDCARD
Minimum number of characters in the search string required to perform a search.
Please note that making changes to these parameters will increase the load factor on the LDAP server. LDAP performance should be monitored and parameters adjusted so that other applications using the same LDAP server will not be adversely affected. By adjusting these parameters to very high values, there is a point where the overhead of maintaining the threads and connections will be higher than queuing the connections and waiting for the LDAP server to respond. Below is a set of recommendations that have been set in an environment and have been noted to improve LDAP performance.
Directory
ST_DB_LDAP_CONNECTIONS_NUMBER=1
ST_DB_LDAP_KEEPALIVE_INTERVAL=1
ST_DB_LDAP_PENDING_LOW=30
ST_DB_LDAP_PENDING_MAX=60
ST_DB_LDAP_RESPRAY_INTERVAL=60
ST_DB_LDAP_MAX_RESULTS=100
ST_DB_LDAP_MIN_WILDCARD=3
Review the Base DN for search
The base distinguished name (DN) for search defines the top most point in the directory where records of the same type or objectclass exist. Some companies set the base DN to the common attribute for all entries such as O=IBM. However, many directories have separate organizational units that define people and groups such as "OU=People,O=IBM" and "OU=Groups,O=IBM". An example of the LDAP Server document configured for a specific base DN for people and another for groups is shown below:
Base Objects
Base object when searching for person entries: OU=People,O=IBM
Base object when searching for group entries: OU=Groups,O=IBM
Review the base DN that you have set in the LDAP Server document and make sure it is appropriate.
Review and update the Sametime search filters
The search filters that are provided in the Sametime default installation are designed to be generic and fit as many system configurations as possible. There are three search filters that are used:
Search filter for resolving person names: (&(objectclass=organizationalPerson)(|(cn=%s*)(givenname=%s*)(sn=%s*)(mail=%s*)))
Search filter to use when resolving a user name to a distinguished name: (&(objectclass=organizationalPerson)(|(cn=%s)(givenname=%s)(sn=%s)(mail=%s)))
Search filter for resolving group names: (&(objectclass=groupOfNames)(cn=%s*))
The first search filter ("Search filter for resolving person names")is used for person searches when adding people to the contact list or locating them with the quick find feature. This is the search filter used by the Notes client to resolve names for inbox awareness. This filter should contain the attributes that users would most likely search for. As an example, this might be a user's full name (cn), given name (givenname), surname (sn) or email address (mail). This search filter utilizes wildcards so partial strings are allowed for search.
The second search filter ("Search filter to use when resolving a user name to a distinguished name") is used for an exact match comparison to a string that exists in LDAP. This filter is used for user authentication. Common attributes that may be included in this filter are employee id number, email address (mail), unique id (uid), samaccountname and full name (cn). Attributes for which multiple records with the same value such as surname (sn) are not commonly part of this filter.
The last search filter ("Search filter for resolving group names") is used by Sametime quick find or when a user is searching for a public group in the directory. Because a user might only know part of a group's name, this search filter is typically configured to allow wildcard searches.
Remove extraneous attributes from the default search filters
There are two search filters in the LDAP Server document that control the searching and resolution of names and one search filter. The first filter "Search filter for resolving person names" is responsible for directory searching when a user is added to the buddy list.
To demonstrate how to modify the default search filters, the following scenario will be used:
Renovations has implemented an LDAP environment shared by several applications. Users must use their employee id (uid) number to authenticate to any application using the LDAP directory. Each user knows their own employee id (uid) number but does not know the employee id of any of their colleagues. Instead, s user searches for colleagues using email address (mail), full name (cn), surname (sn) or part of their name. Public groups names are stored under the cn LDAP attribute.
Because the users only want to search on email address (mail), full name (cn), surname (sn) or part of their name, the administrator needs to add in the extra attributes and remove those which will not be used as part of the search. In this example, the modified search filter would look like:
Search filter for resolving person names: (&(objectclass=organizationalPerson)(|(cn=%s*)(sn=%s*)(mail=%s*)))
The same is applicable to "Search filter to use when resolving a user name to a distinguished name." This search filter is used to control authentication to the Sametime server. Because users will authenticate only with their employee number, the search filter can be modified as follows:
Search filter to use when resolving a user name to a distinguished name: (&(objectclass=organizationalPerson)(uid=%s))
Note: If only one attribute is specified for logins, the OR condition in the search filter is not removed along with the extra set of parenthesis. Having an extra set of parenthesis will cause the search filter to fail.
Finally, users will want to search for groups using the group name which is stored in the cn field. In this example, the modified search filter would look like:
Search filter for resolving group names: (&(objectclass=groupOfNames)(cn=%s*))
Once changes have been made to the search filters, a restart of the Sametime server is required to apply the changes.
Writing Custom Java Filters
Custom Java Filters allow an administrator the ability to build intelligence into a search filter. There are two types of functions a Java filter can provide. First, it can modify the search results by manipulating the data from two or more results before displaying the final result to the user. Secondly, it can modify the search filter that is sent to the LDAP server for processing. In this guide, the focus will be on using Java filters to modify the search filters sent to the LDAP server for processing. However, see the section below on "Writing your own Java Filter" for information about how two or more attributes can be combined.
Sample Java Filter
This sample Java filter is designed to demonstrate how a Java filter can be designed with extended logic to intelligently create LDAP search filters to process search requests. Normal search filters will search every attribute that is specified; however there are certain attributes that a search filter can use to determine the type of data which is being processed. This example makes the following assumptions:
-
An "@" symbol in the string indicates that the string is an email address
-
A "/" in the string indicates that the string is a Notes hierarchical name
This example also demonstrates how a whitelist and blacklist can be used to resolve email addresses that are valid in your Sametime community while rejecting email addresses that might be from other subdomains or external entities.
All of the settings for this example are configurable from the SametimeLDAPFilter.ini file. When the Sametime server is initialized for the first time, the Java class is dynamically linked and initialized. The ini file will be read only during the module initialization, so any changes to the parameters in the file during server runtime will require that the module to be reinitialized by restarting the service (on Windows platforms) or restarting the Sametime server (Unix/Linux/i5). Using an external file to set the parameters will marginally impact the first search request after initialization but will reduce the amount of time needed to recompile the module in case future changes are required.
Note: You must have the Sametime Resolve Hotfix installed to use this sample.
SametimeLDAPFilter_v1.3.zip
(version 1.3 is the latest sample)
IBM does not provide any support or additional development around this filter. The source code is provided for your use and to modify for your environment. If you require assistance in modifying this filter for your environment, please contact IBM Software Services for Lotus for assistance.
Writing your own Java Filter
The following section discusses how to write your own Java search filter. You will require a basic knowledge of Java to customize a filter. As a starting point, you may want to consider using the sample above.
There are two main uses for Java Customized LDAP settings.
1. Java Customized LDAP Attributes
2. Java Customized LDAP Search Filters
1. Java Customized LDAP Attributes
The Java Customized LDAP Attributes apply to the Schema Settings in the Sametime LDAP Configuration. As a reference, here is a list of the settings from stconfig.nsf and their default values:
People
The attribute of the person entry that defines the internal ID of a Sametime user:
The attribute of the person entry that defines the person's name: cn
Attribute used to distinguish between two similar person names:
Attribute of the person entry that defines the person's e-mail address:
The person object class used to determine if an entry is a person: organizationalPerson
Groups
Attribute used to distinguish between two similar group names:
The attribute of the group entry that defines the group's name: cn
Attribute in the group object class that has the names of the group members: member
The group object class used to determine if an entry is a group: groupOfNames
Home Server
Name of the Home Server Attribute:
Example 1a: Update the SametimeServer attribute for Domino LDAP
A common use for Java Customized LDAP Attributes is to populate the Home Sametime Server attribute when using Domino LDAP for Authentication. Because the SametimeServer field in the Person document is in a Names field, Domino LDAP will convert the "/" to a "," when the SametimeServer field is requested via LDAP. This conversion causes the lookup to SametimeServer to fail when looking up the Sametime Server name and users will not be able to log in. This is shown in the Domino LDAP SametimeServer attribute example above.
To work around this behavior, a Java method can be written to convert the "," back to a "/" so that the Sametime Server will be able to find the server name properly.
Here is a sample class with a static method to convert "," to "/". Note that the class names, static method names, variable names, and LDAP attribute names used in the examples are not set as required names. You are free to use any naming convention that you wish, as long as the Java class and method names are referenced correctly in the Sametime configuration.
public class STCustomLDAPSettings {
public static String convertSTServerName(String stservername) {
return stservername.replace(',', '/');
}
}
For this method to take effect, the value of field "Name of the Home Server Attribute" must call the method and pass the appropriate Sametime Server Name.
For example:
Home Server
Name of the Home Server Attribute: STCustomLDAPSettings.convertSTServerName(SametimeServer)
Keep in mind that the class name and method name are case-sensitive so they must match the names specified in the Java code exactly. The name of the LDAP Attribute is not case-sensitive. As shown in the example LDIF above, the Attribute containing the Sametime server name happens to be called "SametimeServer". This is not a requirement and any existing LDAP attribute can be used if the LDAP Schema cannot be extended to include SametimeServer.
Note for Domino LDAP: By default Domino LDAP does not allow anonymous LDAP clients to see the SametimeServer attribute. For this to work, either an authenticated LDAP connection must be used or the Domino LDAP configuration in the default Configuration Document in Names.nsf must be changed to allow the SametimeServer attribute to be searchable by anonymous LDAP clients. To use an authenticated LDAP connection for Sametime, just specify the credentials in the appropriate fields in Sametime LDAP settings.
Example 1b: Customize the Display of User Names in Contact Lists
In Example 1a, the steps to take values of one LDAP attribute and return a modified value was discussed. This can be applied to any of the LDAP Attribute settings. Java can also be used to combine and merge the values of multiple LDAP Attributes. For instance, the LDAP Attribute that is used to determine how names look in contact lists is specified in the field "The attribute of the person entry that defines the person's name". This example will customize the name to be in the format "FirstName Surname - Country".
Keep in mind that an LDAP Attribute containing the base information must exist. For example if no LDAP Attribute contained Country information for users, it must first be added to the schema and populated correctly.
Here is a sample Java class that accepts three strings as inputs and formats them as described. In this example it is assumed that the firstname, lastname and country will always exist. If this is not true, a similar check is required to validate that the Strings are not null.
public class STCustomLDAPSettings {
public static String displayName(String firstName, String surname, String country) {
return firstName + " " + surname + "-" + country;
}
}
The Sametime LDAP Configuration must also be changed to:
The attribute of the person entry that defines the person's name:
STCustomLDAPSettings.displayName(givenname, sn, Country)
The parameters that are passed in should be the names of the LDAP Attributes. Notice that the names of the attributes and the variable names declared in the method do not need to match, but specifying similar names helps alleviate confusion and decrease the chance for defects.
After these changes are made, new names added to the contact list in private groups will be in the format "FirstName Surname - Country". This will also affect the way all names look in public groups. Currently existing members of private groups will not have their display name changed as the old format will have already been saved to the contact list. The display name is saved to the contact list to allow users to customize the display names of contact list entries.
2. Java Customized LDAP Search Filters
Java can also be used to customize the LDAP Search filters used by Sametime. Here are some default filters to use as a reference:
Search Filters
Search filter for resolving person names:
(&(objectclass=organizationalPerson)(|(cn=%s*)(sn=%s*)(mail=%s*)))
Search filter to use when resolving a user name to a distinguished name:
(&(objectclass=organizationalPerson)(|(cn=%s)(sn=%s)(mail=%s)))
Search filter for resolving group names: (&(objectclass=groupOfNames)(cn=%s))
Customizing the LDAP Search filters can be a very powerful method of optimizing LDAP performance. For the examples in Java Customized LDAP Attributes, the method signature could have one or more String inputs and return a String. For Java Customized LDAP Search filters, the method signature should take only one String input and return a String. The input will end up being the exact String that the user is searching for and can be used to manipulate the Search Filter.
When Sametime utilizes a Java CustomizedLdap library for LDAP search filters , Java code must use certain encoding on the username string to be resolved. Note that if the Java customize code does not escape special characters that are embedded in the username string, it may cause Sametime connection to LDAP to hang.
I
Example 2a: Customizing searches for email addresses
For example if a user is trying to add Blue Admin to their contact list using Blue Admin's email address, the user would search for "admin@blue.com". By default, Sametime will send the following search string to the LDAP Server:
(&(objectclass=organizationalPerson)(|(cn=admin@blue.com*)(sn=admin@blue.com*)
(mail=admin@blue.com*)))
It would be more efficient to send just:
(&(objectclass=organizationalPerson)(mail=admin@blue.com))
This can be done by writing a Java static method to return a custom search filter based on the properties of the search string.
Here is an example:
public class STCustomLDAPSettings {
public static String searchFilter(String name) {
if searchstring has @ only check mail attribute
if (name.indexOf('@') >= 0)
return "(&(objectclass=organizationalPerson)(mail=" + name + "))";
return default search string minus the mail attribute
return "(&(objectclass=organizationalPerson)(|(cn=" + name + "*)(sn=" + name + "*)))"
}
}
This method assumes that if there is an "@" in the search string that the user is searching using an email address so only the email address attribute is queried. If your LDAP Schema includes "@" in other attributes you may want to customize your method to match your needs. Notice also that in the example the wild card was omitted when searching for the email address. This means that a search for "admin@blue" will not resolve to "admin@blue.com" and search will return no results. If you would like to keep the wild card the return string can be modified to keep the wild card symbol.
The Sametime LDAP configuration would also need to be changed for this method to be used. The first filter is used when adding names to contact lists. The second filter is for authenticating users. The third filter is used for adding groups to contact lists. This example is being used for adding users to contact list the following must be changed:
Search filter for resolving person names: STCustomLDAPSettings.searchFilter(%s)
The parameter for every Java Customized LDAP Filter should always be %s. Also make sure to keep in mind that the class name and method name are case-sensitive.
Example 2b: Preventing/limiting Wild Card Searches and Search String Size
Wild Card searches can heavily impact LDAP Performance. A user searching for "a" by default would generate the following search filter:
(&(objectclass=organizationalPerson)(|(cn=a*)(sn=a*)(mail=a*)))
This would match every person record whose common name, last name, or email address starts with the letter "a". There is a Sametime.ini parameter (ST_DB_LDAP_MIN_WILDCARD) that can be used to specify the minimum length of a search string, but here's another way to do this using a custom search filter. This example will also prevent users from manually entering the wild card symbol in their searches.
public class STCustomLDAPSettings {
public static String searchFilter(String name) {
prevent users for manually searching with wild cards
if (name.indexOf('*') >=0)
return "(objectlass=sametimeProbe)";
only allow searches of 3 or more characters
if (name.length < 3)
return "(objectlass=sametimeProbe)";
return the default filter
return "(&(objectclass=organizationalPerson)(|(cn=" + name + "*)(sn=" + name + "*)(mail=" + name + "*))"
}
}
Notice that when a user searches with an invalid String, the method is returning "(objectlass=sametimeProbe)". This is done because the method must return a valid search filter. Returning null will cause problems for Sametime. Any valid search filter can be returned when attempting to prevent a user from searching for a string; however, searching on an invalid objectclass is typically very fast for the LDAP Server to process because it will contain an Index based on the objectclass. Also the example specifies sametimeProbe because LDAP Administrators will see many of these queries hitting their LDAP Server and this makes it easy for them to identify where this is coming from.
To complete the configuration, the Sametime LDAP Configuration will also need to be updated as in example 2a.
Example 2c: Optimizing Notes IM Resolve Requests
One of the most beneficial uses of Customizing LDAP Search filters is to optimize the Notes Client Inbox Awareness resolve requests. A standalone Sametime client only sends resolve requests to the Sametime Server when a user authenticates or manually searches a user. This typically occurs 15 or 20 times a day per user. When using Notes Inbox Awareness, the Notes client is responsible for obtaining awareness information for every name in the Inbox and in mail messages and possibly other Notes databases such as the Names.nsf. To perform this duty, the Notes Client will send a resolve request for every unique name that it sees. This can generate thousands of requests per user which is far greater than the typical LDAP Resolve load of a standalone Sametime Connect client. Newer Notes clients have user name caches to help alleviate the load, but the caches have size limits and the initial search requests will still be sent for each name. In the Notes 6.5.x and Notes 7.0.x clients, the searches for Inbox awareness actually generates a user search and a group search to LDAP, which can cause double the load to the LDAP Server. This can be optimized by customizing the group search filter to not search for strings that include "@" or "/" because most user entries in the Inbox will be either a Notes Name or email address. Here is a sample class to use for group searches:
public class STCustomLDAPSettings {
public static String groupFilter(String name) {
prevent group searches that have @
if (name.indexOf('@') >=0)
return "(objectlass=sametimeProbe)";
prevent group searches that have /
if (name.indexOf('/') >=0)
return "(objectlass=sametimeProbe)";
return the default filter
return "(&(objectclass=groupOfNames)(cn=" + name + "))"
}
}
Keep in mind that this can only be used if groups do not include "@" or "/". If your LDAP groups contain those symbols and you want to allow them to be searchable, a more intelligent filter must be made. As explained in Example 2c, the method must return a valid search filter that will generate no hits.
The group search filter will also need to be updated similar to what was shown in Example 2a.
Another efficient customization that can be done for Notes IM awareness is to modify the User Search Filter to only send requests if the email addresses end with the domain of your company. This is only helpful if there is a defined email domain that you can assume will apply to all users.
Example 2d: Using null to Terminate Unresolvable Resolve Requests
If the Sametime Server is running version 7.5.1 - 8.0.2, a hotfix is available to immediately return a message to the client indicating that no results were returned whenever a null is returned instead of a search string. This prevents the request from being sent to the LDAP server for processing, which in turn reduces the processing load on the LDAP. This change also reduces the length of the STResolve processing queues, which improves the speed at which results are returned.
public class STCustomLDAPSettings {
public static String groupFilter(String name) {
prevent group searches that have @
if (name.indexOf('@') >=0)
return null;
prevent group searches that have /
if (name.indexOf('/') >=0)
return null;
return the default filter
return "(&(objectclass=groupOfNames)(cn=" + name + "))"
}
}
In the example above, the returned value of "(objectclass=SametimeProbe)" is replaced with null.
The example code that has been discussed in this section is available for download. For more information and examples, view the information in the Sametime Information Center under the topic "Using a Java class to control directory searches for people and groups."
The String Representation of LDAP Search
When Java code is used to customize the LDAP Search filters of Sametime, this Java code must use certain encoding rules on the user name string to be resolved.
If the Java customize code does not adhere to the encoding rules and does not escape special characters that are embedded in the user name string, it may cause Sametime connections to LDAP to hang.
Therefore it is highly recommended that Java Customized Ldap library will do the escaping properly as demonstrates in the example below.
Encoding rules
The encoding is done according to RFC4515 - "The String Representation of LDAP Search." For more information on this RFC, visit the following URL: http://www.faqs.org/rfcs/rfc4515.html
The encoding rules are governed by the following table:
Character ASCII value
* 0x2a
( 0x28
) 0x29
\ 0x5c
NULL 0x00
The character must be encoded as the backslash '\' character (ASCII 0x5c) followed by the two hexadecimal digits representing the ASCII value of the encoded character. This escaping mechanism eliminates filter-parsing ambiguities and allows any filter that can be represented in LDAP to be represented as a NULL terminated string.
Example A:
string to resolve -> "Noam()"
encoded string -> "Noam\28\29"
Example B:
string to resolve -> "\ran"
encoded string -> "\5cran"
For more information and Java example to download, view the the following Tech note:
http://www.ibm.com/support/docview.wss?uid=swg21437755
Implementing the Java filter on your Sametime Server
To put a Java filter on your Sametime server, do the following:
1. Make sure that the Java filter is compiled with the correct version of Java.
A custom version of Java is installed as part of the Sametime server installation. A Java development environment does not need to be installed on the server. The Java development can be done on any workstation as long as the complied code is compatible with the Server's version of Java. This can be determined by running "java -version" command for the Java executable located in the ibm-jre folder of the Domino server installation.
The following is an example from a Domino 8.0.1 server:
C:\lotus\Domino\ibm-jre\jre\bin>.\java -version java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build pwi32dev-20070511 (SR5))
IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 Windows XP x86-32 j9vmwi3223-2007042
6 (JIT enabled)
J9VM - 20070420_12448_lHdSMR
JIT - 20070419_1806_r8
GC - 200704_19)
JCL - 20070511
To ensure that the correct Java version is returned, make sure that Java is not in your %PATH% environment variable.
2. Copy the files to the Domino Java folder located under the Domino Program folder by default.
Example: C:\Lotus\Domino|java
3. Update or verify that the ST_JAVA_CLASS_PATH variable in the sametime.ini includes the path to the Domino Java folder where you placed the class files.
Example:
ST_JAVA_CLASS_PATH=C:\Lotus\Domino\StConfig.jar;C:\Lotus\Domino\StConfigXml.jar;C:\Lotus\Domino\xerces.jar;C:\Lotus\Domino\java
4. Verify, add or update ST_JAVA_JVM_PATH environment variable in the sametime.ini points to the correct jvm.dll, which is generally the following by default:
**
C:\Lotus\Domino\ibm-jre\jre\bin\classic\jvm.dll (for Sametime 6.5.1 FP1 and higher)
5. Optionally in some versions of Sametime an additional copy of the sametime.ini must be copied into the C:\Lotus\Domino\ibm-jre\jre\bin.
This is not required with Sametime 8.x.
6. Update the Samtime LDAP Settings in stconfig.nsf or using the Admin Web interface to reference the functions. Remember that they are case-sensitive. To reference the class file and function, use the following format: ClassName.functionName(%s)
Example: STCustomLDAPSettings.searchFilter(%s)
7. Restart the server.
Tips for Java Customized Filters
-
As mentioned throughout this guide, the Java Class names and Java method Names are case-sensitive, so make sure the enter the correct values in the Sametime LDAP Configuration.
-
Keep in mind that these methods will be called thousands of times, so it is important to write them as efficiently as possible. Consult your Java Development Team for assistance.
-
All of the examples showed one class with one static method defined. You should create one class with multiple static methods.
-
Think carefully about your LDAP Schema and how the attributes are used. Make sure to validate your assumptions about the attribute values by checking actual LDAP data.
-
Write test drivers to ensure that the methods behave as you expect them to.
-
Verify that you compile your code with a Java version that matches your Server's Java version. In most cases, this should be Java 1.4.2/1.5.0.
-
If you have problems, you can debug by adding "VP_LDAP_TRACE=1" to the sametime.ini Debug section and restarting the server. The debug should be in the stresolve, stusers, or stgroups trace file depending on what you are troubleshooting.
-
LDAP Customized Attributes take one or more LDAP Attribute Names as parameters and return a String.
-
LDAP Customized Search Filters take one String as an input and must return a String that is a valid search filter.
-
To specify a wildcard search, the user provided value must be passed into the Java filter. The method in the Java filter will need to be programmed to add the wildcard symbol to the appropriate parts of the LDAP search filters.
-
In the Stconfig.nsf or Web Admin, the Java method parameters for LDAP Attributes will have to be names of valid LDAP Attributes and the Java method parameter for LDAP Search Filters will be %s.
|