5.3.2. Configuring Communication Settings

JBoss ON servers are configured to communicate to agents by defining and identifying ways that the server and agent can connect, as well as how other clients (like users accessing the JBoss ON GUI) can connect to the server. These communication endpoints include identifying the server hostname or IP address, ports that the server listens on for different types of messages, and protocols used to access the server. All of the server connection parameters are described in Table 8, “rhq-server.properties Parameters for Server Connections”.
Connections, or transport methods, for the server are implemented through servlets (HTTP and HTTPS) or sockets (HTTPS). The servlet (HTTP) and sslservlet (HTTPS) transports route traffic through the Tomcat server embedded in the JBoss ON server.

Important

If the server is using the transport servlet or sslservlet, the agent communication is over the Tomcat connector. This means rhq.communications.connector.bind-port is ignored and the Tomcat connector port is used to send messages from agent to server. By default, the Tomcat connector port is 7080 (servlet) or 7443 (sslservlet).

Note

Servlet-based transports leverage the Tomcat connector infrastructure to handle both agent and GUI requests. Using servlets, however, limits agents and GUI clients to use the same connection methods; for certificate-based SSL connections, servlets require users to authenticate to the GUI using a stored browser certificate. For SSL, then, it may be preferable to use socket connections, which allow different authentication methods for agent and GUI sessions.
The general configuration settings set the port numbers that users can used to access the server.
# General Properties
rhq.server.startup.web.http.port=7080
rhq.server.startup.web.https.port=7443
Additional connection settings can be added to configure SSL connections for inbound connections to the server (messages from the agent to the server) and outbound connections (messages from the server to the agent). For example:
rhq.server.tomcat.security.client-auth-mode=want
rhq.server.tomcat.security.secure-socket-protocol=TLS
rhq.server.tomcat.security.algorithm=SunX509
rhq.server.tomcat.security.keystore.alias=RHQ
rhq.server.tomcat.security.keystore.file=conf/rhq.keystore
rhq.server.tomcat.security.keystore.password=RHQManagement
rhq.server.tomcat.security.keystore.type=JKS
rhq.server.tomcat.security.truststore.file=conf/rhq.truststore
rhq.server.tomcat.security.truststore.password=RHQManagement
rhq.server.tomcat.security.truststore.type=JKS
The third part of JBoss ON server communications provides more control over information the connection endpoints for JBoss ON servers and agents to use to talk with each other. These are transport parameters for the server. Both the JBoss ON agent and port use the same remoting framework, using invocation strings that are similar to URLs. These connection strings have the format:
protocol://server:port/transportParm1=value1&transportParam2=value2

Important

For most communications, the JBoss ON server must use either servlet or sslservlet protocols. The only instance where socket can be used is for passing transport parameters. Otherwise, socket and sslsocket are not supported.
The transport configuration first sets up connectors (called endpoints) that the servers and agents jointly define and use for communications. This means that the same information must be in both the server and agent configuration files. Each aspect of the remoting URL is built using separate server configuration parameters.
The standard server configuration has four parts, for the transport method, server IP address, agent port, and any parameters to append to the URL. For example:
rhq.communications.connector.transport=servlet
rhq.communications.connector.bind-address=192.168.1.2
rhq.communications.connector.bind-port=16163
rhq.communications.connector.transport-params=/jboss-remoting-servlet-invoker/ServerInvokerServlet
That standard configuration is merged to create this URL:
servlet://192.168.1.2:16163/jboss-remoting-servlet-invoker/ServerInvokerServlet
A corresponding entry, with the same endpoint definition, is also listed in the agent configuration so that it knows how to send communications to the server, such as sending registration and availability reports.
RHQ Server IP Address=192.168.1.2
RHQ Server Port=16163
RHQ Server Transport Protocol=servlet
RHQ Server Transport Parameters=/jboss-remoting-servlet-invoker/ServerInvokerServlet

Example 5. Basic Server-Agent Transport Example

A server with an IP address of 192.168.0.10 will connect to agents over the standard agent port of 16163. The server configuration has the following configuration to define the server address (rhq.communications.connector.bind-address), the agent communications port (rhq.communications.connector.bind-port), and the connection protocol (rhq.communications.connector.transport):
rhq.communications.connector.transport=servlet
rhq.communications.connector.bind-address=192.168.0.10 
rhq.communications.connector.bind-port=16163 
rhq.communications.connector.transport-params=enableTcpNoDelay=true&backlog=200
The connection URL, then, is:
servlet://192.169.0.10:16163/enableTcpNoDelay=true&backlog=200
The JBoss ON agent configuration will contain corresponding entries which match the server configuration:
RHQ Server IP Address=192.168.0.10 
RHQ Server Port=16163 
RHQ Server Transport Protocol=socket 
RHQ Server Transport Parameters=enableTcpNoDelay=true&backlog=200
Transport parameters can pass relevant information about both incoming and outgoing messages (called server and client messages, respectively, because of how the JBoss ON server handles the messages). These transport parameters are strung together with ampersands (&), as with a standard web URL parameters.
Both server and client transport parameters are passed in the same URL; the JBoss ON server only processes whatever parameters are relevant for the current operation. In Example 5, “Basic Server-Agent Transport Example”, for instance, the configuration sets two transport parameters, enableTcpNoDelay (client) and backlog (server). When the JBoss ON server is receiving messages — when it function as a communications server — it uses the backlog parameter and ignore enableTcpNoDelay because enableTcpNoDelay is only for outgoing (client) messages.

Table 8. rhq-server.properties Parameters for Server Connections

Parameter Description
General Connection Parameters
jboss.bind.address[a][b] Gives the IP address for the JBoss ON GUI console, among other services, to bind to. This is the host in the JBoss ON GUI URL, such as server.example.com in http://server.example.com:7080.
rhq.server.startup.web.http.port[a][b] Gives the port that the JBoss ON GUI listens to for unsecured HTTP requests. This is the port number in the JBoss ON GUI URL, such as the 7080 in http://localhost:7080. This is also the unsecured port used as the endpoint in high availability.
rhq.server.startup.web.https.port[a][b] Gives the port that the JBoss ON GUI listens to for secured HTTPS requests. This is the port number in the JBoss ON GUI URL, such as the 7443 in https://localhost:7443. This is also the secure port used as the endpoint in high availability.
rhq.server.startup.keystore.filename[b] The JBoss ON GUI can accept browser requests over HTTPS. If you want to authenticate the JBoss ON GUI to remote browsers, you need to put an SSL certificate in a keystore file. This setting points to the location of the keystore file. Note that this file name must be a relative file path relative to the <JBoss ON server Install Dir>/jbossas/server/default/conf directory. The JBoss ON server ships with a self-signed certificate in a default keystore file.
rhq.server.startup.keystore.password[b] The password of the keystore file. This is so the JBoss ON GUI can access the keystore file in order to be able to serve the certificate to browser clients.
rhq.server.startup.keystore.sslprotocol[b] The protocol that browser clients should use to communicate with the JBoss ON GUI.
rhq.server.maintenance-mode-at-start Sets whether to start the server in maintenance mode (true) or whether to start the server in whatever mode it was in when it shut down (false). The default is false.
  • rhq.server.startup.webservice.port[a][b]
  • rhq.server.startup.namingservice.port[a][b]
  • rhq.server.startup.namingservice.rmiport[a][b]
  • rhq.server.startup.jrmpinvoker.rmiport[a][b]
  • rhq.server.startup.pooledinvoker.rmiport[a][b]
  • rhq.server.startup.ajp.port[a][b]
  • rhq.server.startup.unifiedinvoker.port[a][b]
  • rhq.server.startup.aspectdeployer.bind-port[a][b]
Ports used by internal services.
SSL Connection Parameters
  • rhq.communications.connector.security.secure-socket-protocol (agent to server)
  • rhq.server.client.security.secure-socket-protocol (server to agent)
The secure protocol that agents must use when communicating with this JBoss ON server.
  • rhq.communications.connector.security.keystore.file (agent to server)
  • rhq.server.client.security.keystore.file (server to agent)
The keystore file that contains a certificate that authenticates the JBoss ON server to the agents.
  • rhq.communications.connector.security.keystore.algorithm (agent to server)
  • rhq.server.client.security.keystore.algorithm (server to agent)
 
  • rhq.communications.connector.security.keystore.type (agent to server)
  • rhq.server.client.security.keystore.type (server to agent)
The file format of the keystore.
  • rhq.communications.connector.security.keystore.password (agent to server)
  • rhq.server.client.security.keystore.password (server to agent)
The password that is used to gain access to the keystore file.
  • rhq.communications.connector.security.keystore.key-password (agent to server)
  • rhq.server.client.security.keystore.key-password (server to agent)
The password that is used to gain access to the key inside the keystore.
  • rhq.communications.connector.security.keystore.alias (agent to server)
  • rhq.server.client.security.keystore.alias (server to agent)
The alias that identifies the JBoss ON server's key within its keystore.
  • rhq.communications.connector.security.truststore.file (agent to server)
  • rhq.server.client.security.truststore.file (server to agent)
The truststore file that contains certificates that this JBoss ON server trusts. If you need the JBoss ON server to authenticate JBoss ON agents, you must set this; otherwise it is not needed. This truststore contains certificates for all JBoss ON agents that need to communicate with this JBoss ON server. Refer to the Incoming Client Authentication Mode.
  • rhq.communications.connector.security.truststore.algorithm (agent to server)
  • rhq.server.client.security.truststore.algorithm (server to agent)
 
  • rhq.communications.connector.security.truststore.type (agent to server)
  • rhq.server.client.security.truststore.type (server to agent)
The file format of the truststore file.
  • rhq.communications.connector.security.truststore.password (agent to server)
  • rhq.server.client.security.truststore.password (server to agent)
The password that is used to gain access to the truststore file.
  • rhq.communications.connector.security.client-auth-mode (agent to server)
  • rhq.server.client.security.server-auth-mode-enabled (server to agent)
Indicates if the JBoss ON server must authenticate the JBoss ON agents that are sending it messages. If the server is using secure connections, but does not have trusted certificates for all of the JBoss ON agents in a truststore, set this to none. The valid values are none, want, or need.
Transport Connection Parameters
rhq.communications.connector.transport Defines how the JBoss ON agents need to transport messages to the JBoss ON server. The allowed values are either servlet or sslservlet. The agent requests go through the JBoss ON server web application layer (i.e. the secure Tomcat Connector). With sslservlet, not only do agent requests route through the web application layer, but they are also secured through the secure Tomcat Connector. The keystore used for incoming agent message authentication is the same as that configured in rhq.communications.connector.security.keystore.file.

Note

This transport setting does not restrict agents from only going over that particular connection method. By default, the JBoss ON server always deploys the communications connector that allows for both servlet and sslservlet traffic. This setting tells the agent to decide what transport is used when it sends messages to the server. If the server has its transport set to servlet, but the agent is configured to talk to the server via sslservlet, the messages the agent sends will be via sslservlet.
rhq.communications.connector.bind-address This is the address that is placed in the server's JBoss/Remoting locator URL. This defines the endpoint that the JBoss ON server will bind its connector to. It also represents the public endpoint address that all agents can use to connect to the server.
rhq.communications.connector.bind-port Defines the endpoint that the JBoss ON server binds to, as well as the public address that all agents can use to connect to the server. This is hidden from view in the installer, although it still appears in the rhq-server.properties file. This value can be blank; the server sets this to either the HTTP or HTTPS port, depending on the transport configured for the server.
rhq.communications.connector.transport-params Defines additional transport parameters the JBoss ON server will set on its connector that will accept incoming messages from the JBoss ON agents. All of the possible transport parameters are listed in Table 9, “Transport Parameters”.
rhq.communications.multicast-detector.enabled If true, the JBoss ON server will attempt to auto-detect JBoss ON agents coming online and going offline using multicast detection. Your network must support multicast traffic for this to work.
rhq.communications.multicast-detector.bind-address The address that the multicast detector directly binds to. This is not used, or needed, if you have not enabled multicast detection.
rhq.communications.multicast-detector.multicast-address The address that the multicast detector will broadcast messages to. This is not used, or needed, if you have not enabled multicast detection.
rhq.communications.multicast-detector.port The port that the multicast detector will broadcast messages to. This is not used, or needed, if you have not enabled multicast detection.
[a] These settings configure specific IP addresses and ports for the JBoss ON server instance. If there are firewall issues the require different settings, then these parameters can be changed.
[b] The JBoss ON server has to be restarted for any changes to this value to take effect.

Table 9. Transport Parameters

Transport Parameter Description For Incoming Messages or for Outgoing Messages
serverBindAddress The address on which the server socket binds to listen for requests. The default is an empty value which indicates the server socket should be bound to the host provided by the InvokerLocator URL (the host). Incoming
serverBindPort The port to listen for requests on. Incoming
timeout The socket timeout value. The default on the server side is 60000 (one minute). If the timeout parameter is set, its value will also be passed to the client-side (see below). Incoming
backlog The preferred number of unaccepted incoming connections allowed at a given time. The actual number may be greater than the specified backlog. When the queue is full, further connection requests are rejected. Must be a positive value greater than 0. If the value passed if equal or less than 0, then the default value will be assumed. The default value is 200. Incoming
numAcceptThreads The number of threads that exist for accepting client connections. The default is 1. Incoming
maxPoolSize The number of server threads for processing client requests. The default is 300. Incoming
socket.check_connection Indicates if the invoker should try to check the connection before re-using it by sending a single byte ping from the client to the server and then back from the server. This configuration needs to be set on both the client and server to work. The default value is false. Incoming
clientConnectAddress The IP address or hostname the client will use to connect to the server-side socket. This would be needed in the case that the client will be going through a router that forwards requests made externally to a different IP address or hostname internally. If no clientConnectAddress or serverBindAddress is specified, the local host's address is used. Outgoing
clientConnectPort The port the client will use to connect to the server-side socket. This would be needed in the case that the client will be going through a router that forwards requests made externally to a different port internally. Outgoing
timeout The socket timeout value. The default on the client side is 1800000 (or 30 minutes). Outgoing
enableTcpNoDelay Indicates if the client socket should have TCP_NODELAY turned on or off. TCP_NODELAY is for a specific purpose; to disable the Nagle buffering algorithm. It should only be set for applications that send frequent small bursts of information without getting an immediate response. The default is false. Outgoing
clientMaxPoolSize The client-side maximum number of active socket connections. This basically equates to the maximum number of concurrent client calls that can be made from the socket client invoker. The default is 50. Outgoing
numberOfRetries The number of retries to get a socket from the pool. This basically equates to the number of seconds the client will wait to get a client socket connection from the pool before timing out. If the max retries is reached, a CannotConnectException will be thrown. The default is 30. Outgoing
numberOfCallRetries The number of retries for making the invocation. This is unrelated to numberOfRetries in that when this comes into play is after it has already received a client socket connection from the pool. However, it is possible that the socket connection timed out while waiting within the pool. Since a connection check is not done by default, the connection is thrown away and an attempt to get a new one will be made. This will happen for however many numberOfCallRetries is (which defaults to 3). However, when (numberOfCallsRetries - 2) is reached, the entire connection pool is flushed under the assumption that all connections in the pool have timed out and are invalid and will start over by creating a new connection. If this still fails, a MarshalException is thrown. Outgoing
socket.check_connection Indicates if the invoker should try to check the connection before re-using it by sending a single byte ping from the client to the server and then back from the server. This configuration needs to be set on both client and server to work. This if false by default. Outgoing