LCDS NIO
AMF and HTTP (AMFX) channels offer long-polling and streaming channel support over HTTP. They are a good alternative to simple polling and approximate real-time push. However, in LiveCycle Data Services 2.5 they relied on servlet-based AMF and HTTP endpoints on the server. The servlet API requires a request-handler thread for each long-polling or streaming connection. A thread is not available to service other requests while it is servicing a long-poll parked on the server, or while it is servicing a streaming HTTP response. Therefore, the servlet implementation does not scale well for a large number of long-polling or streaming connections.
NIO-based AMF and HTTP endpoints address this scalability limitation by providing identical transport functionality from the client perspective, while avoiding the requirement of using one thread for each long-polling or streaming connection. NIO-based endpoints use the Java NIO API to service a large number of client connections in a non-blocking, asynchronous fashion.
Note: Like servlet-based endpoints, NIO-based AMF and HTTP endpoints return a session id to inject into the client channel URL in the first response that is returned from the server. This allows client-server interaction to work when the client has cookies disabled.
Configuring a shared socket server for NIO-based endpoints
You can configure one or more socket servers for use with NIO-based endpoints. The only reason to define more than one socket server is if you want to use both secure and insecure NIO endpoints. An underlying server either supports secure (SSL or TLS) connections or insecure connections, not both.
Do not define more than one socket server unless you need both secure and insecure support in the same application. When you do define more than one socket server, you can specify which server the endpoint of a channel definition uses. You use the server element in the services-config.xml file to create the server definition. The servers element can contain one or more server elements, as the following example shows:
<servers>
<server id="my-nio-server" class="flex.messaging.socketserver.SocketServer">
</server>
<server id="secure-nio-server" class="flex.messaging.socketserver.SocketServer">
<properties>
<keystore-file>d:\keystores\localhoststore</keystore-file>
<keystore-file>{context.root}/WEB-INF/flex/localhost.keystore</keystore-file>
<keystore-password>changeit</keystore-password>
<alias>lh</alias>
</properties>
</server>
</servers>
NIO-based endpoints within a channel definition reference a <server> definition by using the <server ref="..."/> property, as the following example shows:
<channel-definition id="my-nio-amf" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://localhost:2080/mynioamf"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
</channel-definition>
Note: One reason to share a server definition among multiple endpoint definitions is that a single port cannot be bound by more than one server definition. For example, if your application must define both a regular NIOAMFEndpoint as well as a StreamingNIOAMFEndpoint, you want clients to be able to reach either endpoint over the same port so these endpoints must reference a common server. If you do not require a shared server, you can configure socket server properties inside channel definitions.
An NIO-based endpoint can implicitly define and use an internal server definition by omitting the <server ref="..."/> property, and instead including any server configuration properties directly within its <properties> element. For example, if you define only a single NIO-based AMF or HTTP endpoint, omit the <server ref="…"/> element and define any desired properties within the endpoint definition. However, if a <server ref="..."/> property is included in the channel definition, any server-related configuration properties in the endpoint definition are ignored and must instead be defined directly for the server itself.
If you configure more than one NIO-based AMF or HTTP endpoint that is not secure, they should all reference a shared unsecured server definition. If you define more than one secure NIO-based AMF or HTTP endpoint, they should all reference a secured shared <server> definition. This configuration lets all insecure endpoints share the same insecure port, and lets all the secure endpoints share a separate, secure port.
Note: A server definition accepts either standard or secure connections based on whether it is configured to use a keystore. A server definition cannot service both standard and secure connections concurrently.
The endpoint uses the class attribute to register the protocol-specific connection implementation classes with the server. For information on the NIO HTTP implementation classes, see Defining channels and NIO-based endpoints.
Secure server definition
A secure server definition requires a digital certificate, and contains child elements for specifying a keystore filename and password. You can create public and private key pairs and self-signed certificates with the Java keytool utility. The common name (CN) of self-signed certificates must be set to localhost or the IP address on which the RTMPS endpoint is available. For information about key and certificate creation and management, see the Java keytool documentation at http://java.sun.com.
Optionally, you can store a keystore password in a separate file, possibly on removable media. Specify only one keystore-password or keystore-password-file. The following example shows a keystore-password-file element:
<keystore-password-file>a:\password</keystore-password-file>
Compatibility with previous versions of LiveCycle Data Services ES
The NIO-based AMF and HTTP endpoints are functionally equivalent to the existing servlet-based AMF and HTTP endpoints as far as the client is concerned. You should be able to run your existing applications, using the existing configuration files, when migrating your application to LiveCycle Data Services 2.6.
NIO-based endpoints do not support the following configuration options:
max-waiting-poll-requests
NIO-based polling endpoints do not have the threading limitation that the servlet API imposes, so they do not require nor support the max-waiting-poll-requests property.
max-streaming-clients
NIO-based streaming endpoints do not have the threading limitation that the servlet API imposes, so they do not require nor support the max-streaming-clients property.
Defining channels and NIO-based endpoints
When defining NIO-based endpoints, you specify one of the following classes to define the protocol-specific connection implementation There is also a secure version of each of these endpoints that transports data over a secure connection. The names of the secure endpoints all start with the text "Secure"; for example, SecureRTMPEndpoint.
RTMPEndpoint
NIOAMFEndpoint
StreamingNIOAMFEndpoint
NIOHTTPEndpoint
StreamingNIOHTTPEndpoint
The NIO-based AMF and HTTP endpoints implement part of the HttpServletRequest interface to expose headers and cookies in requests to custom LoginCommands or for other uses. You can access the HttpServletRequest instance by using the FlexContext.getHttpRequest() method. These endpoints do not implement the HttpServletResponse interface; therefore, the FlexContext.getHttpResponse() method returns null.
Supported methods from the HttpServletRequest interface include the following:
getCookies()
getDateHeader()
getHeader()
getHeaderNames()
getHeaders()
getIntHeader()
Calling an unsupported method of the HttpServletRequest interface throws an UnsupportedOperationException exception.
Configuring RTMP endpoints
You use RTMP channels to connect to an RTMP endpoint that supports real-time messaging and data. You can also configure these channels for long polling.
RTMPT connections are HTTP connections from the client to the server over which RTMP data is tunneled. When a direct RTMP connection is unavailable, the standard and secure channels automatically attempt to use RTMPT and tunneled RTMPS connections, respectively, on the RTMP endpoint with no additional configuration required.
Note: You cannot use server.port tokens in an RTMP endpoint configuration. You can use the server.name token, but not when using clustering. If you have a firewall in place, you must open the port that you assign to the RTMP endpoint to allow RTMP traffic.
RTMP is a protocol that is primarily used to stream data, audio, and video over the Internet to Flash Player clients. RTMP maintains a persistent connection with an endpoint and allows real-time communication. You can make an RTMP connection in one of the following ways depending upon the network setup of the clients:
Direct socket connection.
Tunneled socket connection through an HTTP proxy server using the CONNECT method.
Active, adaptive polling using the browser HTTP stack. This mechanism does place additional computational load on the RTMP server and so reduces the scalability of the deployment.
RTMP direct socket connection
RTMP in its most direct form uses a simple TCP socket connection from the client machine directly to the RTMP server.
RTMPT Tunnelling with HTTP Proxy Server Connect
This connection acts like a direct connection but uses the proxy server support for the CONNECT protocol if supported. If this connection is not supported, the server falls back to using HTTP requests with polling.
RTMPT Tunnelling with HTTP requests
In this mode, the client uses an adaptive polling mechanism to implement two-way communication between the browser and the server. This mechanism is not configurable and is designed to use at most one connection between the client and server at a time to ensure that Flash Player does not consume all of the connections the browser allows to one server.
Connecting RTMP from the web tier to the application server tier
Currently, all RTMP connections must be made from the browser, or an HTTP proxy server in the case of a CONNECT-based tunnel connection, directly to the RTMP server. Because the NIO server is embedded in the application server tier with access to the database, in some server environments it is not easy to expose it directly to web clients. There are a few ways to address this problem in your configuration:
You can expose a firewall and load balancer to web clients that can implement a TCP pass-through mode to the LiveCycle Data Services ES server.
You can place a proxy server on the web tier that supports the HTTP CONNECT protocol so it can proxy connections from the client to the RTMP server. This provides real-time connection support by passing the web tier. The proxy server configuration can provide control over which servers and ports can use this protocol so it is more secure than opening up the RTMP server directly to clients. For an RTMP CONNECT tunnel to work, the client browser must be configured to use a specific HTTP proxy server.
You can place a reverse proxy server on the web tier which proxies simple HTTP requests to the NIO server. This approach only works in RTMPT polling mode.
Configuring a standard RTMPChannel/RTMPEndpoint
Use a standard RTMPChannel/RTMPEndpoint only when transmitting data that does not require security. The following example shows an RTMP channel definition:
<channel-definition id="my-rtmp"
class="mx.messaging.channels.RTMPChannel">
<endpoint url="rtmp://{server.name}:2035"
class="flex.messaging.endpoints.RTMPEndpoint"/>
<properties>
<idle-timeout-minutes>20</idle-timeout-minutes>
</properties>
</channel-definition>
You can use the optional rtmpt-poll-wait-millis-on-client element when clients are connected over RTMPT while performing adaptive polling. After receiving a server response, clients wait for an absolute time interval before issuing the next poll request rather than using an exponential back-off up to a maximum poll wait time of 4 seconds. Allowed values are integers in the range of 0 to 4000, for example:
<rtmpt-poll-wait-millis-on-client>0</rtmpt-poll-wait-millis-on-client>
You can set the optional block-rtmpt-polling-clients element to true to allow the server to be configured to drop the inefficient polling connection. This action triggers the client to fall back to the next channel in its channel set. The default value is false.
When an RTMPChannel internally falls back to tunneling, it sends its HTTP requests to the same domain/port that is used for regular RTMP connections and these requests must be sent over a standard HTTP port so that they make it through external firewalls that some clients could be behind. For RTMP to work, you must bind your server-side RTMP endpoint for both regular RTMP connections and tunneled connections to port 80. When the client channel falls back to tunneling, it always goes to the domain/port specified in the channel endpoint URI.
If you have a switch or load balancer that supports virtual IPs, you can use a deployment as the following table shows, using a virtual IP (and no additional NIC on the LiveCycle Data Services ES server) where client requests first hit a load balancer that routes them back to a backing LiveCycle Data Services ES server:
Public Internet
Load balancer
LiveCycle Data Services ES
Browser client makes HTTP request
my.domain.com:80
Servlet container bound to port 80
Browser client uses RTMP/T
rtmp.domain.com:80 (virtual IP address)
RTMPEndpoint bound to any port; for example, 2037
The virtual IP/port in this example (rtmp.domain.com:80) is configured to route back to port 2037 or whatever port the RTMPEndpoint is configured to use on the LiveCycle Data Services ES server. In this approach, the RTMPEndpoint does not have to bind to a standard port because the load balancer publicly exposes the endpoint via a separate virtual IP address on a standard port.
If you do not have a switch or load balancer that supports virtual IPs, you need a second NIC to allow the RTMPEndpoint to bind port 80 on the same server as the servlet container that binds to port 80 on the primary NIC, as the following table shows:
Public Internet
LiveCycle Data Services ES NICs
LiveCycle Data Services ES
Browser client makes HTTP request
my.domain.com:80
Servlet container bound to port 80 on primary NIC using primary domain/IP address
Browser client uses RTMP/T
rtmp.domain.com:80
RTMPEndpoint bound to port 80 on a second NIC using a separate domain/IP address
In this approach the physical LiveCycle Data Services ES server has two NICs, each with its own static IP address. The servlet container binds port 80 on the primary NIC and the RTMPEndpoint binds port 80 on the secondary NIC. This allows traffic to and from the server to happen over a standard port (80) regardless of the protocol (HTTP or RTMP). The key take away is that for the RTMPT fallback to work smoothly, the RTMPEndpoint must be exposed to Flex clients over port 80, which is the standard HTTP port that generally allows traffic (unlike nonstandard RTMP ports like 2037, which are usually closed by IT departments).
To bind the RTMPEndpoint to port 80, one of the approaches above is required. For secure RTMPS (direct or tunneled) connections, the information above is the same but you would use port 443. If an application requires both secure and non-secure RTMP connections with tunneling fallback, you do not need three NICs; you need only two. The first NIC services regular HTTP/HTTPS traffic on the primary IP address at ports 80 and 443, and the second NIC services RTMP and RTMPS connections on the secondary IP at ports 80 and 443. If a load balancer is in use, it is the same as the first option above where LiveCycle Data Services ES has a single NIC and the different IP/port combinations are defined at the load balancer.
Configuring NIO-based AMF and HTTP endpoints
The NIO-based AMF and HTTP endpoint classes support simple polling, long-polling, and streaming requests. Like the socket server configuration options, these endpoints support the existing configuration options defined for the RTMPEndpoint, AMFEndpoint and HTTPEndpoint classes, and the following additional configuration options:
:Option
Description
session-cookie-name (Optional) Default value is AMFSessionId. The name used for the session cookie set by the endpoint.
If you define multiple NIO-based endpoints and specify a custom cookie name, it must be the same for all NIO-based AMF and HTTP endpoints.
session-timeout-minutes (Optional) Default value is 15 minutes. The session timeout for inactive NIO HTTP sessions, in minutes. Long-poll requests or streaming connections that uses server-to-client-heartbeat-millis keep the session alive, as will any request from the client.
If you define multiple NIO-based endpoint and specify a custom session timeout, it must be the same for all NIO-based AMF and HTTP endpoints.
max-request-line-size (Optional) Default value is 1024 characters. Requests that contain request or header lines that exceed this value are dropped and the connection is closed.
max-request-body-size (Optional) Default is 5 MB. The maximum POST body size, in bytes, that the endpoint accepts. Requests that exceed this limit are dropped and the connection is closed.
Channels that use NIO-based endpoints
The following channel definition defines an RTMP channel for use with RTMP endpoints.
<!-- NIO RTMP -->
<channel-definition id="my-rtmp" class="mx.messaging.channels.RTMPChannel">
<endpoint url="rtmp://servername:2038"
class="flex.messaging.endpoints.RTMPEndpoint"/>
<properties>
<idle-timeout-minutes>0</idle-timeout-minutes>
<bind-address>10.132.64.63</bind-address>
<bind-port>2035</bind-port>
</properties>
</channel-definition>
The following channel definitions define AMF channels for use with NIO-based AMF endpoints.
<!-- NIO AMF -->
<channel-definition id="my-nio-amf" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://servername:2080/nioamf"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
<!-- NIO AMF with polling -->
<channel-definition id="my-nio-amf-poll" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://servername:2080/nioamfpoll"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-millis>3000</polling-interval-millis>
</properties>
</channel-definition>
<!-- NIO AMF with long polling -->
<channel-definition id="my-nio-amf-longpoll" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://servername:2080/nioamflongpoll"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-millis>0</polling-interval-millis>
<wait-interval-millis>-1</wait-interval-millis>
</properties>
</channel-definition>
<!-- NIO AMF with streaming -->
<channel-definition id="my-nio-amf-stream"
class="mx.messaging.channels.StreamingAMFChannel">
<endpoint url="http://servername:2080/nioamfstream"
class="flex.messaging.endpoints.StreamingNIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<server-to-client-heartbeat-millis>10000</server-to-client-heartbeat-millis>
<user-agent-settings>
<user-agent match-on="MSIE"
kickstart-bytes="2048" max-streaming-connections-per-session="1"/>
<user-agent match-on="Firefox"
kickstart-bytes="0" max-streaming-connections-per-session="1"/>
</user-agent-settings>
</properties>
</channel-definition>
<!-- Secure NIO AMF -->
<channel-definition id="secure-nio-amf" class="mx.messaging.channels.SecureAMFChannel">
<endpoint url="https://servername:2443/securenioamf"
class="flex.messaging.endpoints.SecureNIOAMFEndpoint"/>
<server ref="secure-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
The following channel definitions define HTTP channels for use with NIO-based HTTP endpoints:
<!-- NIO HTTP -->
<channel-definition id="my-nio-http" class="mx.messaging.channels.HTTPChannel">
<endpoint url="http://servername:2080/niohttp"
class="flex.messaging.endpoints.NIOHTTPEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
<!-- NIO HTTP with streaming -->
<channel-definition id="my-nio-http-stream"
class="mx.messaging.channels.StreamingHTTPChannel">
<endpoint url="http://servername:2080/niohttpstream"
class="flex.messaging.endpoints.StreamingNIOHTTPEndpoint"/>
<server ref="my-nio-server"/>
</channel-definition>
<!-- Secure NIO HTTP -->
<channel-definition id="secure-nio-http" class="mx.messaging.channels.SecureHTTPChannel">
<endpoint url="https://servername:2443/secureniohttp"
class="flex.messaging.endpoints.SecureNIOHTTPEndpoint"/>
<server ref="secure-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
Configuring the socket server
You configure one or more socket server definitions in the services-config.xml file. Once defined, you can specify which server a channel definition uses.
Note: You can optionally set any of the socket server properties directly in a channel definition for situations where you are not sharing the same socket server for more than one endpoint.
Use a secure channel definition to connect to the endpoint over Transport Layer Security (TLS) for RTMP-based endpoints or SSL for servlet-based endpoints. When using RTMP, the channel falls back to tunneled RTMPS when a direct connection is unavailable.
The following table describes the configuration options for the socket server.:
Option
Description
Security Related Options
max-connection-count (Optional) The total number of open connections that the server accepts. Clients that attempt to connect beyond this limit are rejected. Setting max-connection-count to 0, the default, disables this limitation.
Note that this is a potential security concern.
connection-idle-timeout-minutes (Optional) The number of minutes that a streaming channel is allowed to remain idle before it is closed. Setting idle-timeout-minutes to 0, the default value, disables the timeout.
Note that this is a potential security concern.
idle-timeout-minutes Supported but deprecated. See connection-idle-timeout-minutes above.
whitelist (Optional) Contains client IP addresses that are permitted to connect to the server. When defined, client IPs must satisfy this filter to connect. The blacklist option takes precedence over the whitelist option if the client IP is a member of both sets.
Define a whitelist by creating a list of ip-address and ip-address-pattern elements. The ip-address element supports simple IP matching, allowing you to use a wildcard symbol, *, for individual bytes in the address. The ip-address-pattern element supports regular-expression pattern matching of IP addresses to support range-based IP filtering, as the following example shows:
<whitelist> <ip-address>10.132.64.63</ip-address> <ip-address-pattern>240.*</ip-address-pattern> </whitelist>
blacklist (Optional) Contains client IPs that are restricted from accessing the server. The blacklist option takes precedence over the whitelist option if the client IP is a member of both sets.
Blacklists take a list of ip-address and ip-address-pattern elements, as the following example shows:
<blacklist> <ip-address>10.132.64.63</ip-address> <ip-address-pattern>240.63.*</ip-address-pattern> </blacklist>
For more information on the ip-address and ip-address-pattern elements, see the whitelist option.
cross-domain-path Path to a cross domain policy file. For more information, see Using cross domain policy files with the NIO server.
enabled-cipher-suites A cipher suite is a set of encryption algorithms. Secure NIO socket server definitions or secure NIO (RTMP, AMF, or HTTP) endpoint definitions can define a restricted set of cipher suites to use with secure connections, as the following examples shows:
<enabled-cipher-suites> <cipher-suite>SSL_RSA_WITH_128_MD5</cipher-suite> <cipher-suite>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</cipher-suite> </enabled-cipher-suites>
If left undefined, the default set of cipher suites for the security provider implementation of the Java virtual machine (JVM) are used for secure connection handshaking. If an unsupported cipher suite is defined, an error occurs and a ConfigurationException exception is thrown when the server starts.
General Server Options
bind-address (Optional) Binds the server to a specific network interface. If left unspecified, the server binds to all local network interfaces on startup.
bind-port (Optional) Binds the server to a port that differs from the public port that clients connect to. This allows clients to connect to a public port on a firewall or load balancer that forwards traffic to this internal port.
Connection Configuration Options
connection-buffer-type (Optional) Controls the type of byte buffers that connections use to read and write from the network. Supported values include:
heap (default) specifies to use heap-allocated ByteBuffers.
direct specifies to use DirectByteBuffers.
Performance varies depending upon JRE and operating system.
connection-read-buffer-size (Optional) Default value is 8192 (8 KBytes). Size, in bytes, for the read buffer for connections.
connection-write-buffer-size (Optional) Default value is 8192 (8 KBytes). Size, in bytes, for the write buffer for connections.
Control the threading behavior of the server in the absence of a WorkManager.
websphere-workmanager-jndi-name (Optional) For IBM WebSphere deployment, the WorkManager configured and referenced as the worker thread pool for the server. A WorkManager must be referenced to support JTA, which the Data Management Service uses.
max-worker-threads (Optional) The upper bound on the number of worker threads that the server uses to service connections. Defaults to unbounded with idle threads being reaped based upon the idle-worker-thread-timeout-millis value. Ignored if the server is using a WorkManager.
min-worker-threads (Optional) A nonzero, lower bound on the number of worker threads that the server uses to service connections. Defaults to 0. If nonzero, on server start up this number of worker threads is prestarted. Ignored if the server is using a WorkManager.
idle-worker-thread-timeout-millis (Optional) Time, in minutes, that a worker thread must be idle before it is released. Defaults to 1. Ignored if the server is using a WorkManager.
worker-thread-priority (Optional) Desired priority for the server threads. Defaults to Thread.NORM_PRIORITY. Ignored if the server is using a WorkManager.
Acceptor and Reactor Configuration Options
accept-backlog (Optional) The suggested size of the accept queue for the server socket to buffer new connect requests when the server is too busy to handshake immediately. Default is the platform default value for a server socket.
accept-thread-priority (Optional) Allows the priority for accepting new connections to be adjusted either above or below the general server priority for servicing existing connections. Default is the thread priority of the worker thread pool or the WorkManager (whichever is used).
reactor-count (Optional) Splits IO read/write readiness selection for all existing connections to the server out across all available processors and divides the total readiness selection set by the number of reactors to avoid having a single Selector manage the state for all connections. Default is the number of available physical processors on the machine.
TLS/SSL Configuration Options
keystore-type (Optional) Default value is JKS. Specifies the keystore type. The supported values include: JKS and PKCS12.
keystore-file Points to the actual keystore file on the running server. The path to the file may be specified as an absolute path, as in:
<keystore-file>C:\keystore.jks</keystore-file>
Or as a relative to the WEB-APP directory using the {context.root} token, as in:
<keystore-file>{context.root}/WEB- INF/certs/keystore.jks</keystore-file>
keystore-password The keystore password.
keystore-password-file Path to a text file on external or removable media that contains the password value. Ignored if keystore-password is specified.
keystore-password-obfuscated (Optional) Default value is false. Set to true if an obfuscated value is stored in the configuration file and a password deobfuscator has been registered for use.
password-deobfuscator (Optional) The class name of a password deobfuscator used to handle obfuscated passwords safely at run time.
A password deobfuscator implements the flex.messaging.util.PasswordDeobfuscator interface, which contains a deobfuscate() and a destroy() method. The flex.messaging.util.AbstactPasswordDeobfuscator class is an abstract class that implements the destroy() method. Your deobfuscator class can extend this class, and just implement a deobfuscate() method. The deobfuscate() method takes a string that contains the obfuscated password and returns a char[] containing the deobfuscated password.
For more information, see the JavaDoc for the flex.messaging.util.PasswordDeobfuscator interface and the flex.messaging.util.AbstractPasswordDeobfuscator abstract base class.
algorithm (Optional) Only configure this option when using a third-party security provider implementation. Defaults to the current default JVM algorithm. The default JVM algorithm can be controlled by setting the ssl.KeyManagerFactory.algorithm security property.
Example usage:
<algorithm>Default</algorithm> - Explicitly uses the default JVM algorithm.
<algorithm>SunX509</algorithm> - Uses Sun algorithm; requires the Sun secuity provider.
<algorithm>IbmX509</algorithm> - Uses IBM algorithm; requires the IBM security provider.
alias (Optional) If a keystore is used that contains more than one server certificate, use this property to define which certificate to use to authenticate the server end of SSL/TLS connections.
protocol (Optional) Default value is TLS. The preferred protocol for secure connections.
Socket Configuration Options (for accepted sockets)
socket-keep-alive-enabled (Optional) Enables/Disables SO_KEEPALIVE for sockets the server uses.
socket-oobinline-enabled (Optional) Enables/Disables OOBLINE (receipt of TCP urgent data). Defaults to false, which is the JVM default.
socket-receive-buffer-size (Optional) Sets the SO_RCVBUF option for sockets to this value, which is a hint for the size of the underlying network I/O buffer to use.
socket-send-buffer-size (Optional) Sets the SO_SNDBUF option for sockets to this value, which is a hint for the size of the underlying network I/O buffer to use.
socket-linger-seconds (Optional) Enables/Disables SO_LINGER for sockets the server uses where the value indicates the linger time for a closing socket in seconds. A value of -1 disables socket linger.
socket-tcp-no-delay-enabled (Optional) Enables/Disables TCP_NODELAY, which enables or disables the use of the Nagle algorithm by the sockets.
socket-traffic-class (Optional) Defines the traffic class for the socket.
Using cross domain policy files with the NIO server
By default, the Flash Player security sandbox only allows a SWF file to make requests back to the same domain that the SWF file originated from. You use a cross domain policy file to deal with this security restriction. If a SWF file makes a request to a domain that is different than the one from which it originated, Flash Player makes a request to the new domain for a cross domain policy file that can provide the SWF file with additional permissions to communicate with the domain.
For servlet-based endpoints, LiveCycle Data Services ES depends on the application server for cross domain policy file handling. For NIO-based AMF and HTTP endpoints, LiveCycle Data Services ES must depend on the NIO server for cross domain policy file handling and not the application server itself. This is because the NIO server listens for requests on a different port than the application server.
If your application makes a request to an AMF or HTTP endpoint at the http://domainA:8400/lcds/messagebroker/amfpolling and domainA is not the same domain the SWF file was downloaded from, Flash Player makes a cross domain policy file request to http://domainA:8400. To allow the application to make the request to the AMF endpoint, you must place a cross domain policy file in the root directory of your application server. For example, with a typical installation of Tomcat, this would be the TOMCAT_HOME\webapps\ROOT directory.
If your application makes a request to an NIO-based AMF or HTTP endpoint at the http://domainA:1234/nioamfpolling and domainA is not the same domain the SWF file was downloaded from, Flash Player makes a cross domain policy file request to http://domainA:1234. Since this request goes directly to the NIO server and not to the application server, you must configure the NIO server to serve the cross domain policy file. To do this, you add a cross-domain-path property to your NIO server settings in your services-config.xml file as the following example shows:
<server id="my-nio-server" class="flex.messaging.socketserver.SocketServer">
<properties>
<http>
<cross-domain-path>crossdomain.xml</cross-domain-path>
</http>
</properties>
</server>
Because this setting only applies to NIO-based AMF and HTTP endpoints it goes in the http section of configuration settings. The NIO server expects cross domain policy files to be under the WEB-INF/flex directory of the LiveCycle Data Services ES web application. In the previous example, you would place a file called crossdomain.xml with your cross domain policy settings in the WEB-INF/flex directory of your LiveCycle Data Services ES web application.
You can also place cross domain files in subdirectories under WEB-INF/flex. This lets you have cross domain policy files for individual NIO-based endpoints. For example, if you want a cross domain policy file that only applies to your NIO-based AMF endpoint at http://domainA:1234/nioamfpolling, you would configure your application as follows:
Use a cross-domain-path of /nioamfpolling, which causes the NIO server to search for a cross domain policy file under /WEB-INF/flex/nioamfpolling.
The cross domain path must match the cross domain policy request. This means that to use the cross domain policy file under /WEB-INF/flex/nioamfpolling, the request must be made to http://domainA:1234/nioamfpolling/crossdomain.xml.
By default, the cross domain policy request is made to the root of the application; for example, http://domainA:1234/crossdomain.xml. To override this behavior in your application, you must use the Security.loadPolicyFile() method; in your application, before you make the request to the endpoint, you would add the following line of code.
Security.loadPolicyFile("http://domainA:1234/nioamfpolling/crossdomain.xml");
This causes Flash Player to attempt to load a cross domain policy file with the supplied URL. In this case, the NIO server returns a cross domain policy file from the WEB-INF/flex/nioamfpolling directory and the permissions in the policy file are applied to requests to the http://domainA:1234/nioamfpolling endpoint only.
NIO-based AMF and HTTP endpoints address this scalability limitation by providing identical transport functionality from the client perspective, while avoiding the requirement of using one thread for each long-polling or streaming connection. NIO-based endpoints use the Java NIO API to service a large number of client connections in a non-blocking, asynchronous fashion.
Note: Like servlet-based endpoints, NIO-based AMF and HTTP endpoints return a session id to inject into the client channel URL in the first response that is returned from the server. This allows client-server interaction to work when the client has cookies disabled.
Configuring a shared socket server for NIO-based endpoints
You can configure one or more socket servers for use with NIO-based endpoints. The only reason to define more than one socket server is if you want to use both secure and insecure NIO endpoints. An underlying server either supports secure (SSL or TLS) connections or insecure connections, not both.
Do not define more than one socket server unless you need both secure and insecure support in the same application. When you do define more than one socket server, you can specify which server the endpoint of a channel definition uses. You use the server element in the services-config.xml file to create the server definition. The servers element can contain one or more server elements, as the following example shows:
<servers>
<server id="my-nio-server" class="flex.messaging.socketserver.SocketServer">
</server>
<server id="secure-nio-server" class="flex.messaging.socketserver.SocketServer">
<properties>
<keystore-file>d:\keystores\localhoststore</keystore-file>
<keystore-file>{context.root}/WEB-INF/flex/localhost.keystore</keystore-file>
<keystore-password>changeit</keystore-password>
<alias>lh</alias>
</properties>
</server>
</servers>
NIO-based endpoints within a channel definition reference a <server> definition by using the <server ref="..."/> property, as the following example shows:
<channel-definition id="my-nio-amf" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://localhost:2080/mynioamf"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
</channel-definition>
Note: One reason to share a server definition among multiple endpoint definitions is that a single port cannot be bound by more than one server definition. For example, if your application must define both a regular NIOAMFEndpoint as well as a StreamingNIOAMFEndpoint, you want clients to be able to reach either endpoint over the same port so these endpoints must reference a common server. If you do not require a shared server, you can configure socket server properties inside channel definitions.
An NIO-based endpoint can implicitly define and use an internal server definition by omitting the <server ref="..."/> property, and instead including any server configuration properties directly within its <properties> element. For example, if you define only a single NIO-based AMF or HTTP endpoint, omit the <server ref="…"/> element and define any desired properties within the endpoint definition. However, if a <server ref="..."/> property is included in the channel definition, any server-related configuration properties in the endpoint definition are ignored and must instead be defined directly for the server itself.
If you configure more than one NIO-based AMF or HTTP endpoint that is not secure, they should all reference a shared unsecured server definition. If you define more than one secure NIO-based AMF or HTTP endpoint, they should all reference a secured shared <server> definition. This configuration lets all insecure endpoints share the same insecure port, and lets all the secure endpoints share a separate, secure port.
Note: A server definition accepts either standard or secure connections based on whether it is configured to use a keystore. A server definition cannot service both standard and secure connections concurrently.
The endpoint uses the class attribute to register the protocol-specific connection implementation classes with the server. For information on the NIO HTTP implementation classes, see Defining channels and NIO-based endpoints.
Secure server definition
A secure server definition requires a digital certificate, and contains child elements for specifying a keystore filename and password. You can create public and private key pairs and self-signed certificates with the Java keytool utility. The common name (CN) of self-signed certificates must be set to localhost or the IP address on which the RTMPS endpoint is available. For information about key and certificate creation and management, see the Java keytool documentation at http://java.sun.com.
Optionally, you can store a keystore password in a separate file, possibly on removable media. Specify only one keystore-password or keystore-password-file. The following example shows a keystore-password-file element:
<keystore-password-file>a:\password</keystore-password-file>
Compatibility with previous versions of LiveCycle Data Services ES
The NIO-based AMF and HTTP endpoints are functionally equivalent to the existing servlet-based AMF and HTTP endpoints as far as the client is concerned. You should be able to run your existing applications, using the existing configuration files, when migrating your application to LiveCycle Data Services 2.6.
NIO-based endpoints do not support the following configuration options:
max-waiting-poll-requests
NIO-based polling endpoints do not have the threading limitation that the servlet API imposes, so they do not require nor support the max-waiting-poll-requests property.
max-streaming-clients
NIO-based streaming endpoints do not have the threading limitation that the servlet API imposes, so they do not require nor support the max-streaming-clients property.
Defining channels and NIO-based endpoints
When defining NIO-based endpoints, you specify one of the following classes to define the protocol-specific connection implementation There is also a secure version of each of these endpoints that transports data over a secure connection. The names of the secure endpoints all start with the text "Secure"; for example, SecureRTMPEndpoint.
RTMPEndpoint
NIOAMFEndpoint
StreamingNIOAMFEndpoint
NIOHTTPEndpoint
StreamingNIOHTTPEndpoint
The NIO-based AMF and HTTP endpoints implement part of the HttpServletRequest interface to expose headers and cookies in requests to custom LoginCommands or for other uses. You can access the HttpServletRequest instance by using the FlexContext.getHttpRequest() method. These endpoints do not implement the HttpServletResponse interface; therefore, the FlexContext.getHttpResponse() method returns null.
Supported methods from the HttpServletRequest interface include the following:
getCookies()
getDateHeader()
getHeader()
getHeaderNames()
getHeaders()
getIntHeader()
Calling an unsupported method of the HttpServletRequest interface throws an UnsupportedOperationException exception.
Configuring RTMP endpoints
You use RTMP channels to connect to an RTMP endpoint that supports real-time messaging and data. You can also configure these channels for long polling.
RTMPT connections are HTTP connections from the client to the server over which RTMP data is tunneled. When a direct RTMP connection is unavailable, the standard and secure channels automatically attempt to use RTMPT and tunneled RTMPS connections, respectively, on the RTMP endpoint with no additional configuration required.
Note: You cannot use server.port tokens in an RTMP endpoint configuration. You can use the server.name token, but not when using clustering. If you have a firewall in place, you must open the port that you assign to the RTMP endpoint to allow RTMP traffic.
RTMP is a protocol that is primarily used to stream data, audio, and video over the Internet to Flash Player clients. RTMP maintains a persistent connection with an endpoint and allows real-time communication. You can make an RTMP connection in one of the following ways depending upon the network setup of the clients:
Direct socket connection.
Tunneled socket connection through an HTTP proxy server using the CONNECT method.
Active, adaptive polling using the browser HTTP stack. This mechanism does place additional computational load on the RTMP server and so reduces the scalability of the deployment.
RTMP direct socket connection
RTMP in its most direct form uses a simple TCP socket connection from the client machine directly to the RTMP server.
RTMPT Tunnelling with HTTP Proxy Server Connect
This connection acts like a direct connection but uses the proxy server support for the CONNECT protocol if supported. If this connection is not supported, the server falls back to using HTTP requests with polling.
RTMPT Tunnelling with HTTP requests
In this mode, the client uses an adaptive polling mechanism to implement two-way communication between the browser and the server. This mechanism is not configurable and is designed to use at most one connection between the client and server at a time to ensure that Flash Player does not consume all of the connections the browser allows to one server.
Connecting RTMP from the web tier to the application server tier
Currently, all RTMP connections must be made from the browser, or an HTTP proxy server in the case of a CONNECT-based tunnel connection, directly to the RTMP server. Because the NIO server is embedded in the application server tier with access to the database, in some server environments it is not easy to expose it directly to web clients. There are a few ways to address this problem in your configuration:
You can expose a firewall and load balancer to web clients that can implement a TCP pass-through mode to the LiveCycle Data Services ES server.
You can place a proxy server on the web tier that supports the HTTP CONNECT protocol so it can proxy connections from the client to the RTMP server. This provides real-time connection support by passing the web tier. The proxy server configuration can provide control over which servers and ports can use this protocol so it is more secure than opening up the RTMP server directly to clients. For an RTMP CONNECT tunnel to work, the client browser must be configured to use a specific HTTP proxy server.
You can place a reverse proxy server on the web tier which proxies simple HTTP requests to the NIO server. This approach only works in RTMPT polling mode.
Configuring a standard RTMPChannel/RTMPEndpoint
Use a standard RTMPChannel/RTMPEndpoint only when transmitting data that does not require security. The following example shows an RTMP channel definition:
<channel-definition id="my-rtmp"
class="mx.messaging.channels.RTMPChannel">
<endpoint url="rtmp://{server.name}:2035"
class="flex.messaging.endpoints.RTMPEndpoint"/>
<properties>
<idle-timeout-minutes>20</idle-timeout-minutes>
</properties>
</channel-definition>
You can use the optional rtmpt-poll-wait-millis-on-client element when clients are connected over RTMPT while performing adaptive polling. After receiving a server response, clients wait for an absolute time interval before issuing the next poll request rather than using an exponential back-off up to a maximum poll wait time of 4 seconds. Allowed values are integers in the range of 0 to 4000, for example:
<rtmpt-poll-wait-millis-on-client>0</rtmpt-poll-wait-millis-on-client>
You can set the optional block-rtmpt-polling-clients element to true to allow the server to be configured to drop the inefficient polling connection. This action triggers the client to fall back to the next channel in its channel set. The default value is false.
When an RTMPChannel internally falls back to tunneling, it sends its HTTP requests to the same domain/port that is used for regular RTMP connections and these requests must be sent over a standard HTTP port so that they make it through external firewalls that some clients could be behind. For RTMP to work, you must bind your server-side RTMP endpoint for both regular RTMP connections and tunneled connections to port 80. When the client channel falls back to tunneling, it always goes to the domain/port specified in the channel endpoint URI.
If you have a switch or load balancer that supports virtual IPs, you can use a deployment as the following table shows, using a virtual IP (and no additional NIC on the LiveCycle Data Services ES server) where client requests first hit a load balancer that routes them back to a backing LiveCycle Data Services ES server:
Public Internet
Load balancer
LiveCycle Data Services ES
Browser client makes HTTP request
my.domain.com:80
Servlet container bound to port 80
Browser client uses RTMP/T
rtmp.domain.com:80 (virtual IP address)
RTMPEndpoint bound to any port; for example, 2037
The virtual IP/port in this example (rtmp.domain.com:80) is configured to route back to port 2037 or whatever port the RTMPEndpoint is configured to use on the LiveCycle Data Services ES server. In this approach, the RTMPEndpoint does not have to bind to a standard port because the load balancer publicly exposes the endpoint via a separate virtual IP address on a standard port.
If you do not have a switch or load balancer that supports virtual IPs, you need a second NIC to allow the RTMPEndpoint to bind port 80 on the same server as the servlet container that binds to port 80 on the primary NIC, as the following table shows:
Public Internet
LiveCycle Data Services ES NICs
LiveCycle Data Services ES
Browser client makes HTTP request
my.domain.com:80
Servlet container bound to port 80 on primary NIC using primary domain/IP address
Browser client uses RTMP/T
rtmp.domain.com:80
RTMPEndpoint bound to port 80 on a second NIC using a separate domain/IP address
In this approach the physical LiveCycle Data Services ES server has two NICs, each with its own static IP address. The servlet container binds port 80 on the primary NIC and the RTMPEndpoint binds port 80 on the secondary NIC. This allows traffic to and from the server to happen over a standard port (80) regardless of the protocol (HTTP or RTMP). The key take away is that for the RTMPT fallback to work smoothly, the RTMPEndpoint must be exposed to Flex clients over port 80, which is the standard HTTP port that generally allows traffic (unlike nonstandard RTMP ports like 2037, which are usually closed by IT departments).
To bind the RTMPEndpoint to port 80, one of the approaches above is required. For secure RTMPS (direct or tunneled) connections, the information above is the same but you would use port 443. If an application requires both secure and non-secure RTMP connections with tunneling fallback, you do not need three NICs; you need only two. The first NIC services regular HTTP/HTTPS traffic on the primary IP address at ports 80 and 443, and the second NIC services RTMP and RTMPS connections on the secondary IP at ports 80 and 443. If a load balancer is in use, it is the same as the first option above where LiveCycle Data Services ES has a single NIC and the different IP/port combinations are defined at the load balancer.
Configuring NIO-based AMF and HTTP endpoints
The NIO-based AMF and HTTP endpoint classes support simple polling, long-polling, and streaming requests. Like the socket server configuration options, these endpoints support the existing configuration options defined for the RTMPEndpoint, AMFEndpoint and HTTPEndpoint classes, and the following additional configuration options:
:Option
Description
session-cookie-name (Optional) Default value is AMFSessionId. The name used for the session cookie set by the endpoint.
If you define multiple NIO-based endpoints and specify a custom cookie name, it must be the same for all NIO-based AMF and HTTP endpoints.
session-timeout-minutes (Optional) Default value is 15 minutes. The session timeout for inactive NIO HTTP sessions, in minutes. Long-poll requests or streaming connections that uses server-to-client-heartbeat-millis keep the session alive, as will any request from the client.
If you define multiple NIO-based endpoint and specify a custom session timeout, it must be the same for all NIO-based AMF and HTTP endpoints.
max-request-line-size (Optional) Default value is 1024 characters. Requests that contain request or header lines that exceed this value are dropped and the connection is closed.
max-request-body-size (Optional) Default is 5 MB. The maximum POST body size, in bytes, that the endpoint accepts. Requests that exceed this limit are dropped and the connection is closed.
Channels that use NIO-based endpoints
The following channel definition defines an RTMP channel for use with RTMP endpoints.
<!-- NIO RTMP -->
<channel-definition id="my-rtmp" class="mx.messaging.channels.RTMPChannel">
<endpoint url="rtmp://servername:2038"
class="flex.messaging.endpoints.RTMPEndpoint"/>
<properties>
<idle-timeout-minutes>0</idle-timeout-minutes>
<bind-address>10.132.64.63</bind-address>
<bind-port>2035</bind-port>
</properties>
</channel-definition>
The following channel definitions define AMF channels for use with NIO-based AMF endpoints.
<!-- NIO AMF -->
<channel-definition id="my-nio-amf" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://servername:2080/nioamf"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
<!-- NIO AMF with polling -->
<channel-definition id="my-nio-amf-poll" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://servername:2080/nioamfpoll"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-millis>3000</polling-interval-millis>
</properties>
</channel-definition>
<!-- NIO AMF with long polling -->
<channel-definition id="my-nio-amf-longpoll" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://servername:2080/nioamflongpoll"
class="flex.messaging.endpoints.NIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-millis>0</polling-interval-millis>
<wait-interval-millis>-1</wait-interval-millis>
</properties>
</channel-definition>
<!-- NIO AMF with streaming -->
<channel-definition id="my-nio-amf-stream"
class="mx.messaging.channels.StreamingAMFChannel">
<endpoint url="http://servername:2080/nioamfstream"
class="flex.messaging.endpoints.StreamingNIOAMFEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<server-to-client-heartbeat-millis>10000</server-to-client-heartbeat-millis>
<user-agent-settings>
<user-agent match-on="MSIE"
kickstart-bytes="2048" max-streaming-connections-per-session="1"/>
<user-agent match-on="Firefox"
kickstart-bytes="0" max-streaming-connections-per-session="1"/>
</user-agent-settings>
</properties>
</channel-definition>
<!-- Secure NIO AMF -->
<channel-definition id="secure-nio-amf" class="mx.messaging.channels.SecureAMFChannel">
<endpoint url="https://servername:2443/securenioamf"
class="flex.messaging.endpoints.SecureNIOAMFEndpoint"/>
<server ref="secure-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
The following channel definitions define HTTP channels for use with NIO-based HTTP endpoints:
<!-- NIO HTTP -->
<channel-definition id="my-nio-http" class="mx.messaging.channels.HTTPChannel">
<endpoint url="http://servername:2080/niohttp"
class="flex.messaging.endpoints.NIOHTTPEndpoint"/>
<server ref="my-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
<!-- NIO HTTP with streaming -->
<channel-definition id="my-nio-http-stream"
class="mx.messaging.channels.StreamingHTTPChannel">
<endpoint url="http://servername:2080/niohttpstream"
class="flex.messaging.endpoints.StreamingNIOHTTPEndpoint"/>
<server ref="my-nio-server"/>
</channel-definition>
<!-- Secure NIO HTTP -->
<channel-definition id="secure-nio-http" class="mx.messaging.channels.SecureHTTPChannel">
<endpoint url="https://servername:2443/secureniohttp"
class="flex.messaging.endpoints.SecureNIOHTTPEndpoint"/>
<server ref="secure-nio-server"/>
<properties>
<polling-enabled>false</polling-enabled>
</properties>
</channel-definition>
Configuring the socket server
You configure one or more socket server definitions in the services-config.xml file. Once defined, you can specify which server a channel definition uses.
Note: You can optionally set any of the socket server properties directly in a channel definition for situations where you are not sharing the same socket server for more than one endpoint.
Use a secure channel definition to connect to the endpoint over Transport Layer Security (TLS) for RTMP-based endpoints or SSL for servlet-based endpoints. When using RTMP, the channel falls back to tunneled RTMPS when a direct connection is unavailable.
The following table describes the configuration options for the socket server.:
Option
Description
Security Related Options
max-connection-count (Optional) The total number of open connections that the server accepts. Clients that attempt to connect beyond this limit are rejected. Setting max-connection-count to 0, the default, disables this limitation.
Note that this is a potential security concern.
connection-idle-timeout-minutes (Optional) The number of minutes that a streaming channel is allowed to remain idle before it is closed. Setting idle-timeout-minutes to 0, the default value, disables the timeout.
Note that this is a potential security concern.
idle-timeout-minutes Supported but deprecated. See connection-idle-timeout-minutes above.
whitelist (Optional) Contains client IP addresses that are permitted to connect to the server. When defined, client IPs must satisfy this filter to connect. The blacklist option takes precedence over the whitelist option if the client IP is a member of both sets.
Define a whitelist by creating a list of ip-address and ip-address-pattern elements. The ip-address element supports simple IP matching, allowing you to use a wildcard symbol, *, for individual bytes in the address. The ip-address-pattern element supports regular-expression pattern matching of IP addresses to support range-based IP filtering, as the following example shows:
<whitelist> <ip-address>10.132.64.63</ip-address> <ip-address-pattern>240.*</ip-address-pattern> </whitelist>
blacklist (Optional) Contains client IPs that are restricted from accessing the server. The blacklist option takes precedence over the whitelist option if the client IP is a member of both sets.
Blacklists take a list of ip-address and ip-address-pattern elements, as the following example shows:
<blacklist> <ip-address>10.132.64.63</ip-address> <ip-address-pattern>240.63.*</ip-address-pattern> </blacklist>
For more information on the ip-address and ip-address-pattern elements, see the whitelist option.
cross-domain-path Path to a cross domain policy file. For more information, see Using cross domain policy files with the NIO server.
enabled-cipher-suites A cipher suite is a set of encryption algorithms. Secure NIO socket server definitions or secure NIO (RTMP, AMF, or HTTP) endpoint definitions can define a restricted set of cipher suites to use with secure connections, as the following examples shows:
<enabled-cipher-suites> <cipher-suite>SSL_RSA_WITH_128_MD5</cipher-suite> <cipher-suite>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</cipher-suite> </enabled-cipher-suites>
If left undefined, the default set of cipher suites for the security provider implementation of the Java virtual machine (JVM) are used for secure connection handshaking. If an unsupported cipher suite is defined, an error occurs and a ConfigurationException exception is thrown when the server starts.
General Server Options
bind-address (Optional) Binds the server to a specific network interface. If left unspecified, the server binds to all local network interfaces on startup.
bind-port (Optional) Binds the server to a port that differs from the public port that clients connect to. This allows clients to connect to a public port on a firewall or load balancer that forwards traffic to this internal port.
Connection Configuration Options
connection-buffer-type (Optional) Controls the type of byte buffers that connections use to read and write from the network. Supported values include:
heap (default) specifies to use heap-allocated ByteBuffers.
direct specifies to use DirectByteBuffers.
Performance varies depending upon JRE and operating system.
connection-read-buffer-size (Optional) Default value is 8192 (8 KBytes). Size, in bytes, for the read buffer for connections.
connection-write-buffer-size (Optional) Default value is 8192 (8 KBytes). Size, in bytes, for the write buffer for connections.
Control the threading behavior of the server in the absence of a WorkManager.
websphere-workmanager-jndi-name (Optional) For IBM WebSphere deployment, the WorkManager configured and referenced as the worker thread pool for the server. A WorkManager must be referenced to support JTA, which the Data Management Service uses.
max-worker-threads (Optional) The upper bound on the number of worker threads that the server uses to service connections. Defaults to unbounded with idle threads being reaped based upon the idle-worker-thread-timeout-millis value. Ignored if the server is using a WorkManager.
min-worker-threads (Optional) A nonzero, lower bound on the number of worker threads that the server uses to service connections. Defaults to 0. If nonzero, on server start up this number of worker threads is prestarted. Ignored if the server is using a WorkManager.
idle-worker-thread-timeout-millis (Optional) Time, in minutes, that a worker thread must be idle before it is released. Defaults to 1. Ignored if the server is using a WorkManager.
worker-thread-priority (Optional) Desired priority for the server threads. Defaults to Thread.NORM_PRIORITY. Ignored if the server is using a WorkManager.
Acceptor and Reactor Configuration Options
accept-backlog (Optional) The suggested size of the accept queue for the server socket to buffer new connect requests when the server is too busy to handshake immediately. Default is the platform default value for a server socket.
accept-thread-priority (Optional) Allows the priority for accepting new connections to be adjusted either above or below the general server priority for servicing existing connections. Default is the thread priority of the worker thread pool or the WorkManager (whichever is used).
reactor-count (Optional) Splits IO read/write readiness selection for all existing connections to the server out across all available processors and divides the total readiness selection set by the number of reactors to avoid having a single Selector manage the state for all connections. Default is the number of available physical processors on the machine.
TLS/SSL Configuration Options
keystore-type (Optional) Default value is JKS. Specifies the keystore type. The supported values include: JKS and PKCS12.
keystore-file Points to the actual keystore file on the running server. The path to the file may be specified as an absolute path, as in:
<keystore-file>C:\keystore.jks</keystore-file>
Or as a relative to the WEB-APP directory using the {context.root} token, as in:
<keystore-file>{context.root}/WEB- INF/certs/keystore.jks</keystore-file>
keystore-password The keystore password.
keystore-password-file Path to a text file on external or removable media that contains the password value. Ignored if keystore-password is specified.
keystore-password-obfuscated (Optional) Default value is false. Set to true if an obfuscated value is stored in the configuration file and a password deobfuscator has been registered for use.
password-deobfuscator (Optional) The class name of a password deobfuscator used to handle obfuscated passwords safely at run time.
A password deobfuscator implements the flex.messaging.util.PasswordDeobfuscator interface, which contains a deobfuscate() and a destroy() method. The flex.messaging.util.AbstactPasswordDeobfuscator class is an abstract class that implements the destroy() method. Your deobfuscator class can extend this class, and just implement a deobfuscate() method. The deobfuscate() method takes a string that contains the obfuscated password and returns a char[] containing the deobfuscated password.
For more information, see the JavaDoc for the flex.messaging.util.PasswordDeobfuscator interface and the flex.messaging.util.AbstractPasswordDeobfuscator abstract base class.
algorithm (Optional) Only configure this option when using a third-party security provider implementation. Defaults to the current default JVM algorithm. The default JVM algorithm can be controlled by setting the ssl.KeyManagerFactory.algorithm security property.
Example usage:
<algorithm>Default</algorithm> - Explicitly uses the default JVM algorithm.
<algorithm>SunX509</algorithm> - Uses Sun algorithm; requires the Sun secuity provider.
<algorithm>IbmX509</algorithm> - Uses IBM algorithm; requires the IBM security provider.
alias (Optional) If a keystore is used that contains more than one server certificate, use this property to define which certificate to use to authenticate the server end of SSL/TLS connections.
protocol (Optional) Default value is TLS. The preferred protocol for secure connections.
Socket Configuration Options (for accepted sockets)
socket-keep-alive-enabled (Optional) Enables/Disables SO_KEEPALIVE for sockets the server uses.
socket-oobinline-enabled (Optional) Enables/Disables OOBLINE (receipt of TCP urgent data). Defaults to false, which is the JVM default.
socket-receive-buffer-size (Optional) Sets the SO_RCVBUF option for sockets to this value, which is a hint for the size of the underlying network I/O buffer to use.
socket-send-buffer-size (Optional) Sets the SO_SNDBUF option for sockets to this value, which is a hint for the size of the underlying network I/O buffer to use.
socket-linger-seconds (Optional) Enables/Disables SO_LINGER for sockets the server uses where the value indicates the linger time for a closing socket in seconds. A value of -1 disables socket linger.
socket-tcp-no-delay-enabled (Optional) Enables/Disables TCP_NODELAY, which enables or disables the use of the Nagle algorithm by the sockets.
socket-traffic-class (Optional) Defines the traffic class for the socket.
Using cross domain policy files with the NIO server
By default, the Flash Player security sandbox only allows a SWF file to make requests back to the same domain that the SWF file originated from. You use a cross domain policy file to deal with this security restriction. If a SWF file makes a request to a domain that is different than the one from which it originated, Flash Player makes a request to the new domain for a cross domain policy file that can provide the SWF file with additional permissions to communicate with the domain.
For servlet-based endpoints, LiveCycle Data Services ES depends on the application server for cross domain policy file handling. For NIO-based AMF and HTTP endpoints, LiveCycle Data Services ES must depend on the NIO server for cross domain policy file handling and not the application server itself. This is because the NIO server listens for requests on a different port than the application server.
If your application makes a request to an AMF or HTTP endpoint at the http://domainA:8400/lcds/messagebroker/amfpolling and domainA is not the same domain the SWF file was downloaded from, Flash Player makes a cross domain policy file request to http://domainA:8400. To allow the application to make the request to the AMF endpoint, you must place a cross domain policy file in the root directory of your application server. For example, with a typical installation of Tomcat, this would be the TOMCAT_HOME\webapps\ROOT directory.
If your application makes a request to an NIO-based AMF or HTTP endpoint at the http://domainA:1234/nioamfpolling and domainA is not the same domain the SWF file was downloaded from, Flash Player makes a cross domain policy file request to http://domainA:1234. Since this request goes directly to the NIO server and not to the application server, you must configure the NIO server to serve the cross domain policy file. To do this, you add a cross-domain-path property to your NIO server settings in your services-config.xml file as the following example shows:
<server id="my-nio-server" class="flex.messaging.socketserver.SocketServer">
<properties>
<http>
<cross-domain-path>crossdomain.xml</cross-domain-path>
</http>
</properties>
</server>
Because this setting only applies to NIO-based AMF and HTTP endpoints it goes in the http section of configuration settings. The NIO server expects cross domain policy files to be under the WEB-INF/flex directory of the LiveCycle Data Services ES web application. In the previous example, you would place a file called crossdomain.xml with your cross domain policy settings in the WEB-INF/flex directory of your LiveCycle Data Services ES web application.
You can also place cross domain files in subdirectories under WEB-INF/flex. This lets you have cross domain policy files for individual NIO-based endpoints. For example, if you want a cross domain policy file that only applies to your NIO-based AMF endpoint at http://domainA:1234/nioamfpolling, you would configure your application as follows:
Use a cross-domain-path of /nioamfpolling, which causes the NIO server to search for a cross domain policy file under /WEB-INF/flex/nioamfpolling.
The cross domain path must match the cross domain policy request. This means that to use the cross domain policy file under /WEB-INF/flex/nioamfpolling, the request must be made to http://domainA:1234/nioamfpolling/crossdomain.xml.
By default, the cross domain policy request is made to the root of the application; for example, http://domainA:1234/crossdomain.xml. To override this behavior in your application, you must use the Security.loadPolicyFile() method; in your application, before you make the request to the endpoint, you would add the following line of code.
Security.loadPolicyFile("http://domainA:1234/nioamfpolling/crossdomain.xml");
This causes Flash Player to attempt to load a cross domain policy file with the supplied URL. In this case, the NIO server returns a cross domain policy file from the WEB-INF/flex/nioamfpolling directory and the permissions in the policy file are applied to requests to the http://domainA:1234/nioamfpolling endpoint only.