Directory Services 7.2.5

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

The LDAP Connection Handler object inherits from Connection Handler.

Dependencies

LDAP Connection Handlers depend on the following objects:

LDAP Connection Handler properties

You can use configuration expressions to set property values at startup time. For details, see Property value substitution.

Basic Properties Advanced Properties

advertised-listen-address
allow-ldap-v2
allow-start-tls
allowed-client
denied-client
enabled
keep-stats
key-manager-provider
listen-address
listen-port
proxy-protocol-allowed-client
proxy-protocol-enabled
restricted-client
restricted-client-connection-limit
ssl-cert-nickname
ssl-cipher-suite
ssl-client-auth-policy
ssl-protocol
trust-manager-provider
use-ssl

accept-backlog
allow-tcp-reuse-address
buffer-size
java-class
max-blocked-write-time-limit
max-request-size
num-request-handlers
send-rejection-notice
use-tcp-keep-alive
use-tcp-no-delay

Basic properties

Use the --advanced option to access advanced properties.

advertised-listen-address

Synopsis

The advertised address(es) which clients should use for connecting to this LDAP Connection Handler.

Description

Multiple addresses may be provided as separate values for this attribute. The meta-address 0.0.0.0 is not permitted.

Default value

None

Allowed values

A hostname or an IP address.

Multi-valued

Yes

Required

Yes

Admin action required

None

Advanced

No

Read-only

No

allow-ldap-v2

Synopsis

Indicates whether connections from LDAPv2 clients are allowed.

Description

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

Advanced

No

Read-only

No

allow-start-tls

Synopsis

Indicates whether clients are allowed to use StartTLS.

Description

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

Advanced

No

Read-only

No

allowed-client

Synopsis

A set of clients who will be allowed to establish connections to this Connection Handler.

Description

Valid values include a host name, a fully qualified domain name, a domain name, an IP address, or a subnetwork with subnetwork mask. Specifying a value for this property in a connection handler will override any value set in the global configuration.

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 property take effect immediately and do not interfere with established connections.

Advanced

No

Read-only

No

denied-client

Synopsis

A set of clients who are not allowed to establish connections to this Connection Handler.

Description

Valid values include a host name, a fully qualified domain name, a domain name, an IP address, or a subnetwork with subnetwork mask. 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. Specifying a value for this property in a connection handler will override any value set in the global configuration.

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 property take effect immediately and do not interfere with established connections.

Advanced

No

Read-only

No

enabled

Synopsis

Indicates whether the Connection Handler is enabled.

Default value

None

Allowed values

true

false

Multi-valued

No

Required

Yes

Admin action required

None

Advanced

No

Read-only

No

keep-stats

Synopsis

Indicates whether the LDAP Connection Handler should keep statistics.

Description

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

Advanced

No

Read-only

No

key-manager-provider

Synopsis

Specifies the name of the key manager that should be used with this LDAP Connection Handler .

Default value

None

Allowed values

The name of an existing 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.

Advanced

No

Read-only

No

listen-address

Synopsis

The network interface(s) on which this LDAP Connection Handler should listen for incoming client connections.

Description

Multiple addresses may be provided as separate values for this attribute. If no values are provided, then the directory server will listen on all interfaces.

Default value

0.0.0.0

Allowed values

A hostname or an IP address.

Multi-valued

Yes

Required

No

Admin action required

The object must be disabled and re-enabled for changes to take effect.

Advanced

No

Read-only

No

listen-port

Synopsis

Specifies the port number on which the LDAP Connection Handler will listen for connections from clients.

Description

Only a single port number may be provided.

Default value

None

Allowed values

An integer.

Lower limit: 1.

Upper limit: 65535.

Multi-valued

No

Required

Yes

Admin action required

The object must be disabled and re-enabled for changes to take effect.

Advanced

No

Read-only

No

proxy-protocol-allowed-client

Synopsis

When the proxy protocol is enabled, this property represents the set of clients who will be allowed to establish connections to this LDAP Connection Handler and will be required to use proxy protocol.

Description

Valid values include a host name, a fully qualified domain name, a domain name, an IP address, or a subnetwork with subnetwork mask. Specifying a value for this property in a connection handler will override any value set in the global configuration.

Default value

If the proxy protocol is enabled then only clients with addresses matching an address on the proxy-protocol-allowed-client list and using proxy protocol are allowed.

Allowed values

An IP address mask.

Multi-valued

Yes

Required

No

Admin action required

None

Changes to this property take effect immediately and do not interfere with established connections.

Advanced

No

Read-only

No

proxy-protocol-enabled

Synopsis

Indicates whether the proxy protocol is enabled.

Description

If enabled, the LDAP Connection Handler makes the server use proxy protocol for connections with a source IP address matching an address in the proxy-protocol-allowed-client list.

Default value

false

Allowed values

true

false

Multi-valued

No

Required

No

Admin action required

None

Advanced

No

Read-only

No

restricted-client

Synopsis

A set of clients who will be limited to the maximum number of connections specified by the "restricted-client-connection-limit" property.

Description

Valid values include a host name, a fully qualified domain name, a domain name, an IP address, or a subnetwork with subnetwork mask. Specifying a value for this property in a connection handler will override any value set in the global configuration.

Default value

No restrictions are imposed on the number of connections a client can open.

Allowed values

An IP address mask.

Multi-valued

Yes

Required

No

Admin action required

None

Changes to this property take effect immediately and do not interfere with established connections.

Advanced

No

Read-only

No

restricted-client-connection-limit

Synopsis

Specifies the maximum number of connections a restricted client can open at the same time to this Connection Handler.

Description

Once Directory Server accepts the specified number of connections from a client specified in restricted-client, any additional connection will be rejected. The number of connections is maintained by IP address. Specifying a value for this property in a connection handler will override any value set in the global configuration.

Default value

100

Allowed values

An integer.

Lower limit: 0.

Multi-valued

No

Required

No

Admin action required

None

Changes to this property take effect immediately and do not interfere with established connections.

Advanced

No

Read-only

No

ssl-cert-nickname

Synopsis

Specifies the nicknames (also called the aliases) of the keys or key pairs that the LDAP Connection Handler should use when performing SSL communication.

Description

The property can be used multiple times (referencing different nicknames) when server certificates with different public key algorithms are used in parallel (for example, RSA, DSA, and ECC-based algorithms). When a nickname refers to an asymmetric (public/private) key pair, the nickname for the public key certificate and associated private key entry must match exactly. A single nickname is used to retrieve both the public key and the private key. 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

Yes

Required

No

Admin action required

The object must be disabled and re-enabled for changes to take effect.

Advanced

No

Read-only

No

ssl-cipher-suite

Synopsis

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

No

Read-only

No

ssl-client-auth-policy

Synopsis

Specifies the policy that the LDAP Connection Handler should use regarding client SSL certificates. Clients can use the SASL EXTERNAL mechanism only if the policy is set to "optional" or "required".

Description

This is only applicable if clients are allowed to use SSL.

Default value

optional

Allowed values

  • disabled: Clients must not provide their own certificates when performing SSL negotiation.

  • optional: Clients are requested to provide their own certificates when performing SSL negotiation. The connection is nevertheless accepted 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 object must be disabled and re-enabled for changes to take effect.

Advanced

No

Read-only

No

ssl-protocol

Synopsis

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.

Advanced

No

Read-only

No

trust-manager-provider

Synopsis

Specifies the name(s) of the trust manager(s) that should be used with the LDAP Connection Handler .

Default value

None

Allowed values

The name of an existing trust-manager-provider.

The referenced trust manager provider must be enabled when the LDAP Connection Handler is enabled, configured to use SSL or StartTLS and its SSL client auth policy is set to required or optional.

Multi-valued

Yes

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.

Advanced

No

Read-only

No

use-ssl

Synopsis

Indicates whether the LDAP Connection Handler should use SSL.

Description

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 object must be disabled and re-enabled for changes to take effect.

Advanced

No

Read-only

No

Advanced properties

Use the --advanced option to access advanced properties.

accept-backlog

Synopsis

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.

Description

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.

Lower limit: 1.

Multi-valued

No

Required

No

Admin action required

The object must be disabled and re-enabled for changes to take effect.

Advanced

Yes

Read-only

No

allow-tcp-reuse-address

Synopsis

Indicates whether the LDAP Connection Handler should reuse socket descriptors.

Description

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 object must be disabled and re-enabled for changes to take effect.

Advanced

Yes

Read-only

No

buffer-size

Synopsis

Specifies the size in bytes of the LDAP response message write buffer.

Description

This property specifies write buffer size allocated by the server for each client connection and used to buffer LDAP response messages data when writing.

Default value

4096 bytes

Allowed values

Uses size syntax.

Lower limit: 1.

Upper limit: 2147483647.

Multi-valued

No

Required

No

Admin action required

None

Advanced

Yes

Read-only

No

java-class

Synopsis

Specifies the fully-qualified name of the Java class that provides the LDAP Connection Handler implementation.

Default value

org.opends.server.protocols.ldap.LDAPConnectionHandler

Allowed values

A Java class that extends or implements:

  • org.opends.server.api.ConnectionHandler

Multi-valued

No

Required

Yes

Admin action required

The object must be disabled and re-enabled for changes to take effect.

Advanced

Yes

Read-only

No

max-blocked-write-time-limit

Synopsis

Specifies the maximum length of time that attempts to write data to LDAP clients should be allowed to block.

Description

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

Lower limit: 0 milliseconds.

Multi-valued

No

Required

No

Admin action required

None

Advanced

Yes

Read-only

No

max-request-size

Synopsis

Specifies the size in bytes of the largest LDAP request message that will be allowed by this LDAP Connection handler.

Description

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

Uses size syntax.

Upper limit: 2147483647.

Multi-valued

No

Required

No

Admin action required

None

Advanced

Yes

Read-only

No

num-request-handlers

Synopsis

Specifies the number of request handlers that are used to read requests from clients.

Description

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.

Default value

Let the server decide.

Allowed values

An integer.

Lower limit: 1.

Multi-valued

No

Required

No

Admin action required

The object must be disabled and re-enabled for changes to take effect.

Advanced

Yes

Read-only

No

send-rejection-notice

Synopsis

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.

Description

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

Advanced

Yes

Read-only

No

use-tcp-keep-alive

Synopsis

Indicates whether the LDAP Connection Handler should use TCP keep-alive.

Description

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

Advanced

Yes

Read-only

No

use-tcp-no-delay

Synopsis

Indicates whether the LDAP Connection Handler should use TCP no-delay.

Description

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

Advanced

Yes

Read-only

No