Rhino REST API Framework 2.1 :: Rhino REST API Framework Users Guide

On this page...

Secure configuration
Specifying bind addresses

Below are properties for configuring unified REST resource adaptor, including properties for secure configuration.

Name Type Default Description

Name	Type	Default	Description
`ListenAddress`	`String`	`127.0.0.1`	Local IP address that the Unified REST resource adaptor will listen on for requests.
`ListenPort`	`Integer`	`8000`	Local TCP port that the Unified REST resource adaptor will listen on for requests.
`BindAddresses`	`String`		Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the Unified REST resource adaptor will listen on for requests. If BindAddresses is empty, ListenAddress and Listen Port will be employed. For syntax see Specifying bind addresses.
`MaxOutgoingConnections`	`Integer`	`5`	The maximum number of outgoing TCP connections the resource adaptor will open to a single host when sending requests to that host.
`OutgoingRequestTimeout`	`Long`	`10000`	The time (in ms) that the resource adaptor will wait for a response to an outgoing request before failing the request. The application will see a 500 Server Error response and in case of asynchronous request, activity will end.
`OutgoingIdleTimeout`	`Long`	`60000`	The time (in ms) that the resource adaptor will keep an outgoing TCP connection open for, with no activity on the connection.
`MaxDepth`	`Integer`	`1`	Controls how many HTTP requests may be queued up on a single connection without receiving a response from the server. This is known as "HTTP pipelining". A value of 1 is strongly recommended if the server does not support non-persistent connections. When the connection closes (which it always will if they are non-persistent) the other requests in the pipeline will have to be re-sent on another connection. A value of 1 is also recommended for slow or unreliable servers, to avoid head-of-line blocking.
`QueueTimeout`	`Long`	`5000`	The time (in ms) that a request can be held on the queue waiting for an outgoing connection before timing out and firing an event with response code 500 and reason "Timed out waiting for server connection".
`NewConnectionDelay`	`Long`	`100`	When a burst of (send) requests occurs, the resource adaptor queues them, and only creates new connections if they cannot be sent on existing connections. NewConnectionDelay is the time in milliseconds that the resource adaptor will wait for an outgoing connection to become available before creating a new one. If the server does not support persistent connections, it is strongly recommended that this value be set to 0.
`IncomingRequestTimeout`	`Long`	`5000`	The time (in ms) that the resource adaptor will wait for the SLEE to send a response to an incoming request before failing the request. The resource adaptor will automatically send an error response to the client and end the activity.
`IncomingIdleTimeout`	`Long`	`60000`	The time (in ms) that the resource adaptor will keep an incoming TCP connection open for, with no activity on the connection.
`ServerName`	`String`	`Rhino-Unified-REST-Server/2.1`	The default value of the Server header set in outgoing responses. Applications may override this by setting the Server header in the response manually.
`UserAgent`	`String`	`Rhino-Unified-REST-Client/2.1`	The default value of the User-Agent header set in outgoing requests. Applications may override this by setting the User-Agent header in the request manually.
`AddressType`	`String`	`null`	Defines how the resource adaptor generates the javax.slee.Address object for HTTP events. Default is to not use any address. Setting this to the value `uripath` will make the resource adaptor use a URI address with the value of the path in the request URL. For example, http://localhost/test/zzz?query=yyy will create an address with address plan `AddressPlan.URI` and value "/test/zzz". Responses have no address.
`MaxContentLength`	`Integer`	`1048576`	Maximum value in bytes for the Content-Length header of the HTTP messages which have a message body. If this value is exceeded, the application will see a 413 Client Error Response. MaxContentLength value update will apply to new connections.
`WorkerCount`	`Integer`	`0`	The number of workers used by the server and client worker executors. 0 means use Netty default: 2 * `untime.availableProcessors()`
`AutomaticContentCompression`	`Boolean`	`false`	If enabled, the Unified REST resource adaptor will compress outgoing responses automatically, while respecting the `Accept-Encoding` header (see RFC 2616 - section 14.3 for details).
`AutomaticContentDecompression`	`Boolean`	`true`	If enabled, the Unified REST resource adaptor will decompress incoming responses automatically, while respecting the `Content-Encoding` header (see RFC 2616 - section 14.11 for details).
`CreateIncomingSasTrail`	`Boolean`	`true`	If enabled, the Unified REST resource adaptor will create SAS Trails for incoming requests, and report them automatically.
`DefaultNodeCallbackUrl`	`String`	`http://localhost:8000`	The default URL the Unified REST resource adaptor will provide to services, to include as a callback URL that identifies the current cluster node.
`DefaultClusterCallbackUrl`	`String`	`http://localhost:8000`	The default URL the Unified REST resource adaptor will provide to services, to include as a callback URL that identifies the cluster.
`ServiceMeshAddress`	`String`		Local IP address of the service mesh server, if present. If unset no service mesh will be used. If a service mesh is used, the message sent from the RA will be modified to be sent to the ServiceMesh address, with the original destination stored in the 'Host' header. Proxy and Service Mesh are mutually exclusive
`ServiceMeshPort`	`Integer`	`0`	Local TCP port of the service mesh server, if present. If set to 0 no service mesh will be used. If a service mesh is used, the message sent from the RA will be modified to be sent to the ServiceMesh address, with the original destination stored in the 'Host' header. Proxy and Service Mesh are mutually exclusive.
`ProxyAddress`	`String`		Local IP address or FQDN of the proxy server, if present. If unset no proxy will be used. Proxy and Service Mesh are mutually exclusive.
`ProxyPort`	`Integer`	`0`	Local TCP port of the proxy server, if present. If set to 0 no proxy will be used. Proxy and Service Mesh are mutually exclusive.
`RequestPathsToRedact`	`String`	`(empty)`	Comma-separated list of regular expressions that will be matched against request URI paths when reporting incoming requests to SAS. Requests with matching URIs will have their content redacted in traces sent to SAS, to avoid sensitive information leaking via SAS. If empty then no redaction is performed. Partial matches are accepted, e.g. the pattern `^/abc/` matches paths `/abc/123`, `/abc/999?x=y` etc.

ListenAddress

String

127.0.0.1

Local IP address that the Unified REST resource adaptor will listen on for requests.

ListenPort

Integer

8000

Local TCP port that the Unified REST resource adaptor will listen on for requests.

BindAddresses

String

Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the Unified REST resource adaptor will listen on for requests. If BindAddresses is empty, ListenAddress and Listen Port will be employed. For syntax see Specifying bind addresses.

MaxOutgoingConnections

Integer

5

The maximum number of outgoing TCP connections the resource adaptor will open to a single host when sending requests to that host.

OutgoingRequestTimeout

Long

10000

The time (in ms) that the resource adaptor will wait for a response to an outgoing request before failing the request. The application will see a 500 Server Error response and in case of asynchronous request, activity will end.

OutgoingIdleTimeout

Long

60000

The time (in ms) that the resource adaptor will keep an outgoing TCP connection open for, with no activity on the connection.

MaxDepth

Integer

1

Controls how many HTTP requests may be queued up on a single connection without receiving a response from the server. This is known as "HTTP pipelining". A value of 1 is strongly recommended if the server does not support non-persistent connections. When the connection closes (which it always will if they are non-persistent) the other requests in the pipeline will have to be re-sent on another connection. A value of 1 is also recommended for slow or unreliable servers, to avoid head-of-line blocking.

QueueTimeout

Long

5000

The time (in ms) that a request can be held on the queue waiting for an outgoing connection before timing out and firing an event with response code 500 and reason "Timed out waiting for server connection".

NewConnectionDelay

Long

100

When a burst of (send) requests occurs, the resource adaptor queues them, and only creates new connections if they cannot be sent on existing connections. NewConnectionDelay is the time in milliseconds that the resource adaptor will wait for an outgoing connection to become available before creating a new one. If the server does not support persistent connections, it is strongly recommended that this value be set to 0.

IncomingRequestTimeout

Long

5000

The time (in ms) that the resource adaptor will wait for the SLEE to send a response to an incoming request before failing the request. The resource adaptor will automatically send an error response to the client and end the activity.

IncomingIdleTimeout

Long

60000

The time (in ms) that the resource adaptor will keep an incoming TCP connection open for, with no activity on the connection.

ServerName

String

Rhino-Unified-REST-Server/2.1

The default value of the Server header set in outgoing responses. Applications may override this by setting the Server header in the response manually.

UserAgent

String

Rhino-Unified-REST-Client/2.1

The default value of the User-Agent header set in outgoing requests. Applications may override this by setting the User-Agent header in the request manually.

AddressType

String

null

Defines how the resource adaptor generates the javax.slee.Address object for HTTP events. Default is to not use any address. Setting this to the value uripath will make the resource adaptor use a URI address with the value of the path in the request URL. For example, http://localhost/test/zzz?query=yyy will create an address with address plan AddressPlan.URI and value "/test/zzz". Responses have no address.

MaxContentLength

Integer

1048576

Maximum value in bytes for the Content-Length header of the HTTP messages which have a message body. If this value is exceeded, the application will see a 413 Client Error Response. MaxContentLength value update will apply to new connections.

WorkerCount

Integer

0

The number of workers used by the server and client worker executors. 0 means use Netty default: 2 * untime.availableProcessors()

AutomaticContentCompression

Boolean

false

If enabled, the Unified REST resource adaptor will compress outgoing responses automatically, while respecting the Accept-Encoding header (see RFC 2616 - section 14.3 for details).

AutomaticContentDecompression

Boolean

true

If enabled, the Unified REST resource adaptor will decompress incoming responses automatically, while respecting the Content-Encoding header (see RFC 2616 - section 14.11 for details).

CreateIncomingSasTrail

Boolean

true

If enabled, the Unified REST resource adaptor will create SAS Trails for incoming requests, and report them automatically.

DefaultNodeCallbackUrl

String

http://localhost:8000

The default URL the Unified REST resource adaptor will provide to services, to include as a callback URL that identifies the current cluster node.

DefaultClusterCallbackUrl

String

http://localhost:8000

The default URL the Unified REST resource adaptor will provide to services, to include as a callback URL that identifies the cluster.

ServiceMeshAddress

String

Local IP address of the service mesh server, if present. If unset no service mesh will be used. If a service mesh is used, the message sent from the RA will be modified to be sent to the ServiceMesh address, with the original destination stored in the 'Host' header. Proxy and Service Mesh are mutually exclusive

ServiceMeshPort

Integer

0

Local TCP port of the service mesh server, if present. If set to 0 no service mesh will be used. If a service mesh is used, the message sent from the RA will be modified to be sent to the ServiceMesh address, with the original destination stored in the 'Host' header. Proxy and Service Mesh are mutually exclusive.

ProxyAddress

String

Local IP address or FQDN of the proxy server, if present. If unset no proxy will be used. Proxy and Service Mesh are mutually exclusive.

ProxyPort

Integer

0

Local TCP port of the proxy server, if present. If set to 0 no proxy will be used. Proxy and Service Mesh are mutually exclusive.

RequestPathsToRedact

String

(empty)

Comma-separated list of regular expressions that will be matched against request URI paths when reporting incoming requests to SAS. Requests with matching URIs will have their content redacted in traces sent to SAS, to avoid sensitive information leaking via SAS. If empty then no redaction is performed. Partial matches are accepted, e.g. the pattern ^/abc/ matches paths /abc/123, /abc/999?x=y etc.

ThreadPoolSize, MaxChannelMemorySize and MaxTotalMemorySize are not currently used. In future, they will support configuration of the Netty OrderedMemoryAwareThreadPoolExecutor.

Secure configuration

Name Type Default Description

Name	Type	Default	Description
`SecureListenPort`	`Integer`	`0`	Local TCP port that the Unified REST resource adaptor will listen on for HTTPS requests. If set to a value greater than 0, then a KeyStore must be provided that contains the private key for the server.
`SecureBindAddresses`	`String`		Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the Unified REST resource adaptor will listen on for requests. If SecureBindAddresses is empty, ListenAddress and SecureListenPort will be employed. If a SecureBindAddress is specified then a KeyStore must be provided that contains the private key for the server. For syntax see Specifying bind addresses.
`KeyStore`	`String`	`(empty)`	Path to JKS keystore file. System properties (such as `${rhino.dir.home}`) may be used.
`KeyStorePassword`	`String`	`(empty)`	Keystore password for file specified by KeyStore.
`TrustStore`	`String`	`${java.home}/lib/security/cacerts`	Path to JKS keystore for trust certificates. The special value <<TRUST ALL>> may be used to bypass trust checks.
`TrustStorePassword`	`String`	`changeit`	Keystore password for file specified by TrustStore.
`CipherSuites`	`String`	`(empty)`	List of cipher suites to pass to `SSLEngine.setEnabledCipherSuites()`. An empty value means the method won’t be called and all cipher suites are enabled.
`SSLSessionTimeout`	`Integer`	`0`	Value to pass to `SSLContext.setSessionTimeout()` after the context is created. A value of 0 means the method won’t be called.
`NeedClientAuth`	`Boolean`	`false`	When set to true, this will set the same flag on the SSL Engine for incoming HTTPS connections, meaning a valid client certificate is required to connect. The client certificates can be retrieved from the `HttpRequest` event using the `getClientDetails()` method.

SecureListenPort

Integer

0

Local TCP port that the Unified REST resource adaptor will listen on for HTTPS requests. If set to a value greater than 0, then a KeyStore must be provided that contains the private key for the server.

SecureBindAddresses

String

Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the Unified REST resource adaptor will listen on for requests. If SecureBindAddresses is empty, ListenAddress and SecureListenPort will be employed. If a SecureBindAddress is specified then a KeyStore must be provided that contains the private key for the server. For syntax see Specifying bind addresses.

KeyStore

String

(empty)

Path to JKS keystore file. System properties (such as ${rhino.dir.home}) may be used.

KeyStorePassword

String

(empty)

Keystore password for file specified by KeyStore.

TrustStore

String

${java.home}/lib/security/cacerts

Path to JKS keystore for trust certificates. The special value <<TRUST ALL>> may be used to bypass trust checks.

TrustStorePassword

String

changeit

Keystore password for file specified by TrustStore.

CipherSuites

String

(empty)

List of cipher suites to pass to SSLEngine.setEnabledCipherSuites(). An empty value means the method won’t be called and all cipher suites are enabled.

SSLSessionTimeout

Integer

0

Value to pass to SSLContext.setSessionTimeout() after the context is created. A value of 0 means the method won’t be called.

NeedClientAuth

Boolean

false

When set to true, this will set the same flag on the SSL Engine for incoming HTTPS connections, meaning a valid client certificate is required to connect. The client certificates can be retrieved from the HttpRequest event using the getClientDetails() method.

Specifying bind addresses

BindAddresses and SecureBindAddresses are specified as a comma-separated list of {node}host:port elements.

This allows entities running on two nodes on the same host to use different ports, for example:

{101}0.0.0.0:8000,{102}0.0.0.0:8001

It also allows entities running on different hosts to specify an interface to listen on that is specific to each host, for example:

{101}192.168.1.100:8000,{102}192.168.1.101:8000

Previous page Next page

Configuring the REST Resource Adaptor

Secure configuration

Specifying bind addresses