UnboundID Metrics Engine - LDAP Connection Handler

Metrics Engine Documentation Index
Configuration Reference Home

LDAP Connection Handler

The LDAP Connection Handler is used to interact with clients using LDAP.

It provides full support for LDAPv3 and limited support for LDAPv2.

↓Parent Component
↓Relations from This Component
↓Properties
↓dsconfig Usage

Parent Component

The LDAP Connection Handler component inherits from the Connection Handler

Relations from This Component

The following components have a direct aggregation relation from LDAP Connection Handlers:

Key Manager Provider

Trust Manager Provider

Properties

The properties supported by this managed object are as follows:

Basic Properties:	Advanced Properties:
↓ description	↓ use-tcp-keep-alive
↓ enabled	↓ use-tcp-no-delay
↓ allowed-client	↓ allow-tcp-reuse-address
↓ denied-client	↓ send-rejection-notice
↓ listen-address	↓ max-cancel-handlers
↓ listen-port	↓ request-handler-per-connection
↓ use-ssl	↓ accept-backlog
↓ allow-start-tls	↓ max-blocked-write-time-limit
↓ ssl-cert-nickname	↓ disable-tls-renegotiation
↓ key-manager-provider	↓ auto-authenticate-using-client-certificate
↓ trust-manager-provider
↓ allow-ldap-v2
↓ keep-stats
↓ max-request-size
↓ num-request-handlers
↓ ssl-client-auth-policy
↓ ssl-protocol
↓ ssl-cipher-suite

Basic Properties

description

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

enabled

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

allowed-client

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.

denied-client

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.

listen-address

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. This modification requires that you disable and then re-enable this component for the change to take effect

listen-port

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	The LDAP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. This modification requires that you disable and then re-enable this component for the change to take effect

use-ssl

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. This modification requires that you disable and then re-enable this component for the change to take effect

allow-start-tls

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	None. Modification requires no further action

ssl-cert-nickname

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. This modification requires that you disable and then re-enable this component for the change to take effect

key-manager-provider

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.

trust-manager-provider

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.

allow-ldap-v2

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

keep-stats

Description	Indicates whether the LDAP Connection Handler should keep statistics. If enabled, the LDAP Connection Handler maintains statistics about the number and types of operations requested over LDAP and the amount of data sent and received.
Default Value	true
Allowed Values	true false
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

max-request-size

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

num-request-handlers

Description	Specifies the number of request handlers that are used to read requests from clients. The LDAP Connection Handler uses one thread to accept new connections from clients, but uses one or more additional threads 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. This modification requires that you disable and then re-enable this component for the change to take effect

ssl-client-auth-policy

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 the 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. This modification requires that you disable and then re-enable this component for the change to take effect

ssl-protocol

Description	Specifies the names of the SSL protocols that are allowed for use in SSL or StartTLS communication.
Default Value	Uses the default set of SSL protocols provided by the server's JVM.
Allowed Values	A string
Multi-Valued	Yes
Required	No
Admin Action Required	None. Changes to this property take effect immediately but only impact new SSL/TLS-based sessions created after the change.

ssl-cipher-suite

Description	Specifies the names of the SSL cipher suites that are allowed for use in SSL or StartTLS communication.
Default Value	Uses the default set of SSL cipher suites provided by the server's JVM.
Allowed Values	A string
Multi-Valued	Yes
Required	No
Admin Action Required	None. Changes to this property take effect immediately but will only impact new SSL/TLS-based sessions created after the change.

Advanced Properties

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

use-tcp-no-delay (Advanced Property)

Description	Indicates whether the LDAP Connection Handler should use TCP no-delay. If enabled, the TCP_NODELAY socket option is used to ensure that response messages to the client are sent immediately rather than potentially waiting to determine whether additional response messages can be sent in the same packet. In most cases, using the TCP_NODELAY socket option provides better performance and lower response times, but disabling it may help for some cases in which the server sends a large number of entries to a client in response to a search request.
Default Value	true
Allowed Values	true false
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

allow-tcp-reuse-address (Advanced Property)

Description	Indicates whether the LDAP Connection Handler should reuse socket descriptors. If enabled, the SO_REUSEADDR socket option is used on the server listen socket to potentially allow the reuse of socket descriptors for clients in a TIME_WAIT state. This may help the server avoid temporarily running out of socket descriptors in cases in which a very large number of short-lived connections have been established from the same client system.
Default Value	true
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. This modification requires that you disable and then re-enable this component for the change to take effect

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. This modification requires that you disable and then re-enable this component for the change to take effect

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. 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. This modification requires that you disable and then re-enable this component for the change to take effect

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. This modification requires that you disable and then re-enable this component for the change to take effect

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

disable-tls-renegotiation (Advanced Property)

Description	Indicates whether to allow TLS renegotiation during SSL and StartTLS communication. TLS renegotiation has been known to introduce security problems in older SSL/TLS implementations because it could be possible for a man-in-the-middle attacker to inject arbitrary plaintext into the cipher stream under a limited set of circumstances. If you are using a recent JVM version, it will likely include a fix for this problem (e.g., all versions of Oracle Java SE 7 should be immune to the problem by default, as should Oracle Java SE 6 update 22 or later). However, older JVMs may not
Default Value	In JVM versions known to include support for the fix outlined in RFC 5746 (Oracle Java SE 6 update 22 or later, or any version of Oracle Java SE 7 or later) renegotiation will be allowed by default. In all other JVMs, it will be denied by default.
Allowed Values	true false
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

dsconfig Usage

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}