6.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 10, “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.
See Section 4.2, “Setting up Client Authentication Between Servers and Agents” for setting up SSL sockets.
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 6. 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 6, “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.
| 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. |
| | Ports used by internal services. |
| SSL Connection Parameters | |
| The secure protocol that agents must use when communicating with this JBoss ON server. |
| The keystore file that contains a certificate that authenticates the JBoss ON server to the agents. |
| |
| The file format of the keystore. |
| The password that is used to gain access to the keystore file. |
| The password that is used to gain access to the key inside the keystore. |
| The alias that identifies the JBoss ON server's key within its keystore. |
| 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. |
| |
| The file format of the truststore file. |
| The password that is used to gain access to the truststore file. |
| 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 11, “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.
| |
| 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 |
