Proxy Backend

A Proxy Backend forwards LDAP requests to other servers.

A Proxy Backend uses the proxied authorization control to forward LDAP requests on behalf of the proxy users. As a consequence, the remote servers must support the proxied authorization control and the proxy user must have appropriate privileges and permissions allowing them to use the control.

Parent

The Proxy Backend object inherits from Backend.

Dependencies

Proxy Backends depend on the following objects:

Proxy Backend Properties

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

Basic Properties Advanced Properties

backend-id
base-dn
connection-pool-idle-timeout
connection-pool-max-size
connection-pool-min-size
connection-timeout
discovery-interval
enabled
heartbeat-interval
heartbeat-search-request-base-dn
key-manager-provider
partition-base-dn
proxy-user-dn
proxy-user-password
route-all
shard
ssl-cert-nickname
use-sasl-external

hash-function
java-class

Basic Properties

Use the --advanced option to access advanced properties.

backend-id

Synopsis

Specifies a name to identify the associated backend.

Description

The name must be unique among all backends in the server. The backend ID may not be altered after the backend is created in the server.

Default Value

None

Allowed Values

A string.

Multi-valued

No

Required

Yes

Admin Action Required

None

Advanced

No

Read-Only

Yes

base-dn

Synopsis

Specifies the base DN(s) for the data that the backend handles.

Description

A single backend may be responsible for one or more base DNs. Note that no two backends may have the same base DN although one backend may have a base DN that is below a base DN provided by another backend (similar to the use of sub-suffixes in the Sun Java System Directory Server). If any of the base DNs is subordinate to a base DN for another backend, then all base DNs for that backend must be subordinate to that same base DN. When the "route-all" property is set to "true" then the "base-dn" property is ignored.

Default Value

Unless route-all is enabled, a proxy with empty base DNs does not handle any requests. This helps incrementally building a proxy’s configuration.

Allowed Values

A valid DN.

Multi-valued

Yes

Required

No

Admin Action Required

None

No administrative action is required.

Advanced

No

Read-Only

No

connection-pool-idle-timeout

Synopsis

The time out period after which unused non-core connections will be closed and removed from the connection pool.

Default Value

10s

Allowed Values

Lower limit: 1 milliseconds.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

connection-pool-max-size

Synopsis

Maximum size of the connection pool for each remote server

Default Value

1024

Allowed Values

An integer.

Use "-1" or "unlimited" to indicate no limit.

Lower limit: 0.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

connection-pool-min-size

Synopsis

Minimum size of the connection pool for each remote server

Default Value

4

Allowed Values

An integer.

Use "-1" or "unlimited" to indicate no limit.

Lower limit: 0.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

connection-timeout

Synopsis

Specifies the timeout used when connecting to servers, performing SSL negotiation, and for individual search and bind requests.

Description

If the timeout expires then the current operation will be aborted and retried against another LDAP server if one is available.

Default Value

3s

Allowed Values

Lower limit: 10 milliseconds.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

discovery-interval

Synopsis

Interval between two server configuration discovery executions.

Description

Specifies how frequently to read the configuration of the servers in order to discover any configuration change.

Default Value

60s

Allowed Values

Lower limit: 1 seconds.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

enabled

Synopsis

Indicates whether the backend is enabled in the server.

Description

If a backend is not enabled, then its contents are not accessible when processing operations.

Default Value

None

Allowed Values

true

false

Multi-valued

No

Required

Yes

Admin Action Required

None

Advanced

No

Read-Only

No

heartbeat-interval

Synopsis

Specifies the heartbeat interval that the Proxy Backend will use when communicating with the remote servers.

Description

The Proxy Backend sends a heartbeat request to the servers every heartbeat interval. The heartbeat serves 3 purposes: keepalive, heartbeat and recovery. The hearbeat requests are small requests sent to prevent the connection from appearing idle and being forcefully closed (keepalive). The heartbeat responses inform the Proxy Backend the server is available (heartbeat). If a heartbeat answer is not received within the interval, the Proxy Backend closes the unresponsive connection and connects to another server. After an unresponsive connection is closed, the server is contacted each heartbeat interval to determine whether it is available again (recovery).

Default Value

10s

Allowed Values

Lower limit: 10 milliseconds.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

heartbeat-search-request-base-dn

Synopsis

Specifies the name of the entry that will be targeted by heartbeat requests.

Description

By default heartbeat requests will attempt to read the remote server’s root DSE, which is sufficient to determine whether the remote server is available, but it will not detect whether a particular backend is available. Set the heartbeat request base DN to the base entry of the backend containing application data in order to detect whether a remote server is available and handling requests against the backend.

Default Value

Allowed Values

A valid DN.

Multi-valued

No

Required

Yes

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 Proxy Backend.

Default Value

None

Allowed Values

The name of an existing key-manager-provider.

The referenced key manager provider must be enabled when the Proxy Backend is enabled and configured to use SASL/External certificate authentication.

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

partition-base-dn

Synopsis

Specifies the base DN(s) which is used for affinity load-balancing and data distribution

Description

Within a single shard, "affinity" load-balancing uses this setting to provide consistency for add/delete operations targeting entries within the same sub-tree. Entries immediately subordinate to the partition base DNs will be considered to be the root of a sub-tree whose entries belong to the same shard. For example, a partition base DN of "ou=people,dc=example,dc=com" would mean that "uid=bjensen,ou=people,dc=example,dc=com" and "deviceid=12345,uid=bjensen,ou=people,dc=example,dc=com" both belong to the same shard, and all operations targeting them would be routed to the same remote server. When applied to data distribution across multiple shards, this setting consistently routes operations targeting an entry below the partition DN to the same shard. Requests targeting the partition DN or above are routed to any shard. Search requests are routed to all shards unless their scope is under the partition DN. For example, if the partition base DN is set to "ou=people,dc=example,dc=com", a search with base DN "uid=bjensen,ou=people,dc=example,dc=com" or "deviceid=12345,uid=bjensen,ou=people,dc=example,dc=com" is always routed to the same shard. A search with base DN "ou=people,dc=example,dc=com" is routed to all shards.

Default Value

No consistency for add/delete operations.

Allowed Values

A valid DN.

Multi-valued

Yes

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

proxy-user-dn

Synopsis

The bind DN that is used to forward LDAP requests to remote servers.

Description

The proxy connects to the remote server using this bind DN and uses the proxied authorization control to forward requests on behalf of the proxy users. This bind DN must exist on all the remote servers.

Default Value

None

Allowed Values

A valid DN.

Multi-valued

No

Required

No

Admin Action Required

None

Advanced

No

Read-Only

No

proxy-user-password

Synopsis

Clear-text password associated with the proxy bind DN.

Description

The proxy password must be the same on all the remote servers.

Default Value

None

Allowed Values

A string.

Multi-valued

No

Required

No

Admin Action Required

None

Changes to this property will take effect the next time that the Proxy Backend is accessed.

Advanced

No

Read-Only

No

route-all

Synopsis

Route requests to all discovered public naming contexts.

Description

When the "route-all" property is set to "true" then the "base-dn" property is ignored.

Default Value

None

Allowed Values

true

false

Multi-valued

No

Required

Yes

Admin Action Required

None

Advanced

No

Read-Only

No

shard

Synopsis

Specifies one or more shards which will be used for distributing data and requests.

Description

When multiple shards are configured, this setting consistently routes write requests for the same target entry below the partition DN to the same shard. Requests targeting an entry under the partition DN are always routed to a single shard. Requests targeting the partition DN or above are routed to any shard. Search requests are routed to all shards unless their scope is under the partition DN. For example, a search with base DN "uid=bjensen,ou=people,dc=example,dc=com" or "deviceid=12345,uid=bjensen,ou=people,dc=example,dc=com" is always routed to the same shard. A search with base DN "ou=people,dc=example,dc=com" is routed to all shards.

Default Value

None

Allowed Values

The name of an existing service-discovery-mechanism.

Multi-valued

Yes

Required

Yes

Admin Action Required

None

Advanced

No

Read-Only

No

ssl-cert-nickname

Synopsis

Specifies the nicknames (also called the aliases) of the keys or key pairs that the Proxy Backend 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 Proxy Backend 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

use-sasl-external

Synopsis

Indicates whether the Proxy Backend should use certificate based authentication when communicating with backend servers.

Description

If enabled, the Proxy Backend will use mutual TLS when connecting to backend servers. Once the TLS handshake has completed, a SASL/External LDAP bind request will be sent in order to associate the TLS client certificate with an LDAP account on the remote backend server. A key manager provider containing the client certificate must be configured in order to use this feature.

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.

hash-function

Synopsis

Specifies the hash function which will be used for data distribution.

Description

This setting only applies to data distribution. Once this server is deployed, this setting must not be modified. Doing so could result in data loss. The hash function is used by the router to map incoming requests to a target server based on the request’s target DN. The role of the hash function is to ensure that the flow of incoming requests is evenly distributed on the set of servers.

Default Value

murmur3

Allowed Values

  • md5: Use the MD5 hash algorithm. This hash function does not distribute data evenly and should not be used in new deployments.

  • murmur3: Use the Murmur3 hash algorithm. This hash function distributes data more evenly than MD5 and should be used in new deployments.

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 backend implementation.

Default Value

org.opends.server.backends.ProxyBackend

Allowed Values

A Java class that extends or implements:

  • org.opends.server.api.Backend

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