<?xml version="1.0" encoding="utf-8"?>

<adm:managed-object name="http-connection-handler"

plural-name="http-connection-handlers"

package="org.forgerock.opendj.server.config" extends="connection-handler"

xmlns:adm="http://opendj.forgerock.org/admin"

xmlns:ldap="http://opendj.forgerock.org/admin-ldap">

<adm:synopsis>

The

<adm:user-friendly-name />

is used to interact with clients using HTTP.

</adm:synopsis>

<adm:description>

It provides full support for Rest2LDAP.

</adm:description>

<adm:constraint>

<adm:synopsis>

A Key Manager Provider must be specified when this

<adm:user-friendly-name />

is enabled and it is configured to use SSL.

</adm:synopsis>

<adm:condition>

<adm:implies>

<adm:contains property="enabled" value="true" />

<adm:implies>

<adm:contains property="use-ssl" value="true" />

<adm:is-present property="key-manager-provider" />

</adm:implies>

</adm:implies>

</adm:condition>

</adm:constraint>

<adm:constraint>

<adm:synopsis>

A Trust Manager Provider must be specified when this

<adm:user-friendly-name />

is enabled and it is configured to use SSL.

</adm:synopsis>

<adm:condition>

<adm:implies>

<adm:contains property="enabled" value="true" />

<adm:implies>

<adm:contains property="use-ssl" value="true" />

<adm:is-present property="trust-manager-provider" />

</adm:implies>

</adm:implies>

</adm:condition>

</adm:constraint>

<adm:profile name="ldap">

<ldap:object-class>

<ldap:name>ds-cfg-http-connection-handler</ldap:name>

<ldap:superior>ds-cfg-connection-handler</ldap:superior>

</ldap:object-class>

</adm:profile>

<adm:property-override name="java-class" advanced="true">

<adm:default-behavior>

<adm:defined>

<adm:value>

org.opends.server.protocols.http.HTTPConnectionHandler

</adm:value>

</adm:defined>

</adm:default-behavior>

</adm:property-override>

<adm:property-reference name="listen-port" />

<adm:property-reference name="use-ssl" />

<adm:property-reference name="ssl-cert-nickname" />

<adm:property-reference name="use-tcp-keep-alive" />

<adm:property-reference name="use-tcp-no-delay" />

<adm:property-reference name="allow-tcp-reuse-address" />

<adm:property name="key-manager-provider">

<adm:synopsis>

Specifies the name of the key manager that should be used with

this

<adm:user-friendly-name />

.

</adm:synopsis>

<adm:requires-admin-action>

<adm:none>

<adm:synopsis>

Changes to this property take effect immediately, but

only for subsequent attempts to access the key manager

provider for associated client connections.

</adm:synopsis>

</adm:none>

</adm:requires-admin-action>

<adm:default-behavior>

<adm:undefined />

</adm:default-behavior>

<adm:syntax>

<adm:aggregation relation-name="key-manager-provider"

parent-path="/">

<adm:constraint>

<adm:synopsis>

The referenced key manager provider must be enabled when

the

<adm:user-friendly-name />

is enabled and configured to use SSL.

</adm:synopsis>

<adm:target-needs-enabling-condition>

<adm:and>

<adm:contains property="enabled" value="true" />

<adm:contains property="use-ssl" value="true" />

</adm:and>

</adm:target-needs-enabling-condition>

<adm:target-is-enabled-condition>

<adm:contains property="enabled" value="true" />

</adm:target-is-enabled-condition>

</adm:constraint>

</adm:aggregation>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-key-manager-provider</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="trust-manager-provider">

<adm:synopsis>

Specifies the name of the trust manager that should be used with

the

<adm:user-friendly-name />

.

</adm:synopsis>

<adm:requires-admin-action>

<adm:none>

<adm:synopsis>

Changes to this property take effect immediately, but

only for subsequent attempts to access the trust manager

provider for associated client connections.

</adm:synopsis>

</adm:none>

</adm:requires-admin-action>

<adm:default-behavior>

<adm:undefined />

</adm:default-behavior>

<adm:syntax>

<adm:aggregation relation-name="trust-manager-provider"

parent-path="/">

<adm:constraint>

<adm:synopsis>

The referenced trust manager provider must be enabled when

the

<adm:user-friendly-name />

is enabled and configured to use SSL.

</adm:synopsis>

<adm:target-needs-enabling-condition>

<adm:and>

<adm:contains property="enabled" value="true" />

<adm:contains property="use-ssl" value="true" />

</adm:and>

</adm:target-needs-enabling-condition>

<adm:target-is-enabled-condition>

<adm:contains property="enabled" value="true" />

</adm:target-is-enabled-condition>

</adm:constraint>

</adm:aggregation>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-trust-manager-provider</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="listen-address" multi-valued="true">

<adm:synopsis>

Specifies the address or set of addresses on which this

<adm:user-friendly-name />

should listen for connections from HTTP clients.

</adm:synopsis>

<adm:description>

Multiple addresses may be provided as separate values for this

attribute. If no values are provided, then the

<adm:user-friendly-name />

listens on all interfaces.

</adm:description>

<adm:requires-admin-action>

<adm:component-restart />

</adm:requires-admin-action>

<adm:default-behavior>

<adm:defined>

<adm:value>0.0.0.0</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:ip-address />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-listen-address</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="keep-stats">

<adm:synopsis>

Indicates whether the

<adm:user-friendly-name />

should keep statistics.

</adm:synopsis>

<adm:description>

If enabled, the

<adm:user-friendly-name />

maintains statistics about the number and types of operations

requested over HTTP and the amount of data sent and received.

</adm:description>

<adm:default-behavior>

<adm:defined>

<adm:value>true</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:boolean />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-keep-stats</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="max-request-size" advanced="true">

<adm:synopsis>

Specifies the size in bytes of the largest HTTP request message that will

be allowed by the <adm:user-friendly-name />.

</adm:synopsis>

<adm:description>

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.

</adm:description>

<adm:default-behavior>

<adm:defined>

<adm:value>5 megabytes</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:size upper-limit="2147483647b"></adm:size>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-max-request-size</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="buffer-size" advanced="true">

<adm:synopsis>

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

</adm:synopsis>

<adm:description>

This property specifies write buffer size allocated by the server for

each client connection and used to buffer HTTP response messages data

when writing.

</adm:description>

<adm:default-behavior>

<adm:defined>

<adm:value>4096 bytes</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:size lower-limit="1b" upper-limit="2147483647b"></adm:size>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-buffer-size</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="num-request-handlers" advanced="true">

<adm:synopsis>

Specifies the number of request handlers that are used to read

requests from clients.

</adm:synopsis>

<adm:description>

The

<adm:user-friendly-name />

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.

</adm:description>

<adm:requires-admin-action>

<adm:component-restart />

</adm:requires-admin-action>

<adm:default-behavior>

<adm:alias>

<adm:synopsis>

Let the server decide.

</adm:synopsis>

</adm:alias>

</adm:default-behavior>

<adm:syntax>

<adm:integer lower-limit="1" />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-num-request-handlers</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="ssl-client-auth-policy">

<adm:synopsis>

Specifies the policy that the

<adm:user-friendly-name />

should use regarding client SSL certificates.

Clients can use the SASL EXTERNAL mechanism only if the

policy is set to "optional" or "required".

</adm:synopsis>

<adm:description>

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

</adm:description>

<adm:requires-admin-action>

<adm:component-restart />

</adm:requires-admin-action>

<adm:default-behavior>

<adm:defined>

<adm:value>optional</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:enumeration>

<adm:value name="disabled">

<adm:synopsis>

Clients must not provide their own

certificates when performing SSL negotiation.

</adm:synopsis>

</adm:value>

<adm:value name="optional">

<adm:synopsis>

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.

</adm:synopsis>

</adm:value>

<adm:value name="required">

<adm:synopsis>

Clients are required to provide their own certificates

when performing SSL negotiation and are refused access

if they do not provide a certificate.

</adm:synopsis>

</adm:value>

</adm:enumeration>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-ssl-client-auth-policy</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="accept-backlog" advanced="true">

<adm: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.

</adm:synopsis>

<adm: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.

</adm:description>

<adm:requires-admin-action>

<adm:component-restart />

</adm:requires-admin-action>

<adm:default-behavior>

<adm:defined>

<adm:value>128</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:integer lower-limit="1">

<adm:unit-synopsis>connections</adm:unit-synopsis>

</adm:integer>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-accept-backlog</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="ssl-protocol" multi-valued="true">

<adm:synopsis>

Specifies the names of the SSL protocols that are allowed for

use in SSL communication.

</adm:synopsis>

<adm:requires-admin-action>

<adm:none>

<adm:synopsis>

Changes to this property take effect immediately but only

impact new SSL/TLS-based sessions created after the

change.

</adm:synopsis>

</adm:none>

</adm:requires-admin-action>

<adm:default-behavior>

<adm:alias>

<adm:synopsis>

Uses the default set of SSL protocols provided by the server's

JVM.

</adm:synopsis>

</adm:alias>

</adm:default-behavior>

<adm:syntax>

<adm:string />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-ssl-protocol</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="ssl-cipher-suite" multi-valued="true">

<adm:synopsis>

Specifies the names of the SSL cipher suites that are allowed

for use in SSL communication.

</adm:synopsis>

<adm:requires-admin-action>

<adm:none>

<adm:synopsis>

Changes to this property take effect immediately but will

only impact new SSL/TLS-based sessions created after the

change.

</adm:synopsis>

</adm:none>

</adm:requires-admin-action>

<adm:default-behavior>

<adm:alias>

<adm:synopsis>

Uses the default set of SSL cipher suites provided by the

server's JVM.

</adm:synopsis>

</adm:alias>

</adm:default-behavior>

<adm:syntax>

<adm:string />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-ssl-cipher-suite</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="max-blocked-write-time-limit" advanced="true">

<adm:synopsis>

Specifies the maximum length of time that attempts to write data

to HTTP clients should be allowed to block.

</adm:synopsis>

<adm:description>

If an attempt to write data to a client takes longer than this

length of time, then the client connection is terminated.

</adm:description>

<adm:default-behavior>

<adm:defined>

<adm:value>2 minutes</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:duration base-unit="ms" lower-limit="0" />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-max-blocked-write-time-limit</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="config-file" mandatory="true">

<adm:synopsis>

Specifies the name of the configuration file for the <adm:user-friendly-name />.

</adm:synopsis>

<adm:default-behavior>

<adm:defined>

<adm:value>config/http-config.json</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:string>

<adm:pattern>

<adm:regex>.*</adm:regex>

<adm:usage>FILE</adm:usage>

<adm:synopsis>

A path to an existing file that is readable by the server.

</adm:synopsis>

</adm:pattern>

</adm:string>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-config-file</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="authentication-required" mandatory="true">

<adm:synopsis>

Specifies whether only authenticated requests can be processed by the

<adm:user-friendly-name />.

</adm:synopsis>

<adm:description>

If true, only authenticated requests will be processed by the

<adm:user-friendly-name />. If false, both authenticated requests and

unauthenticated requests will be processed. All requests are subject

to ACI limitations and unauthenticated requests are subject to server

limits like maximum number of entries returned. Note that setting

ds-cfg-reject-unauthenticated-requests to true will override the current

setting.

</adm:description>

<adm:default-behavior>

<adm:defined>

<adm:value>true</adm:value>

</adm:defined>

</adm:default-behavior>

<adm:syntax>

<adm:boolean />

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-authentication-required</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

<adm:property name="max-concurrent-ops-per-connection">

<adm:synopsis>

Specifies the maximum number of internal operations that each

HTTP client connection can execute concurrently.

</adm:synopsis>

<adm:description>

This property allow to limit the impact that each HTTP request can have on

the whole server by limiting the number of internal operations that each

HTTP request can execute concurrently.

A value of 0 means that no limit is enforced.

</adm:description>

<adm:default-behavior>

<adm:alias>

<adm:synopsis>

Let the server decide.

</adm:synopsis>

</adm:alias>

</adm:default-behavior>

<adm:syntax>

<adm:integer lower-limit="0"/>

</adm:syntax>

<adm:profile name="ldap">

<ldap:attribute>

<ldap:name>ds-cfg-max-concurrent-ops-per-connection</ldap:name>

</ldap:attribute>

</adm:profile>

</adm:property>

</adm:managed-object>