The LDAP Connection Handler is used to interact with clients using LDAP.
It provides full support for LDAPv3 and limited support for LDAPv2.
The LDAP Connection Handler component inherits from the Connection Handler
The following components have a direct aggregation relation from LDAP Connection Handlers:
The properties supported by this managed object are as follows:
| Description | A description for this Connection Handler |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the Connection Handler is enabled. |
| Default Value | None |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies a set of address masks that determines the addresses of the clients that are allowed to establish connections to this connection handler. |
| Default Value | All clients with addresses that do not match an address on the deny list are allowed. If there is no deny list, then all clients are allowed. |
| Allowed Values | An IP address mask |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Changes to this configuration attribute take effect immediately and do not interfere with connections that may have already been established. |
| Description | Specifies a set of address masks that determines the addresses of the clients that are not allowed to establish connections to this connection handler. If both allowed and denied client masks are defined and a client connection matches one or more masks in both lists, then the connection is denied. If only a denied list is specified, then any client not matching a mask in that list is allowed. |
| Default Value | If an allow list is specified, then only clients with addresses on the allow list are allowed. Otherwise, all clients are allowed. |
| Allowed Values | An IP address mask |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Changes to this configuration attribute take effect immediately and do not interfere with connections that may have already been established. |
| Description | Specifies the address or set of addresses on which this LDAP Connection Handler should listen for connections from LDAP clients. Multiple addresses may be provided as separate values for this attribute. If no values are provided, then the LDAP Connection Handler listens on all interfaces. |
| Default Value | 0.0.0.0 |
| Allowed Values | An IP address |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Specifies the port number on which the LDAP Connection Handler will listen for connections from clients. Only a single port number may be provided. |
| Default Value | None |
| Allowed Values | An integer value. Lower limit is 1. Upper limit is 65535 . |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | This modification must also be made to the Server Instance representing this server in the topology registry. This ensures that the most up-to-date information is used by topology-related tools. |
| Description | Indicates whether the LDAP Connection Handler should use SSL. If enabled, the LDAP Connection Handler will use SSL to encrypt communication with the clients. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Indicates whether clients are allowed to use StartTLS. If enabled, the LDAP Connection Handler allows clients to use the StartTLS extended operation to initiate secure communication over an otherwise insecure channel. Note that this is only allowed if the LDAP Connection Handler is not configured to use SSL, and if the server is configured with a valid key manager provider and a valid trust manager provider. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | This modification must also be made to the Server Instance representing this server in the topology registry. This ensures that the most up-to-date information is used by topology-related tools. |
| Description | Specifies the nickname (also called the alias) of the certificate that the LDAP Connection Handler should use when performing SSL communication. This is only applicable when the LDAP Connection Handler is configured to use SSL. |
| Default Value | Let the server decide. |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Specifies the name of the key manager that should be used with this LDAP Connection Handler . |
| Default Value | None |
| Allowed Values | The DN of any Key Manager Provider. The referenced key manager provider must be enabled when the LDAP Connection Handler is enabled and configured to use SSL or StartTLS. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Changes to this property take effect immediately, but only for subsequent attempts to access the key manager provider for associated client connections. |
| Description | Specifies the name of the trust manager that should be used with the LDAP Connection Handler . |
| Default Value | None |
| Allowed Values | The DN of any Trust Manager Provider. The referenced trust manager provider must be enabled when the LDAP Connection Handler is enabled and configured to use SSL or StartTLS. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Changes to this property take effect immediately, but only for subsequent attempts to access the trust manager provider for associated client connections. |
| Description | Indicates whether connections from LDAPv2 clients are allowed. If LDAPv2 clients are allowed, then only a minimal degree of special support are provided for them to ensure that LDAPv3-specific protocol elements (for example, Configuration Guide 25 controls, extended response messages, intermediate response messages, referrals) are not sent to an LDAPv2 client. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the length of time that the server should delay the response to non-successful bind operations. A value of zero milliseconds indicates that non-successful bind operations should not be delayed. If the server should delay failed bind responses, then no other operations will be allowed on the connection until the response is sent. Note that if this is a Directory Server instance that is fronted by one or more Directory Proxy Server instances, then it is recommended to enable this feature in the Directory Proxy Server rather than in the Directory Server. This will avoid tying up Directory Proxy Server connections and worker threads while waiting on the delayed responses from the backend Directory Server, but will still ensure that the response is delayed before being returned to the client. |
| Default Value | 0 ms |
| Allowed Values | A duration. Lower limit is 0 milliseconds. Upper limit is 10000 milliseconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the size of the largest LDAP request message that will be allowed by this LDAP Connection handler. This property is analogous to the maxBERSize configuration attribute of the Sun Java System Directory Server. This can help prevent denial-of-service attacks by clients that indicate they send extremely large requests to the server causing it to attempt to allocate large amounts of memory. |
| Default Value | 5 megabytes |
| Allowed Values | A positive integer representing a size. Upper limit is 2147483647 . |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the number of threads that are used to accept new client connections, and to perform any initial preparation on those connections that may be needed before the connection can be used to read requests and send responses. If the value is greater than zero, then the server will configure the specified number of threads for accepting client connections. A value of zero indicates that the server should attempt to automatically determine the best value for the underlying system (the value selected will half the number of available CPUs, although the automatically-selected value will not be less than two and not more than eight). |
| Default Value | 0 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Specifies the number of request handlers that are used to read requests from clients. The request handler threads are used to read requests from existing client connections. This ensures that new requests are read efficiently and that the connection handler itself does not become a bottleneck when the server is under heavy load from many clients at the same time. A value of zero will cause the server to attempt to automatically determine the best value for the underlying system (the value selected will be equal to the number of available CPUs). |
| Default Value | 0 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Specifies the policy that the LDAP Connection Handler should use regarding client SSL certificates. This is only applicable if clients are allowed to use SSL. |
| Default Value | optional |
| Allowed Values | disabled - Clients are not required to provide their own certificates when performing SSL negotiation. optional - Clients are requested to provide their own certificates when performing SSL negotiation, but still accept the connection even if the client does not provide a certificate. required - Clients are required to provide their own certificates when performing SSL negotiation and are refused access if they do not provide a certificate. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Specifies the names of the TLS protocols that are allowed for use in SSL or StartTLS communication. The set of supported ssl protocols can be viewed via the ssl context monitor entry. If the set of TLS protocols is not specified in this property, then the server will use the set of TLS protocols configured for the crypto manager. If the crypto manager is not configured with an explicit set of TLS protocols, then it will automatically determine an appropriate set of protocols to use. |
| Default Value | Use the set of TLS protocols configured in the crypto manager. |
| Allowed Values | A string |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the names of the TLS cipher suites that are allowed for use in SSL or StartTLS communication. The set of supported cipher suites can be viewed via the ssl context monitor entry. The default set of TLS cipher suites can be modified by adding entries that are pre-pended with either a '+' or a '-' character. Using a '+' will append the specified suite to the default set. Likewise, a '-' will remove the specified suite from the default set. Finally, an exact set of desired suites can be defined by adding entries that only contain the suite name. Exact values and modifications (+ or -) can not be combined. Doing so will result in configuration exception. The available set of cipher suites can be found in the monitor data under "cn=SSL Context,cn=monitor". If the set of TLS cipher suites is not specified in this property, then the server will use the set of TLS cipher suites configured for the crypto manager. If the crypto manager is not configured with an explicit set of TLS cipher suites, then it will automatically determine an appropriate set of cipher suites to use. |
| Default Value | Use the set of TLS cipher suites configured in the crypto manager. |
| Allowed Values | A string |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
close-connections-when-unavailable (Advanced Property)
| Description | Indicates whether all connections associated with this LDAP Connection Handler should be closed and no new connections accepted when the server has determined that it is "unavailable." This allows clients (or a network load balancer) to route requests to another server. a Directory Server instance might declare itself as unavailable for a variety of reasons, for instance if backend data has not been initialized yet or in the case of a Directory Proxy Server instance, no Directory Server instances are available. Smart clients such as the Directory Proxy Server can detect this by listening for alerts and checking the monitor backend for unavailable alert types. However, most clients will assume that if they can connect to the server that the server is fully functional. When this configuration setting is set to true and the server declares itself as unavailable, all connections on this handler will be closed and the server will close the port so that new connections are not accepted. The server will appear unavailable to clients, which will then connect to an available server. Outstanding operations are given a chance to complete before the connections are closed. When this is set to true, we recommend using two LDAP Connection Handlers: one for client traffic, with this option set to true, and one for administration and monitoring, with this option set to false. This allows the server to be visible to administrators but not to clients. When a Directory Server is accessed only through a Directory Proxy Server, enabling this option on the Directory Server is not necessary because the Directory Proxy Server can detect that the server has declared itself as unavailable. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
use-tcp-keep-alive (Advanced Property)
| Description | Indicates whether the LDAP Connection Handler should use TCP keep-alive. If enabled, the SO_KEEPALIVE socket option is used to indicate that TCP keepalive messages should periodically be sent to the client to verify that the associated connection is still valid. This may also help prevent cases in which intermediate network hardware could silently drop an otherwise idle client connection, provided that the keepalive interval configured in the underlying operating system is smaller than the timeout enforced by the network hardware. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
send-rejection-notice (Advanced Property)
| Description | Indicates whether the LDAP Connection Handler should send a notice of disconnection extended response message to the client if a new connection is rejected for some reason. The extended response message may provide an explanation indicating the reason that the connection was rejected. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
max-cancel-handlers (Advanced Property)
| Description | Specifies the maximum number of threads that are used to process cancel and abandon requests from clients. The LDAP Connection Handler uses a separate thread pool for processing cancel requests. This ensures that the connection handler itself does not become a bottleneck when the server is waiting for the canceled operation to complete. |
| Default Value | 16 |
| Allowed Values | An integer value. Lower limit is 1. Upper limit is 1000 . |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
request-handler-per-connection (Advanced Property)
| Description | Indicates whether a separate request handler thread should be created for each client connection, which can help avoid starvation of client connections for cases in which one or more clients send large numbers of concurrent asynchronous requests. This should only be used for cases in which a relatively small number of connections will be established at any given time, the connections established will generally be long-lived, and at least one client may send high volumes of asynchronous requests. This property can be used to alleviate possible blocking during long-running TLS negotiation on a single request handler which can result in it being unable to acknowledge further client requests until the TLS negotation completes or times out. If this is true, then the value of the num-request-handlers property will be ignored. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
accept-backlog (Advanced Property)
| Description | Specifies the maximum number of pending connection attempts that are allowed to queue up in the accept backlog before the server starts rejecting new connection attempts. This is primarily an issue for cases in which a large number of connections are established to the server in a very short period of time (for example, a benchmark utility that creates a large number of client threads that each have their own connection to the server) and the connection handler is unable to keep up with the rate at which the new connections are established. |
| Default Value | 128 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
max-blocked-write-time-limit (Advanced Property)
| Description | Specifies the maximum length of time that attempts to write data to LDAP clients should be allowed to block. If an attempt to write data to a client takes longer than this length of time, then the client connection is terminated. |
| Default Value | 2 minutes |
| Allowed Values | A duration. Lower limit is 0 milliseconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
auto-authenticate-using-client-certificate (Advanced Property)
| Description | Indicates whether to attempt to automatically authenticate a client connection that has established a secure communication channel (using either SSL or StartTLS) and presented its own client certificate. Generally, clients should use the SASL EXTERNAL mechanism to authenticate using a client certificate, but some clients may not support that capability and/or may expect automatic authentication. An internal SASL EXTERNAL bind will be performed using the client connection. As such, the EXTERNAL SASL mechanism handler must be properly configured to allow this. This option will only be used for client connections which are not already authenticated. In the case of a StartTLS operation in which the client connection had previously been authenticated, that authentication will remain intact. If the client cannot be successfully authenticated based on the information contained in the provided certificate, then the connection will remain unauthenticated. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
close-connections-on-explicit-gc (Advanced Property)
| Description | Indicates whether all connections associated with this LDAP Connection Handler should be closed before an explicit garbage collection is performed to allow clients to route requests to another server. When an explicit garbage collection is performed by either an Explicit GC Task or the Periodic GC Plugin, the server might be unresponsive for several seconds. During this time, other servers in the topology can handle the LDAP traffic, but the client fail-over process can be accelerated by explicitly closing the connections prior to the garbage collection. Outstanding operations are given a chance to complete before the connections are closed. When a Directory Server is accessed only through a Directory Proxy Server, enabling this option is not necessary because the Directory Proxy Server can detect that the explicit GC is about to occur by monitoring the degraded alert type. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured Connection Handlers:
dsconfig list-connection-handlers
[--property {propertyName}] ...
To view the configuration for an existing Connection Handler:
dsconfig get-connection-handler-prop
--handler-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Connection Handler:
dsconfig set-connection-handler-prop
--handler-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new LDAP Connection Handler:
dsconfig create-connection-handler
--handler-name {name}
--type ldap
--set enabled:{propertyValue}
--set listen-port:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Connection Handler:
dsconfig delete-connection-handler
--handler-name {name}