LDAP External Server

Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.

LDAP External Servers are used to identify server instances and to control the connection to them.

Direct Subcomponents Parent Component Relations from This Component Relations to This Component Properties dsconfig Usage

Direct Subcomponents

The following LDAP External Servers are available in the server :

These LDAP External Servers inherit from the properties described below.

Parent Component

The LDAP External Server component inherits from the External Server

Relations from This Component

The following components have a direct aggregation relation from LDAP External Servers:

Relations to This Component

The following components have a direct aggregation relation to LDAP External Servers:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  verify-credentials-method
 server-host-name  health-check-connect-timeout
 server-port  max-connection-age
 location  min-expired-connection-disconnect-interval
 bind-dn  connect-timeout
 password  max-response-size
 passphrase-provider  initial-connections
 connection-security  max-connections
 authentication-method  defunct-connection-result-code
 key-manager-provider  abandon-on-timeout
 trust-manager-provider

Basic Properties

description

Description
A description for this External Server
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

server-host-name

Description
The host name or IP address of the target LDAP server.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

server-port

Description
The port number on which the server listens for requests.
Default Value
389
Allowed Values
An integer value. Lower limit is 1. Upper limit is 65535 .
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

location

Description
Specifies the location for the LDAP External Server.
Default Value
None
Allowed Values
The DN of any Location.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

bind-dn

Description
The DN to use to bind to the target LDAP server if simple authentication is required.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

password

Description
The login password for the specified user.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

passphrase-provider

Description
The passphrase provider to use to obtain the login password for the specified user.
Default Value
None
Allowed Values
The DN of any Passphrase Provider.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

connection-security

Description
The mechanism to use to secure communication with the directory server.
Default Value
none
Allowed Values
none - No connection security should be used (i.e., unencrypted LDAP).

ssl - SSL should be used to encrypt communication (i.e., LDAPS).

starttls - StartTLS should be used to encrypt communication.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

authentication-method

Description
The mechanism to use to authenticate to the target server.
Default Value
simple
Allowed Values
none - No authentication should be performed on the connection.

simple - Simple authentication (using a DN and password) should be performed on the connection.

external - SASL EXTERNAL authentication should be performed on the connection.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

key-manager-provider

Description
The key manager provider to use if SSL or StartTLS is to be used for connection-level security. When specifying a value for this property (except when using the Null key manager provider) you must ensure that the external server trusts this server's public certificate by adding this server's public certificate to the external server's trust store.
Default Value
None
Allowed Values
The DN of any Key Manager Provider. The associated key manager provider must exist and must be enabled if SSL or StartTLS is to be used.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

trust-manager-provider

Description
The trust manager provider to use if SSL or StartTLS is to be used for connection-level security.
Default Value
None
Allowed Values
The DN of any Trust Manager Provider. The associated trust manager provider must exist and must be enabled if SSL or StartTLS is to be used.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


Advanced Properties

verify-credentials-method (Advanced Property)

Description
The mechanism to use to verify user credentials while ensuring that the ability to process other operations is not impacted by an alternate authorization identity.
Default Value
separate-connections
Allowed Values
separate-connections - Use one set of connections for processing bind operations and a separate set of connections for all other operations.

retain-identity-control - Use a single set of connections for processing binds and all other types of operations, but use the retain identity request control to process bind operations without changing the identity of the associated connection.

bind-on-existing-connections - Use the same set of connections for processing binds and all other types of operations, and do not do anything to prevent the binds from altering the identity of the connections. This should only be used in conjunction with the rebind authorization method.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

health-check-connect-timeout (Advanced Property)

Description
Specifies the maximum length of time to wait for a connection to be established for the purpose of performing a health check. If the connection cannot be established within this length of time, the server will be classified as unavailable. If no value is specified, then the value of the connect-timeout configuration property will be used. A value of zero seconds indicates that no connect timeout should be enforced, although the network stack of the underlying operating system may enforce a limit.
Default Value
The value of the connect-timeout property will be used as the health check connect timeout.
Allowed Values
A duration. Lower limit is 0 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

max-connection-age (Advanced Property)

Description
Specifies the maximum length of time that connections to this server should be allowed to remain established before being closed and replaced with newly-established connections. A value of zero seconds indicates that no maximum connection age should be applied.
Default Value
600 seconds
Allowed Values
A duration. Lower limit is 0 milliseconds.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

min-expired-connection-disconnect-interval (Advanced Property)

Description
Specifies the minimum length of time that should pass between connection closures as a result of the connections being established for longer than the maximum connection age. This may help avoid cases in which a large number of connections are closed and re-established in a short period of time because of the maximum connection age.
Default Value
1000 milliseconds
Allowed Values
A duration. Lower limit is 0 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

connect-timeout (Advanced Property)

Description
Specifies the maximum length of time to wait for a connection to be established before giving up and considering the server unavailable. A value of zero seconds indicates that no connect timeout should be enforced, although the network stack of the underlying operating system may enforce a limit.
Default Value
10 seconds
Allowed Values
A duration. Lower limit is 0 milliseconds.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

max-response-size (Advanced Property)

Description
Specifies the maximum response size that should be supported for messages received from the LDAP external server. A value of zero bytes indicates that no maximum response size should be enforced.
Default Value
10 megabytes
Allowed Values
A positive integer representing a size.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

initial-connections (Advanced Property)

Description
The number of connections to initially establish to the LDAP external server. A value of zero indicates that the number of connections should be dynamically based on the number of available worker threads. This will be ignored when using a thread-local connection pool.
Default Value
0
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

max-connections (Advanced Property)

Description
The maximum number of concurrent connections to maintain for the LDAP external server. A value of zero indicates that the number of connections should be dynamically based on the number of available worker threads. This will be ignored when using a thread-local connection pool.
Default Value
0
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

defunct-connection-result-code (Advanced Property)

Description
Specifies the operation result code values that should cause the associated connection should be considered defunct. If an operation fails with one of these result codes, then it will be terminated and an attempt will be made to establish a new connection in its place.
Default Value
operations-error
protocol-error
busy
unavailable
unwilling-to-perform
other
server-down
local-error
encoding-error
decoding-error
no-memory
connect-error
timeout
Allowed Values
success - Operation processing completed successfully.

operations-error - An error occurred related to the ordering of operations.

protocol-error - An error occurred while parsing the request from the client.

time-limit-exceeded - Search processing took longer than the maximum allowed time to complete.

size-limit-exceeded - The associated search request matched more entries than are allowed to be returned to the client.

compare-false - The assertion contained in the associated compare request did not match the target entry.

compare-true - The assertion contained in the associated compare request matched target entry.

auth-method-not-supported - The requested authentication type is not supported.

strong-auth-required - Strong authentication is required for the requested operation.

referral - A referral was encountered while processing the operation.

admin-limit-exceeded - An administrative limit was exceeded while processing the operation.

unavailable-critical-extension - A critical control included in the request could not be processed.

confidentiality-required - The requested operation requires confidentiality for communication between the client and the server.

sasl-bind-in-progress - A multi-stage SASL bind operation is in progress.

no-such-attribute - A specified attribute did not exist in the target entry.

undefined-attribute-type - A specified attribute type does is not defined in the server schema.

inappropriate-matching - The operation attempted to perform a type of comparison against a specified attribute that is not allowed for that attribute type.

constraint-violation - The operation would have violated a constraint defined in the server.

attribute-or-value-exists - The operation would have resulted in a conflict with an existing attribute or attribute value in the target entry.

invalid-attribute-syntax - An attribute value was provided that is not valid according to the associated attribute syntax.

no-such-object - The operation targeted an entry that does not exist.

alias-problem - An attempt was made to perform an illegal operation against an alias.

invalid-dn-syntax - A provided value could not be parsed as a valid distinguished name.

alias-dereferencing-problem - A problem occurred while attempting to dereference an alias during search processing.

inappropriate-authentication - The attempted authentication type was not appropriate for the target user.

invalid-credentials - The bind credentials provided were not valid.

insufficient-access-rights - The user does not have permission to perform the requested operation.

busy - The server is too busy to process the requested operation.

unavailable - The server is not available to process client requests.

unwilling-to-perform - The server is not willing to process the requested operation.

loop-detect - A referral or chaining loop was encountered while processing the request.

sort-control-missing - The search request contained the virtual list view request control but was missing the required server-side sort request control.

offset-range-error - The search request contained the virtual list view request control with an invalid offset or range.

naming-violation - The operation would have resulted in an entry that violates the server's naming constraints.

object-class-violation - The operation would have resulted in an entry that violates schema constraints for the object classes contained in the entry.

not-allowed-on-nonleaf - The requested operation is not allowed for non-leaf entries.

not-allowed-on-rdn - The requested operation attempted to alter an RDN attribute value in a manner that is not allowed.

entry-already-exists - The requested operation would have resulted in an entry that conflicts with an entry that already exists in the server.

object-class-mods-prohibited - The requested operation would have modified the object classes contained in the target entry in a manner that is not allowed.

affects-multiple-dsas - The requested operation would have required updating entries that exist in multiple servers.

virtual-list-view-error - An error occurred while performing virtual list view processing.

other - An error occurred which does not fit any other defined result code.

server-down - An established connection was closed by the server.

local-error - A generic client-side error occurred.

encoding-error - An error occurred while attempting to encode a request to send to the server.

decoding-error - An error occurred while attempting to decode a response read from the server.

timeout - No response was received within the configured client-side time limit.

auth-unknown - The client attempted to perform an unknown type of authentication.

filter-error - An error occurred while attempting to parse or encode a search filter.

user-canceled - The operation was canceled by the requester.

param-error - An invalid parameter was encountered while attempting to prepare communication with the server.

no-memory - An out-of-memory error was encountered during processing.

connect-error - An error occurred while attempting to establish a connection to the target server.

not-supported - The requested operation is not supported.

control-not-found - An expected control was not found in a response from the server.

no-results-returned - No results were returned by the server.

more-results-to-return - The server returned more results than expected.

client-loop - A client-side referral loop was detected.

referral-limit-exceeded - Too many referrals were encountered while attempting to process a request.

canceled - The operation was canceled.

no-such-operation - The target operation could not be canceled because it did not exist or had already completed.

too-late - The target operation could not be canceled because the server had already completed too much processing on the operation to allow it to be canceled.

cannot-cancel - The target operation could not be canceled because operations of that type cannot be canceled.

assertion-failed - The target entry did not match the filter contained in the assertion request control.

authorization-denied - The client does not have permission to use the proxied authorization control.

no-operation - No problems were encountered while processing the operation, but no changes were applied because the request included the no-op control.

interactive-transaction-aborted - The interactive transaction has been aborted.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

abandon-on-timeout (Advanced Property)

Description
Indicates whether to send an abandon request for an operation for which a response timeout is encountered. A request which has timed out on one server may be retried on another server regardless of whether an abandon request is sent, but if the initial attempt is not abandoned then a long-running operation may unnecessarily continue to consume processing resources on the initial server. Note that even if an abandon request is sent for an operation that has timed out, there is no guarantee that it will be successfully abandoned. The server may have completed its processing (or reached a point of no return) prior to receiving the abandon request. If processing on the target operation completes (either because no abandon request is sent, or because the abandon request arrives too late), then it may or may not have been successful, and, in the case of a write operation, may or may not have altered content in the target server.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured External Servers:

dsconfig list-external-servers
     [--property {propertyName}] ...

To view the configuration for an existing External Server:

dsconfig get-external-server-prop
     --server-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing External Server:

dsconfig set-external-server-prop
     --server-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new LDAP External Server:

dsconfig create-external-server
     --server-name {name}
     --type ldap
     --set server-host-name:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing External Server:

dsconfig delete-external-server
     --server-name {name}