Directory Server, Version 6.1

---

 

Setting server properties

We can set the following properties for your server:

• Changing server ports and enabling language tags

• Setting Searches

• Enabling and disabling transaction support

• Enabling and disabling event notification

• Adding and removing suffixes

• Referrals

• Adding attributes to and removing attributes from the attribute cache

• Enforcing minimum ulimits

While the Web Administration Tool is the preferred method, updates to the server configuration file can be made using LDAP utilities. The LDAP modify requests can be generated by:

• A C-application using the C-client provided with the IBM® Tivoli® Directory Server

• A Java™ application using JNDI

• Any other interface that generates a standard V3 LDAP.

Examples that are provided use the idsldapmodify command line utility.

The idsldapmodify command can be run either in interactive mode or with input specified in a file. For most examples in this guide, the file contents to be used with the idsldapmodify command are supplied. The general form of the command to use with these files is:

idsldapmodify -D <adminDN> —w <password> —i <filename>

To update the server configuration settings dynamically, we need to issue the following idsldapexop commands. This command updates all configuration settings that are dynamic:

idsldapexop -D <adminDN> -w <adminPW> -op readconfig -scope entire

This command updates a single setting.

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope single <entry DN>
          <attribute>

The idsldapexop command updates only those attributes that are dynamic. For other changes to take effect stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically. See the idsldapmodify and idsldapexop command information in the IBM Tivoli Directory Server version 6.1 Command Reference for more information.

Only the administrator and members of the administrative group are allowed to update the server configuration settings.

 

Changing server ports and enabling language tags

Remember, if you change the port setting for the server, you must also change the port settings for the server in the console. See Modifying a server in the console.

 

Using Web Administration:

Click the Server administration category in the Web administration navigation area and then click Manage server properties tab to display the Manage server properties panel. This panel is displayed with the General tab preselected. The General panel has two read-only information fields, which display the host name of the server and the version level of the IBM Tivoli Directory Server that is installed on the machine.

This panel also has three modifiable required fields, Unsecure port (default value is 389), Secure port (default value 636) that display the respective current port numbers and a check box to enable and disable language tag support.

The well-known ports are those from 0 through 1023. The registered ports are those from 1024 through 49151. The dynamic or private ports are those from 49152 through 65535.

If you want to change the port settings or enable language tags or both:

1. Click Unsecure port and enter a number ranging from 1 through 65535. For this example 399. Remember, if you change the port setting for the server, also change the port settings for the server in the console. See Modifying a server in the console.

2. Click Secure port and enter a number ranging from 1 through 65535. For this example 699. Remember, if you change the port setting for the server, also change the port settings for the server in the console. See Modifying a server in the console.

3. Click the Enable language tag support check box to enable support for language tags. The default setting is disabled. See Language tags for more information.

   After enabling the language tag feature, if you associate language tags with the attributes of an entry, the server returns the entry with the language tags. This occurs even if you later disable the language tag feature. Because the behavior of the server might not be what the application is expecting, to avoid potential problems, do not disable the language tag feature after it has been enabled.

4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

If you have changed a port number, stop the server for changes to take effect. See Starting and stopping the server.

We can enable or disable language tags dynamically, without restarting the server.

After stopping the server also stop and start the administration daemon locally to resynchronize the ports. See Directory administration daemon. Restart the server.

 

Using the command line:

To determine whether the language tag feature is enabled, issue a root DSE search specifying the attribute ibm-enabledCapabilities.

idsldapsearch -b "" -s base objectclass=* ibm-enabledCapabilities

If the OID 1.3.6.1.4.1.4203.1.5.4 is returned, the feature is enabled.

If the language tag support is not enabled, any LDAP operation that associates a language tag with an attribute is rejected with the error message:

LDAP_NO_SUCH_ATTRIBUTE

To assign the ports that are not the default ports and to enable language tags using the command line, issue the following command:

idsldapmodify -D <adminDN> —w <password> —i <filename>

where <filename> contains:

dn: cn=configuration
changetype: modify
replace: ibm-slapdPort
ibm-slapdPort: 399
-
replace: ibm-slapdSecurePort
ibm-slapdSecurePort: 699

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
replace: ibm-slapdLanguageTagsEnabled
ibm-slapdLanguageTagsEnabled: TRUE

You must stop the server for changes to take effect. See Starting and stopping the server.

We can enable or disable language tags dynamically, without restarting the server.

After stopping the server also stop and start the administration daemon locally to resynchronize the ports. See Directory administration daemon.

ibmdirctl -D <AdminDN> -w <Adminpw> -p 389 stop

ibmdirctl -D<AdminDN> -w <Adminpw>  admstop

idsdiradm

ibmdirctl -D<AdminDN> -w <Adminpw>  start

 

Setting Performance

For the latest tuning information, see the IBM Tivoli Directory Server Version 6.1 Performance Tuning and Capacity Planning Guide located on the Tivoli Software Library Web site.

We can change the search limits and connections settings to enhance performance.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Performance tab.

1. Specify the Number of database connections. This sets the number of DB2® connections used by the server. The minimum number specify is 5. The default setting is 15. If your LDAP server receives a high volume of client requests or clients are receiving "connection refused" errors, you might see better results by increasing the setting of the number of connections made to DB2 by the server. The maximum number of connections is determined by the setting on your DB2 database. While there are no longer any server limitations upon the number of connections you specify, each connection does consume resources. Consult the IBM Tivoli Directory Server Version 6.1 Performance Tuning and Capacity Planning Guide for the latest tuning recommendations for your system.

2. Specify the Number of database connections for replication. This sets the number of DB2 connections used by the server for replication. The minimum number specify is 1. The default setting is 4. Consult the IBM Tivoli Directory Server Version 6.1 Performance Tuning and Capacity Planning Guide for the latest tuning recommendations for your system.

   The total number of connections specified for database connections and database connections for replication cannot exceed the number of connections set in your DB2 database.

3. Select Cache ACL information to use the following ACL cache settings. This option must be selected in order for the other cache setting options on this panel to take effect.

4. Specify the Maximum number of elements in ACL cache. The default is 25,000.

5. Specify the Maximum number of elements in entry cache. The default is 25,000.

6. Specify the Maximum number of elements in search filter cache. The default is 25,000. The search filter cache consists of actual queries on the requested attribute filters and resulting entry identifiers that matched. On an update operation, all filter cache entries are invalidated.

7. Specify the Maximum number of elements from a single search added to search filter cache. If you select Elements, enter a number. The default is 100. Otherwise, select Unlimited. Search entries that match more entries than the number specified here are not added to the search filter cache.

8. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

9. If you are setting the number of database connections, restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration
changetype: modify
replace: ibm-slapdDbConnections
ibm-slapdDbConnections:  15
-
replace: ibm-slapdReplDbConns
ibm-slapdReplDbConns:  4

dn: cn=Front End, cn=Configuration
changetype: modify
replace: ibm-slapdACLCache
ibm-slapdACLCache: TRUE
-
replace: ibm-slapdACLCacheSize
ibm-slapdACLCacheSize: 25000
-
replace: 
: 25000
-
replace: ibm-slapdFilterCacheSize
ibm-slapdFilterCacheSize: 25000
-
replace: ibm-slapdFilterCacheBypassLimit
ibm-slapdFilterCacheBypassLimit: 100

To update the settings dynamically, issue the following idsldapexop command:

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope entire

The idsldapexop command updates only those attributes that are dynamic. For other changes to take effect stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

 

Setting Searches

We can set search parameters to control users' search capabilities, such as paged and sorted searching.

Paged results allow you to manage the amount of data returned from a search request. We can request a subset of entries (a page) instead of receiving all the results at once. Subsequent search requests display the next page of results until the operation is canceled or the last result is returned. Sorted search allows a client to receive search results sorted by a list of criterion, where each criteria represents a sort key. This selection moves the responsibility of sorting from the client application to the server, where it might be done more efficiently.

A directory entry with objectclass of 'alias' or 'aliasObject' contains an attribute 'aliasedObjectName' that is used to reference another entry in the directory. Only search requests can specify if aliases are dereferenced. Dereferencing means to trace the alias back to the original entry. The IBM Tivoli Directory Server response time for searches with the alias dereferencing option set to always or search might be significantly longer than that of searches with dereferencing option set to never, if alias entries exist in the directory.

The server side dereference option can be set to never, find, search, or always. This option value is combined with the deference option value specified in a search request by a logical AND operation. The resulting value is used as the dereference option in the search operation.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Search settings tab.

1. Set the Search size limit. Click either the Entries or the Unlimited radio button. If you select Entries, we need to specify in the field the maximum number of entries a search returns. The default setting is 500. If more entries fit the search criteria, they are not returned. This limit does not apply to the administrator or administrative group members.

2. Set the Search time limit. Click either the Seconds or the Unlimited radio button. If you select Entries, we need to specify in the field the maximum amount of time the server spends processing the request. The default setting is 900. This limit does not apply to the administrator administrative group members.

3. To restrict search sorting capabilities to administrators, select the Only allow administrators to sort searches check box.

4. To restrict search paging capabilities to administrators, select the Only allow administrators to page searches check box.

5. To set the level of alias dereferencing, expand the drop-down menu for Alias dereferencing and select one of the following. The default setting is always.

   never

   Aliases are never dereferenced

   find

   Aliases are dereferenced when finding the starting point for the search, but not when searching under that starting entry.

   search

   Aliases are dereferenced when searching the entries beneath the starting point of the search, but not when finding the starting entry.

   always

   Aliases are always dereferenced, both when finding the starting point for the search, and also when searching the entries beneath the starting entry. Always is the default setting.

   This option is available only if your server supports dereferencing aliases.

6. Specify in seconds the time to wait (idle time out) for paged searches. Paged searches require an open connection between the LDAP server and the DB2 database where the LDAP data is stored. The idle time out administrative limit is designed to age out DB2 database connections held open for paged results search requests.

7. Specify the maximum number of concurrent paged searches allowed by the server at any given time. The default setting is 3.

   Setting the value to 0 disables paged searches.

8. Specify the maximum number of attributes used for sorting in sorted searches. The default setting is 3.

   Setting the value to 0 disables sorted searches.

9. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

See Searching the directory with paging and sorting for additional information about searches.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Configuration
changetype: modify
replace: ibm-slapdTimeLimit
ibm-slapdTimeLimit:  900
-
replace : ibm-slapdDerefAliases
ibm-slapdDerefAliases: {never|find|search|always}
-
replace: ibm-slapdSizeLimit
ibm-slapdSizeLimit:  500

dn: cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration
changetype: modify
replace: ibm-slapdPagedResAllowNonAdmin
ibm-slapdPagedResAllowNonAdmin: false
-
replace: ibm-slapdPagedResLmt
ibm-slapdPagedResLmt: 3
-
replace: ibm-slapdSortKeyLimit
ibm-slapdSortKeyLimit: 3
-
replace: ibm-slapdSortSrchAllowNonAdmin
ibm-slapdSortSrchAllowNonAdmin: false

dn: cn=Front End, cn=Configuration
changetype: modify
replace: ibm-slapdIdleTimeOut
ibm-slapdIdleTimeOut:  300 

To update the settings dynamically, issue the following idsldapexop command:

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope entire

See the ldapsearch command information in the IBM Tivoli Directory Server version 6.1 Command Reference for more information on how to perform searches using the command line.

 

Searching the directory with paging and sorting

The search function searches for a filter match on only the first 240 bytes of an attribute if indexing is enabled for that attribute. Additionally, if sort is specified on a search request, the server sorts the entries found by the search using only the first 240 bytes. Any end user or client application needs to take into consideration that a match for a search filter that exists in a value after the first 240 bytes might not be returned to the client depending on whether indexing is enabled for that table.

This restriction is specific to the IBM Tivoli Directory Server. IBM LDAP servers on other platforms, including z/OS® and i5/OS® might have different restrictions. Consult the documentation for each platform to determine restrictions.

The administrator can tell if indexing has been enabled for an attribute by looking at the attribute definition in the Web Administration Tool, (Schema management -> Manage attributes -> <attributename> -> Edit ->IBM extensions) or by looking at the attribute definition returned by a search of cn=schema. When viewing an attribute definition in the Web Administration Tool, the IBM extensions tab displays the following:

Indexing rules

 Equality
 Ordering
 Approximate
 Substring
 Reverse

The appropriate indexing rules are checked for the attribute. If the idsldapsearch utility is used, the ibmattributetypes value contains the keywords: APPROX, EQUALITY, ORDERING, SUBSTR or REVERSE. For example, the 'cn' attribute has the following indexes defined:

attributetypes=( 2.5.4.3 NAME ( 'cn' 'commonName' ) DESC 'This is the X.500 
                commonName attribute, which contains a name of an object.  
                If the object corresponds to a person, it is typically the 
                persons full name.' SUP 2.5.4.41 EQUALITY 2.5.13.2 
                ORDERING 2.5.13.3 SUBSTR 2.5.13.4 )
ibmattributetypes=( 2.5.4.3 DBNAME ( 'cn' 'cn' ) ACCESS-CLASS NORMAL LENGTH 
                   256 EQUALITY ORDERING SUBSTR APPROX )

See Indexing rules.

 

Sorted search control

Sorted Search Results provides sort capabilities for LDAP clients that have limited or no sort functionality. Sorted Search Results allows an LDAP client to receive search results sorted based on a list of criteria, where each criteria represents a sort key. The sort criteria includes attribute types, matching rules, and descending order. The server uses this criteria to sort search results before returning them. This moves the responsibility of sorting from the client application to the server, where it might be done much more efficiently. For example, a client application might want to sort the list of employees at the company's Grand Cayman site by surname, common name, and telephone number. Instead of building the search list twice so it can be sorted (once at the server and then again at the client after all the results are returned), the search list is built only once, and then sorted, before returning the results to the client application.

The server sorts search entries based on attributes and by default allows a maximum of three sort keys (attribute names) per search operation. To change the value of this administrative limit, change the following line, ibm-slapdSortKeyLimit: 3, in the ibmslapd.conf file. See Setting Searches for information on how to do this. If the line does not exist, add it to set the new maximum (if the line does not exist, the server is using the default value).

By default the server honors requests from nonadministrator binds, including those binding anonymously. Because sorting search results before returning them uses more server resources than simply returning them, you might want to configure the server to honor only requests from users binding with administrator authority. To honor sorted search requests submitted using only administrator bind, change the following line, ibm-slapdSortSrchAllowNonAdmin: true to ibm-slapdSortSrchAllowNonAdmin: false, in the ibmslapd.conf file. See Setting Searches. If the line does not exist, add it with a value of false to enable only administrator binds to perform sorted search operations.

The LDAP server returns all referrals to the client at the end of a search request. It is up to the application using the client services to decide whether to set the criticality of the sorted search request, and to handle a lack of support of those controls on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports the sorted search control. Multiple lists could be returned to the client application, some not sorted. It is the client application's decision as to how to best present this information to the end user. Possible solutions include: combine all referral results before presenting to the end user; show multiple lists and the corresponding referral server host name; take no extra steps and show all results to the end user as they are returned from the server. The client application must turn off referrals to get one truly sorted list, otherwise when chasing referrals with sorted search controls specified, unpredictable results might occur.

It is important to note when taking advantage of the server sorted search results that:

• The server takes advantage of the underlying DB2 database to perform sorting of search results. This means that there might be different sorted search results based on the data code page for the database (especially if your database code page is UTF-8).

• Ordering rules specified for a sort key attribute are ignored by the server. At this time, ordering rules are not supported by the server.

• There is no support for multi-server sorting (referrals). The server cannot guarantee that referred servers support sorted search results.

More information about the server side sorted search control can be found in RFC 2891. The control OID for sorted search results is 1.2.840.113556.1.4.473, and is included in the Root DSE information as a supported control.

 

Simple paged results

Simple Paged Results provides paging capabilities for LDAP clients that want to receive just a subset of search results (a page) instead of the entire list. The next page of entries is returned to the client application for each subsequent paged results search request submitted by the client until the operation is canceled or the last result is returned. The server ignores a simple paged results request if the page size is greater than or equal to the sizeLimit value for the server because the request can be satisfied in a single operation.

Because paging of search results holds server resources throughout the life of the simple paged results request, there are several new administrative limits employed to ensure that server resources cannot be abused, or misused, through the use of simple paged results search requests.

ibm-slapdPagedResAllowNonAdmin

By default, the server honors requests from non-administrator binds, including those binding anonymously. If you want the server to honor simple paged results search requests only from users binding with administrator authority, we need to change the following line, ibm-slapdPagedResAllowNonAdmin: true to ibm-slapdPagedResAllowNonAdmin: false, in the ibmslapd.conf file. See Setting Searches. If the line does not exist, add it with a value of false to allow only Administrator bind.

ibm-slapdPagedResLmt

By default, the server allows a maximum of three outstanding simple paged results operations at any given time. To ensure the fastest response for subsequent simple paged results request, the server holds a database connection open throughout the life of the search request until the user cancels the simple paged results request, or the last result is returned to the client application. This administrative limit is designed to ensure that other operations being handled by the server are not denied service because all database connections are in use by outstanding simple paged results search requests. For consistent results, set the ibm-slapdPagedResLmt value lower than the maximum number of database connections for your server. To change the value of this administrative limit, change the following line, ibm-slapdPagedResLmt: 3, in the ibmslapd.conf file. See Setting Searches. If the line does not exist add it to set the new maximum (if the line does not exist, the server is using the default value).

ibm-slapdIdleTimeOut

The idle time out administrative limit is designed to age out DB2 database connections held open for simple paged results search requests. The default idle time for a simple paged results request is 500 seconds. For example, if a client application were to pause for 510 seconds between pages, the server would age out the request in order to free the database connection for use by other server operations. The server returns the appropriate error to the client application for the next simple paged results request submitted, at which point the client application needs to restart the simple paged results request. The idle timer for each simple paged results request is restarted after every page returned to the client application. The server checks for aged out simple paged results request every 5 seconds, so if you set the value of ibm-slapdIdleTimeOut value lower than 5 seconds, you still have to wait 5 seconds for the simple paged results requests to be aged out. To change the value of this administrative limit, change the following line, ibm-slapdIdleTimeOut: 300, in the ibmslapd.conf file. See Setting Searches. If the line does not exist,add it to set the new maximum (if the line does not exist, the server is using the default value).

The LDAP server returns all referrals to the client at the end of a search request, the same as a search without any controls. That means that if the server has 10 pages of results returned, all the referrals are returned on the 10th page, not at the end of each page. When chasing referrals, the client application needs to send in an initial paged results request, with the cookie set to null, to each of the referral servers. It is up to the application using the client services to decide whether or not to set the criticality as to the support of paged results, and to handle a lack of support of this control on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports paged results controls. Multiple lists could be returned to the client application, some not paged. It is at the client application's decision as to how to best present this information to the end user. Possible solutions include: combine all referral results before presenting to the end user; show multiple lists and the corresponding referral server host name; take no extra steps and show all results to the end user as they are returned from the server. The client application must turn off referrals to get one truly paged list, otherwise when chasing referrals with the paged results search control specified, unpredictable results might occur.

More information about the server side simple paged results control can be found in RFC 2686. The control OID for simple paged results is 1.2.840.113556.1.4.319, and is included in the Root DSE information as a supported control.

 

Persistent search

Persistent search enables LDAP clients to receive notification of changes that occur in an LDAP server. The persistent search mechanism is available to all users. However, ACL checks are enforced on each entry that is returned. This means that users can retrieve only those entries or parts of entries that they have access to. Updates to the directory data that are a part of a transaction are also reported by persistent search. Since the persistent search mechanism is available to all users, it is mandatory to limit the number of concurrent persistent searches that the server will handle. This is done by setting the ibm-slapdMaxPersistentSearches option in the configuration file.

Although the persistent search mechanism can keep returning entries, the search size and time limits applicable for non-administrative users will be applicable for persistent search as well. The size and time limits will be applicable irrespective of whether the entries being returned are a part of the initial matching set or the updated ones. For instance, if the size limit is 500 and 450 entries have been sent as a part of the initial result set, then after 50 update notifications, the persistent search will return LDAP_SIZELIMIT_EXCEEDED error. Similarly, if the time limit is 10 seconds, then, irrespective of whether entries are returned from the initial matching set or update notifications, after 10 seconds an LDAP_TIMELIMIT_EXCEEDED error is returned.

When the persistent search mechanism is used along with paging or sorting, paging or sorting will be applicable only on the initial result set. Also, the change log plug-in will need to run before the persistent search plug-in, if change-log is enabled.

The TDS server will return the OID 2.16.840.1.113730.3.4.3 for the attribute ibm-supportedcontrol in case of a root DSE search.

The following addition is made to the configuration file to support the persistent search mechanism:

dn: cn=Persistent Search, cn=Configuration
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPersistentSearch
cn: Persistent Search
ibm-slapdEnablePersistentSearch:  TRUE
ibm-slapdMaxPersistentSearches:  100

ibm-slapdEnablePersistentSearch is a Boolean type attribute that determines if persistent search is enabled. This attribute can be assigned a value of either TRUE or FALSE. The default value of this attribute is TRUE. The ibm-slapdMaxPersistentSearches attribute determines the maximum number of concurrent persistent searches allowed. The default value of this attribute is 100 and the maximum allowed value is 2000.

 

How to enable persistent search

To enable persistent search, use one of the following methods.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Persistent Search tab.

1. Select the Enable persistent search check box to enable persistent search during server start-up.

2. In the Number of concurrent persistent searches field, enter the maximum number of concurrent persistent searches to be allowed. The default value is 100 and the maximum allowed value is 2000. The minimum allowed value is 1.

3. Click OK to save your changes.

 

Using the command line:

To enable persistent search using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW>
dn: cn=Persistent Search, cn=Configuration
changetype: modify
replace: ibm-slapdEnablePersistentSearch
ibm-slapdEnablePersistentSearch:  TRUE

 

Enabling and disabling event notification

The event notification function allows a server to notify a registered client that an entry in the directory tree has been changed, added, or deleted. This notification is in the form of an unsolicited message.

When an event occurs, the server sends a message to the client as an LDAP v3 unsolicited notification. The messageID is 0 and the message is in the form of an extended operation response. The responseName field is set to the registration OID. The response field contains the unique registration ID and a timestamp for when the event occurred. The time field is in UTC time format.

When a transaction occurs, the event notifications for the transaction steps cannot be sent until the entire transaction is completed.

ACLs are only checked on the entry that the event is registered on, when the event is registered. A user who does not have access to some of the entries below his access entry might receive notification of changes for those entries. The user is not told the exact change, just that a change has occurred. Also, if the ACLs are changed on the original entry to not allow the user access, the registered events remain, even though the user no longer has access. See Access control lists for information about ACLs.

 

Enabling event notification

To enable event notification, use one of the following procedures.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Event notification tab.

1. Select the Enable event notification check box to enable event notification. If Enable event notification is disabled, the server ignores all other options on this panel.

2. Set the Maximum registrations per connection. Click either the Registrations or the Unlimited radio button. If you select Registrations, you need to specify in the field the maximum number of registrations allowed for each connection. The maximum number of registrations is 2,147,483,647. The default setting is 100 registrations.

3. Set the Maximum registrations total. This selection sets how many registrations the server can have at any one time. Click either the Registrations or the Unlimited radio button. If you select Registrations, you need to specify in the field the maximum number of registrations allowed for each connection. The maximum number of registrations is 2,147,483,647. The default number of registrations is Unlimited.

4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

5. If you have enabled event notification, restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Event Notification,cn=Configuration
changetype: modify
replace: ibm-slapdEnableEventNotification
ibm-slapdEnableEventNotification:  TRUE
-
replace: ibm-slapdMaxEventsPerConnection
ibm-slapdMaxEventsPerConnection:  100
-
replace: ibm-slapdMaxEventsTotal
ibm-slapdMaxEventsTotal:  0

If you have enabled event notification, restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

To update the settings dynamically, issue the following idsldapexop command:

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope entire

The idsldapexop command updates only those attributes that are dynamic. For other changes to take effect stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

 

Disabling event notification

To disable event notification, use one of the following procedures.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Event notification tab.

1. Deselect the Enable event notification check box to enable transaction processing.

2. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

3. You must restart the server for the changes to take effect.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Event Notification,cn=Configuration
changetype: modify
replace: ibm-slapdEnableEventNotification
ibm-slapdEnableEventNotification:  FALSE

You must restart the server for the changes to take effect.

See the IBM Tivoli Directory Server Version C-Client SDK Programming Reference for more information about event notification.

 

Enabling and disabling transaction support

Transaction processing enables an application to group a set of entry updates together in one operation. Normally each individual LDAP operation is treated as a separate transaction with the database. Grouping operations together is useful when one operation is dependent on another operation because if one of the operations fails, the entire transaction fails. Transaction settings determine the limits on the transaction activity allowed on the server.

 

Enabling transaction support

To enable transaction support use one of the following procedures.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Transactions tab.

1. Select the Enable transaction processing check box to enable transaction processing. If Enable transaction processing is disabled, all other options on this panel, such as Maximum number of operations per transaction and Pending time limit, are ignored by the server.

2. Set the Maximum number of transactions. Click either the Transactions or the Unlimited radio button. If you select Transactions, we need to specify in the field the maximum number of transactions. The maximum number of transactions is 2,147,483,647. The default setting is 20 transactions.

3. Set the Maximum number of operations per transaction. Click either the Operations or the Unlimited radio button. If you select Operations, we need to specify in the field the maximum number of operations allowed for each transaction. The maximum number of operations is 2,147,483,647. The smaller the number, the better the performance. The default is 5 operations.

4. Set the Pending time limit. This selection sets the maximum timeout value of a pending transaction in seconds. Click either the Seconds or the Unlimited radio button. If you select Seconds, we need to specify in the field the maximum number of seconds allowed for each transaction. The maximum number of seconds is 2,147,483,647. Transactions left uncompleted for longer than this time are cancelled (rolled back). The default is 300 seconds.

5. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

6. If you have enabled transaction support, restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Transaction,cn=Configuration
changetype: modify
replace: ibm-slapdTransactionEnable
ibm-slapdTransactionEnable: TRUE 
-
replace: ibm-slapdMaxNumOfTransactions
ibm-slapdMaxNumOfTransactions: 20
-
replace: ibm-slapdMaxOpPerTransaction
ibm-slapdMaxOpPerTransaction: 5 
-
replace: ibm-slapdMaxTimeLimitOfTransactions
ibm-slapdMaxTimeLimitOfTransactions: 300

To update the settings dynamically, issue the following idsldapexop command:

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope entire

The idsldapexop command updates only those attributes that are dynamic. For other changes to take effect stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

 

Disabling transaction support

To disable transaction processing, use one of the following procedures.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Transactions tab.

1. Deselect the Enable transaction processing check box to enable transaction processing.

2. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

3. You must restart the server for the changes to take effect.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Transaction,cn=Configuration
changetype: modify
replace: ibm-slapdTransactionEnable
ibm-slapdTransactionEnable: False 

You must restart the server for the changes to take effect.

See the IBM Tivoli Directory Server Version C-Client SDK Programming Reference for more information about transaction support.

 

Adding and removing suffixes

A suffix is a DN that identifies the top entry in a locally held directory hierarchy. Because of the relative naming scheme used in LDAP, this DN is also the suffix of every other entry within that directory hierarchy. A directory server can have multiple suffixes, each identifying a locally held directory hierarchy, for example, o=sample.

The specific entry that matches the suffix must be added to the directory.

Entries to be added to the directory must have a suffix that matches the DN value, such as 'ou=Marketing,o=sample'. If a query contains a suffix that does not match any suffix configured for the local database, the query is referred to the LDAP server that is identified by the default referral. If no LDAP default referral is specified, the result returned indicates that the object does not exist.

 

Creating or adding suffixes

To create or add a suffix, use one of the following methods.

 

Using Web Administration:

Defined suffixes such as cn=localhost, cn=pwdpolicy, cn=schema and cn=ibmpolicies cannot be added or removed. Consequently, they are not displayed in the panel.

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Suffixes tab.

1. Enter the Suffix DN, for example, c=Italy. The maximum is 1000 characters for a suffix.

2. Click Add.

3. Repeat this process for as many suffixes as you want to add.

4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

 

Using the command line:

To add suffixes using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

DN: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
add: ibm-slapdSuffix
ibm-slapdSuffix: <suffixname>
ibm-slapdSuffix: <suffix2>
ibm-slapdSuffix: <suffix3>

To update the settings dynamically, issue the following idsldapexop command:

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope single "cn=Directory,
    cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration" ibm-slapdSuffix

We can also use the idscfgsuf command to add suffixes one at a time:

idscfgsuf -I <instancename> -s <suffixname>

See the idscfgsuf command information in the IBM Tivoli Directory Server version 6.1 Command Reference for more information.

 

Removing a suffix

To remove a suffix use, one of the following methods.

 

Using Web Administration:

Defined suffixes such as cn=localhost, cn=pwdpolicy, cn=schema and cn=ibmpolicies cannot be added or removed. Consequently, they are not displayed in the panel.

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Suffixes tab.

1. From the Current suffix DNs list box, select the suffixes you want to remove.

2. Click Remove.

3. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

 

Using the command line:

The removal of system defined suffixes such as cn=localhost, cn=pwdpolicy, cn=schema and cn=ibmpolicies is not supported.

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

DN: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
delete: ibm-slapdSuffix
ibm-slapdSuffix: <suffixname>
ibm-slapdSuffix: <suffix2>
ibm-slapdSuffix: <suffix3>

You must restart the server for the change to take effect.

To update the settings dynamically, issue the following idsldapexop command:

idsldapexop -D <adminDN> -w<adminPW> -op readconfig -scope single "cn=Directory,
    cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration" ibm-slapdSuffix

We can also use the idsucfgsuf command to add suffixes one at a time:

idsucfgsuf -I <instancename> -s <suffixname>

See the idsucfgsuf command information in the IBM Tivoli Directory Server version 6.1 Command Reference for more information.

We can also use the configuration utility idsxcfg to add and remove suffixes. See the IBM Tivoli Directory Server Version 6.1 Installation and Configuration Guide for more information.

 

Adding attributes to and removing attributes from the attribute cache

The attribute cache has the advantage of being able to resolve filters in memory rather than in the database. It also has the advantage of not being flushed like the filter cache each time an LDAP add, delete, modify, or modrdn operation is performed.

In deciding which attributes you want to store in memory, we need to consider:

• The amount of memory available to the server

• The size of the directory

• The types of search filters the application typically uses

The attribute cache manager can resolve both exact match filters and presence filters. It can also resolve complex filters that are conjunctive or disjunctive. Additionally, the subfilters within complex filters must be exact match, presence, conjunctive, or disjunctive.

Not all attributes can be added to the attribute cache. To determine if an attribute can be added to the cache, use the ldapexop command:

• For attributes that can be added:

  ldapexop -D <adminDN> -w <adminPW> -op getattributes -attrType attribute_cache 
  -matches true

• For attributes that cannot be added:

  ldapexop -D <adminDN> -w <adminPW> -op getattributes -attrType attribute_cache 
  -matches false

Attribute caching can be configured either manually or automatically. To manually configure attribute caching, an administrator first needs to know which attributes to cache. To make attribute caching most effective, the administrator should perform cn=monitor searches. These searches provide information about the attributes that are cached, the amount of memory used by each attribute in the cache, the total amount of memory used by attribute caching, the amount of memory configured for attribute caching, and a list of the attributes most often used in search filters. Using this information, an administrator can determine the amount of memory that is allowed to be used for attribute caching, as well as which attributes to cache whenever necessary.

Alternatively, when an administrator enables automatic attribute caching, the directory server tracks the combination of attributes that would be most useful to cache within the memory limits defined by the administrator. The server then updates the attribute caching at a particular time and according to a time interval configured by the administrator.

Typically you want to put a limited number of attributes into the attribute cache because of memory constraints. To help determine which attributes you want to cache, view the Directory cache candidate list and Changelog cache candidate list for the 10 most frequently used attribute search filters by your applications. See Checking server status. Also, see "Determining which attributes to cache" in the IBM Tivoli Directory Server Version 6.1 Performance Tuning and Capacity Planning Guide for more information.

 

Setting up and adding attributes to the attribute cache

To set up and add attributes to the attribute cache, use one of the following methods.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage cache properties in the expanded list. Next, click the Attribute cache tab.

1. We can change the amount of memory in kilobytes available to the directory cache. The default is 16384 kilobytes (16 MB).

2. We can change the amount of memory in kilobytes available to the changelog cache. The default is 16384 kilobytes (16 MB).

   This selection is disabled if a changelog has not been configured.

To enable directory automatic attribute caching, perform the following steps

1. Select the Enable directory automatic attribute cache check box. This enables other elements within this group.

2. Enter the start time for directory automatic attribute caching in the Start Time text box.

3. From the Interval combo box, select the interval at which the directory automatic attribute caching is to be performed again.

To enable change log automatic attribute caching, perform the following steps

1. Select the Enable change log automatic attribute cache check box. This enables other elements within this group.

2. Enter the start time for change log automatic attribute caching in the Start Time text box.

3. From the Interval combo box, select the interval at which the change log automatic attribute caching is to be performed again.

Automatic attribute caching for change log should not be enabled unless frequent searches within the change log are required and the performance of these searches are critical.

To add an attribute

1. Select the attribute that you want to cache from the Available attributes drop-down menu. Only those attributes that can be designated as cached attributes are displayed in this menu. For example, sn.

   An attribute remains in the list of available attributes until it has been placed in both the Directory and the Changelog containers.

2. Click either Add to Database or Add to Change log button. The attribute is displayed in the appropriate list box. We can list the same attribute in both containers.

3. Repeat this process for each attribute you want to cache.

   An attribute is removed from the drop-down list when it is added to both the Cached attributes under Database and Cached attributes under Change log listboxes. If changelog is not enabled, then the Add to Change log button is disabled and the entry cannot be added to Cached attributes under Change log list box. The attribute is removed from the available attributes list when it is added to Cached attributes under Database list box.

4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

 

Using the command line:

To create the directory attribute caches with the same attributes, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
add: ibm-slapdCachedAttribute
ibm-slapdCachedAttribute:  sn
-
add: ibm-slapdCachedAttribute
ibm-slapdCachedAttribute:  cn
-
replace: ibm-slapdcachedattributesize
ibm-slapdcachedattributesize: 16384

 

Removing attributes from the attribute cache

To remove an attribute from the attribute cache, perform either of the following tasks.

 

Using Web Administration

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage cache properties in the expanded list. Next, click the Attribute cache tab.

1. Select the attribute that you want to remove from the attributes cache by clicking the attribute in the appropriate list box. For example AIXAdminGroupId from the previous task.

2. Click Remove.

3. Repeat this process for each attribute you want to remove from the list.

4. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

 

Using the command line:

To perform the same operations using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

DN: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
delete: ibm-slapdCachedAttribute
ibm-slapdCachedAttribute:  sn

 

Group members' cache

The group members' cache is an extension of the Entry cache. This cache stores member and uniquemember attribute values with their entries. To configure the group members' cache, perform either of the following tasks.

 

Using Web Administration

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage cache properties in the expanded list. Next, click the Group members' cache tab.

To configure group members' cache:

1. In the Maximum number of groups in cache field, enter a value for the maximum number of groups with members to be cached in the group members' cache.

2. In the Maximum number of members in a group that can be cached field, enter a value for the maximum number of members in a group to be cached in the group members' cache.

3. When you are finished, do one of the following:

   • Click OK to save your changes and exit this panel.

   • Click Apply to apply your changes and stay on this panel.

   • Click Cancel to exit this panel without making any changes.

 

Using command line

To configure group members' cache using the command line, issue the following command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename> 
where <filename> contains:

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
replace: ibm-slapdGroupMembersCacheSize
ibm-slapdGroupMembersCacheSize:25
-
replace: ibm-slapdGroupMembersCacheBypassLimit
ibm-slapdGroupMembersCacheBypassLimit: 50

 

Enforcing minimum ulimits

The directory server tries to enforce minimum ulimit option values that are considered important for the smooth running of the server. During startup, the directory server verifies whether the ulimit option values for the current process are greater than or equal to the prescribed ulimit option values specified in the configuration file. If the verification fails, then the server attempts to set the ulimit option values of the current process to the prescribed values. If the server fails to do so, it will start in configuration only mode.

Given below is a list of all the typical ulimit options whose values are critical for the smooth running of the directory server.

Ulimit options are applicable only to the proxy and back-end servers. No minimum ulimit options values are prescribed for the admin daemon process.

Critical memory parameters

Virtual memory size

This option includes all types of memory including stack, heap, and memory-mapped files. Attempts to allocate memory in excess of this limit will fail with an out-of-memory error. The value for this option is specified in kilobytes.

Maximum resident set size (RSS)

This option limits the amount of memory that can be swapped in to physical memory on behalf of any one process. The value for this option is specified in kilobytes.

AIX® and HP-UX defines this ulimit option, while Solaris does not.

Data segment

This option limits the amount of memory that a process can allocate to a heap. The value for this option is specified in kilobytes.

Stack size

This option limits the amount of memory a process can allocate to a stack. The value for this option is specified in kilobytes.

Critical File parameters

File size

This option limits the maximum size of any one file a process can create. This is specified in 512-byte blocks.

Nofile

This option limits the number of file descriptors belonging to a single process. File descriptors includes not only files but also sockets for Internet communication.

On Solaris, the number of open files limit is set to the hard limit of the number of open files while starting the sever. The number of open files limit cannot be changed using the ulimit feature.

The table below lists the operating system default values and the prescribed minimum ulimit values of the critical options.

Table 12. System specific ulimit values

Ulimit Option	AIX		Solaris
	Operating system default	Prescribed minimum	Operating system default	Prescribed minimum
Data segment size	256 MB	256 MB	Unlimited	256 MB
Virtual memory	Unlimited	1 GB	Unlimited	1 GB
Nofile	2000	500	256	256
Maximum resident set size (rss)	64 MB	256 MB	N/A	N/A
File size	1024 MB	1024 MB	Unlimited	1024 MB
Stack size	64 MB	64 MB	8 MB	8 MB

Table 13. System specific ulimit values

Ulimit Option	Linux®		HP-UX
	Operating system default	Prescribed minimum	Operating system default	Prescribed minimum
Data segment size	Unlimited	256 MB	1024 MB	256 MB
Virtual memory	Unlimited	1 GB	Unlimited	1 GB
Nofile	1024	500	2048	500
Maximum resident set size (rss)	N/A	N/A	Unlimited	256
File size	Unlimited	1024 MB	Unlimited	1024 MB
Stack size	10 MB	10 MB	8 MB	8 MB

Operating system default ulimit option values may vary for different kernel versions and for different shells in the same kernel version.

An administrator can modify the minimum ulimit option values using the web administration tool or through command line.

 

Using Web Administration:

If you have not done so already, click Server administration in the Web Administration navigation area and then click Manage server properties in the expanded list. Next, click the Ulimit settings tab.

1. To specify the virtual memory size, select Size and specify a value in kilobytes in the text box. Alternatively, to specify the virtual memory size as unlimited, select Unlimited.

2. To specify the resident set size, select Size and specify a value in kilobytes in the text box. Alternatively, to specify the resident set size as unlimited, select Unlimited.

3. To specify the data segment size, select Size and specify a value in kilobytes in the text box. Alternatively, to specify the data segment size as unlimited, select Unlimited.

4. To specify the stack size, select Size and specify a value in kilobytes in the text box. Alternatively, to specify the stack size as unlimited, select Unlimited.

5. To specify the file size in blocks of 512 bytes, select File size and specify a value in kilobytes in the text box. Alternatively, to specify the file size as unlimited, select Unlimited.

6. Enter the number of file descriptors belonging to a single process in the Number of open file descriptors text box.

7. Click OK or Apply for the settings to take effect.

 

Using the command line:

Ulimit option values can be modified using the ldapmodify command line utility. For example, to modify the ulimit value for virtual memory, issue the following command:

ldapmodify  -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains: 

dn: cn=ulimits, cn= configuration 
changetype: modify 
replace: ibm-slapdUlimitVirtualMemory
ibm-slapdUlimitVirtualMemory: <New prescribed ulimit for virtual memory>

Similarly, the ldapmodify command can be used to modify other ulimit option values such as data segment size, nofile, maximum resident set size (rss), file size, and stack size.

[ Top of Page | Previous Page | Next Page | Contents | Index ]