Search

5. Configuring Servers

download PDF
The JBoss ON configuration is edited in one of two areas, depending on the configuration setting:
  • In the JBoss ON GUI

    Note

    Settings that can be edited in the JBoss ON UI must be edited in the JBoss ON UI.
  • In the rhq-server.properties configuration file
Additional configuration is stored in the database backend used by the JBoss ON server.

5.1. Enabling Debug Logging for the JBoss ON Server

Debug mode records debugging messages caused or encountered by the start scripts to the server logs.
Debug messages are in the log file, serverRoot/jon-server-3.0.0.GA1/logs/rhq-server-log4j.log.
In some cases, you will want debug messages from the JBoss ON server launcher scripts. To do this, you need to set the environment variable RHQ_SERVER_DEBUG to any value. After setting this variable when you start the launcher, scripts will output debug messages.

5.1.1. Using an Environment Variable

The quickest way to enable debug logging is to set the RHQ_SERVER_DEBUG environment variable to any value before starting the server.

5.1.2. Setting log4j Priorities

log4j categories support priorities for logging levels. This means that different areas of the agent can be configured for different log levels.

Note

Do not set the RHQ_SERVER_DEBUG environment variable if you are setting priorities in the rhq-server-log4j.xml file. The environment variable overrides this rhq-server-log4j.xml configuration.

Warning

Do not modify anything else in the jbossas directory. This could adversely affect the performance of the JBoss ON server.
To enable debug logging for a category, change the priority value to DEBUG:
  1. Open the jboss-log4j.xml file:
    # vim serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/conf/jboss-log4j.log
  2. Uncomment the org.rhq category to set the priority for all JBoss ON server subsystems to DEBUG.
       <category name="org.rhq">
          <priority value="DEBUG"/>
       </category>
    Alternatively, set DEBUG priorities for individual subsystems in the server. Uncomment the specific categories and set the priority element for the category to DEBUG. Many categories are defined for JBoss ON server subsystems, including database upgrades, global concurrency settings, inventory reports, authorization, alerting, and the UI. There are also categories for third-party subsystems like JBoss/Remoting and Hibernate. For example:
       ...
    					   <!--
       <category name="org.rhq.enterprise.server.alert">
         <priority value="DEBUG"/>
       </category>
       -->
    
       <!--
       <category name="org.rhq.enterprise.server.authz">
         <priority value="DEBUG"/>
       </category>
       -->
    
       <!--
       <category name="org.rhq.enterprise.server.event">
         <priority value="DEBUG"/>
       </category>
       -->
    
       <!--
       <category name="org.rhq.enterprise.server.measurement">
         <priority value="DEBUG"/>
       </category>
       -->
       
       ...

    Note

    By default, the console window will not display debug messages. This is because the log4j CONSOLE appender has a threshold at INFO. For debug messages to appear in the UI, change the CONSOLE appender's threshold setting to DEBUG.
       <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
          <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
          <param name="Target" value="System.out"/>
    	   <param name="Threshold" value="DEBUG"/>
    	   ....
  3. Restart the server to load the new configuration.
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh stop
The log4j file format is described more in the Apache log4j documentation.

5.2. Changing the JBoss ON Server URL

The server URL is the URL used to identify and connect to the server in two ways:
  • Connecting to the GUI
  • Details on alerts, contained in email notifications of alerts
The server URL does not need to be changed unless the JBoss ON connects to the Internet through a proxy server.
  1. Click the Administration tab in the top menu.
  2. In the Configuration menu table on the left, select the System Settings item.
  3. Scroll to the JON General Configuration Properties section in the main work area.
  4. Change the hostname or IP address in the GUI Console URL field.
  5. Click Save.

5.3. Editing JBoss ON Server Configuration in rhq-server.properties

JBoss ON server configuration properties are stored either in the rhq-server.properties configuration file in the serverRoot/jon-server-3.0.0.GA1/bin directory or in the JBoss ON database. The configuration file contains most of the basic information about the JBoss ON server, such as the TCP/IP ports it listens on and its hostname or IP address.
The JBoss ON server configuration is loaded from the rhq-server.properties file when the server starts. The initial configuration is defined by the installer when the JBoss ON program is set up.

Note

Because the configuration properties are loaded from rhq-server.properties when the JBoss ON server starts up, you have to restart the JBoss ON server after making any changes to that configuration file so the new settings are loaded.

5.3.1. 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 URLs; e.g. the myhost in http://myhost: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 URLs, such as the 7080 in http://localhost:7080. This is also the unsecure 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 URLs, 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

5.3.2. Setting Concurrency Limits

JBoss ON can handle large numbers of agents, potentially hundreds. The JBoss ON server can possibly be flooded with messages if many agents attempt to communicate with the server simultaneously. This can happen if the JBoss ON server is restarted after being down for a period of time; when JBoss ON agents detect that the JBoss ON server has come back, they all immediately attempt to send it a backlog of messages.
The JBoss ON server can have a configurable limit on the number of concurrent messages that can be processed at one time, to mitigate any risk of flooding the server. Any messages that come in past that limit are dropped and the agent is asked to send them later.
All of the concurrency-related parameters are listed in Table 10, “rhq-server.properties Parameters for Concurrency Limits”.
Concurrency limits not only limit the number of agent connections, but also the number of connections to the GUI and other web connections to the server. There are three primary parameters that control the concurrency limits:
  • A global limit on the total number of incoming messages to the server (rhq.communications.global-concurrency-limit).
    This is the total number of allowed agent connections. There are other concurrency limits for specific message types which can help tune performance for content downloads, inventory synchronization, and other resource-intensive or recurring agent operations. Those concurrency limits apply only to those specific message types, and those limits are evaluated independently of each other. The global concurrency limit is the total cap for all agent conenctions. This is the effective concurrency limit, even if the sum of the other concurrency limits is higher.
  • A limit on the total number of concurrent web connections allowed (rhq.server.startup.web.max-connections).
    This counts any client connection which connects to the JBoss ON server over an HTTP or HTTPS connection. This includes web GUI connections, of course, but it also includes all agent connections which use the (default) servlet or ssslservlet transports.
    The limit on web connections is the same for both non-secured HTTP requests and HTTPS requests, but the limit is additive so HTTP and HTTPS connections count against different pools. The total maximum connections allowed is actually twice whatever the rhq.server.startup.web.max-connections value is. For example, if the setting is 300, then 300 HTTP requests are allowed and 300 HTTPS requests are allowed, for total of 600 concurrent web connections.
  • Limits on the number of downloads from agents (rhq.server.agent-downloads-limit) and from other clients (rhq.server.client-downloads-limit).

Example 6. Concurrency Limits

rhq.server.startup.web.max-connections=200
rhq.server.agent-downloads-limit=45
rhq.server.client-downloads-limit=5
rhq.communications.global-concurrency-limit=30
Table 10. rhq-server.properties Parameters for Concurrency Limits
Parameter Description
rhq.server.startup.web.max-connections Sets a limit on the number of web connections that can be concurrently created, including both connections to the GUI and connections by agents.

Note

If agent requests are routed over web connections, make sure that the rhq.communications.global-concurrency-limit value is slightly lower than the web connections limit. Otherwise, GUI users could be blocked from accessing the JBoss ON UI whenever there is a high agent load.
The limit on web connections is the same for both HTTP and HTTPS (secure) requests, so the total max connections allowed is actually twice what this setting is. For example, if the max web connections is set to 300, then 300 HTTP requests will be allowed and 300 HTTPS requests will be allowed, for a total of 600 concurrent web connections.
rhq.communications.global-concurrency-limit
Sets the total number of agent messages that come into the server. This only affected incoming agent messages, not GUI requests. If this global concurrency limit is set to 300, no more than 300 total agent messages can be processed at any one time, regardless of what kinds of messages are coming in.
Even if the sum of the other concurrency limits are higher than this global limit, they are capped at this global limit since there can never be more messages processed than the global limit.
This value should be slightly lower than the number of allowed web connections so that web connections to the GUI are not blocked when there is a high agent load.
rhq.server.concurrency-limit.inventory-report Inventory reports are sent from the agent when the agent starts up, and periodically thereafter. Inventory reports can be large, depending on the number of resources on the agent machine.
rhq.server.concurrency-limit.availability-report Availability reports are regularly sent from the agent, typically every 60 seconds. Availability reports are usually very small, but occur in large numbers due to the high frequency of their transmission.
rhq.server.concurrency-limit.inventory-sync Inventory synchronizations occur when the agent needs to synchronize its inventory with that of the server. Agents typically synchronize at startup. Traffic that flows as part of inventory synchronizations is usually large, depending upon the number of resources managed by the agent.
rhq.server.concurrency-limit.content-report Content reports are similar to inventory reports except they contain information about discovered content (i.e., installed packages of software). These reports can be large depending on the number of installed software the agent has discovered and is managing.
rhq.server.concurrency-limit.content-download Content downloads occur when a resource on an agent needs to ask for the content of a package version, usually for the purpose of installing the package.
rhq.server.concurrency-limit.measurement-report Measurement reports are periodically sent to the server whenever the agent completes measurement collections. The number and size of measurement reports can vary, depending on the number and frequency of measurements scheduled to be collected. The greater the number of schedule measurements the agent needs to collect, the more frequently measurement reports are sent, and the larger the reports will be.
rhq.server.concurrency-limit.measurement-schedule-request Similar to inventory synchronization, measurement schedule requests are sent to the agent asking the server for an up-to-date set of measurement schedules that have to be collected.

5.3.3. Configuring the SMTP Server for Email Notifications

Each JBoss ON server talks to a specific SMTP server. The SMTP server is defined in the rhq-server.properties file. The default configuration points to the local JBoss ON server hosts.
# Email
rhq.server.email.smtp-host=localhost
rhq.server.email.smtp-port=25
rhq.server.email.from-address=rhqadmin@localhost
These settings can be edited to use a different SMTP server or email account.

Note

To confirm that the SMTP settings are correct and the server can send emails successfully, go to the test email page at http://server/admin/test/email.jsp.
Table 11. rhq-server.properties Parameters for SMTP
Parameter Description
rhq.server.email.smtp-host Sets the hostname of the SMTP server used by the JBoss ON server.
rhq.server.email.smtp-port Sets the port of the SMTP server used by the JBoss ON server.
rhq.server.email.from-address Sets the address to use for the From header of all emails sent by the JBoss ON server.

5.3.4. Installing a Server Silently

Some options in the rhq-server.properties file tell the installation process to load the server configuration from the file rather than the from the web-based installer.
# Auto-Install Pre-Configuration Settings
rhq.autoinstall.enabled=false
rhq.autoinstall.database=auto
rhq.autoinstall.public-endpoint-address=
These settings are only used for installation.
Table 12. rhq-server.properties Parameters for Silent Installation
Parameter Description
rhq.autoinstall.enabled Tells the installation process whether to load the configuration from the rhq-server.properties file (true) or from the web-based installer (false).
rhq.autoinstall.database Tells the install process how to load or add database schema. There are three options:
  • auto creates a new schema for new installation or upgrades existing schema without overwriting the data.
  • overwrite overwrites the database and creates a new, empty schema.
  • skip skips the entire database process so no database is created or updated.
rhq.autoinstall.public-endpoint-address Sets the IP address or hostname to use for the server. If no value is given, then the server detects and sets its own value when it starts.

5.4. Synchronizing Server Configuration

Even in different environments, JBoss ON servers can share a lot of the same configuration. For example, different JBoss ON servers may manage a development environment, staging environment, and production environment, yet on all three, the servers use similar metric templates and configuration settings.
To simplify managing separate but similar environments, JBoss ON can export the configuration for a server and then import that configuration into another server.
Any user with permissions to manage settings can export the server configuration. There are two categories of data:
  • System settings, which include how long alerts, events, and monitoring metrics are stored; the baseline calculation schedule; and the LDAP server configuration.
  • Metric collection settings for each resource types.
The information is exported to dumped to a gzipped XML file, which can be easily edited before being imported into another server.

Note

Syncing server configuration is only necessary when servers use different backend databases. Servers which share a database (in the high availability cloud) already share their configuration.
Import and export operations are only done through the JBoss ON CLI. This API is available with the other JBoss ON documentation. Running the CLI is covered more in Running JBoss ON Command-Line Scripts.

5.4.1. Exporting a Server's Configuration

  1. Log into the JBoss ON CLI.
    [root@server bin]#  installDir/bin/rhq-cli.sh -u rhqadmin -p rhqadmin
  2. Export the data to a database object:
    rhqadmin@localhost:7080$ var ex = SynchronizationManager.exportAllSubsystems();
  3. Convert that object into an export file. The file extension should be .xml.gz because the export format is a GZIP'ed XML file.
    rhqadmin@localhost:7080$ saveBytesToFile(ex.exportFile, 'export.xml.gz');

Note

The user must have the manage settings permission to export the server data.

5.4.2. Importing a Server's Configuration

Server configuration is exported into an XML file. Administrators can edit this file to control what kind of information is imported into the other JBoss ON servers, so there is a lot of adaptability in the import process. When the file is imported, it first runs through a series of validation tests to make sure that the configuration data can actually be imported into the server. Then, two classes or synchronizers, one for system settings and one for metric templates, are used to import the data.
The import process can be changed by administrators, so there are several common import scenarios:
  • The configuration data are imported directly into the server, using all of the default settings.
  • The XML file can be edited so that the configuration values are adapted to the target JBoss ON servers.
  • The synchronizer behavior is changed, which changes what data elements are imported.
5.4.2.1. Editing the XML Import File
All of the data are dumped to a single XML file, which contains the system settings, metric settings for each resource type, and some processing instructions.
The configuration entries all defined in two large <entities> elements.
Metric templates list each metric separately in individual <entity> elements, with the metric itself identified by its name, resource type, and plug-in as arguments for the element. The entity ID identifies the template in the JBoss ON database, but is ignored during import because the IDs do not need to match between servers.
<entities id="org.rhq.enterprise.server.sync.MetricTemplateSynchronizer">
	<entity>
		<data>
			<metricTemplate 
				enabled="false" 
				defaultInterval="300000"
				perMinute="false" 
				metricName="trap_count" 
				resourceTypePlugin="snmptrapd"
				resourceTypeName="SnmpTrapd" 
				referencedEntityId="10001">
			</metricTemplate>
		</data>
	</entity>
	.....
System settings, on the other hand, are all defined in a single <entity> element, and each configuration parameter is given as a key on the entry. Not all of these keys are imported into the target server; the keys which are imported depend on the synchronizer configuration.
<entities id="org.rhq.enterprise.server.sync.SystemSettingsSynchronizer">
	<entity>
		<data>
			<systemSettings referencedEntityId="0">
				<entry key="CAM_BASE_URL">http://10.16.65.121:7080/</entry>
				<entry key="CAM_DATA_PURGE_6H">2678400000</entry>
				<entry key="CAM_LDAP_BIND_DN"></entry>
				.....
			</systemSettings>
		</data>
	</entity>
</entities>
5.4.2.2. Changing the Synchronizer Configuration
JBoss ON uses synchronizers to set what elements — like what metric schedules — are imported into the JBoss ON server and how to apply them to the server. The synchronizer has a default template which applies configuration changes programmatically to every import operation. There is also synchronizer configuration in the exported XML file, which are applied to that specific import operation.

Note

Custom settings in the XML file override the programmatic template settings. Programmatic settings passed with the CLI commands override the settings in the XML file.
To print the configuration for a specific synchronizer, specify the synchronizer name in SynchronizationManager.getImportConfigurationDefinition(). For example:
rhqadmin@localhost:7080$ var configDef = SynchronizationManager.getImportConfigurationDefinition('org.rhq.enterprise.server.sync.SystemSettingsSynchronizer')
To print all of the configuration for both synchronizers:
rhqadmin@localhost:7080$ var configDefs = SynchronizationManager.importConfigurationDefinitionOfAllSynchronizers 
rhqadmin@localhost:7080$ configDef = configDefs.get(0)

rhqadmin@localhost:7080$ pretty.print(configDef.configurationDefinition.defaultTemplate.configuration)
5.4.2.2.1. Changing the Synchronizer Settings in the XML File
The simplest way to customize the synchronizer configuration is to change the configuration in the exported XML file. The settings and metrics synhcronizers use XML elements that are very similar to the resource plug-in configuration. The root element for a synchronizer is <default-configuration>, and the configuration settings are listed as properties within that element.
The settings synchronizer has the simplest configuration. It has a single <ci:simple-property> element, and the list of settings to import is given in the value= flag on the <ci:simple-property> element.
<default-configuration>
    <ci:simple-property value="AGENT_MAX_QUIET_TIME_ALLOWED, ENABLE_AGENT_AUTO_UPDATE, ENABLE_DEBUG_MODE, ENABLE_EXPERIMENTAL_FEATURES, 
CAM_DATA_PURGE_1H, CAM_DATA_PURGE_6H, CAM_DATA_PURGE_1D, CAM_DATA_MAINTENANCE, DATA_REINDEX_NIGHTLY, RT_DATA_PURGE, ALERT_PURGE, EVENT_PURGE, 
TRAIT_PURGE, AVAILABILITY_PURGE, CAM_BASELINE_FREQUENCY, CAM_BASELINE_DATASET" type="string" name="propertiesToImport">
        <c:description>The names of the properties that should be imported. Note that these are the INTERNAL names as used in the RHQ database</c:description>
    </ci:simple-property>
</default-configuration>

Note

The values for the settings are the names used in the JBoss ON database for the server settings.
The metrics schedules settings are much more complex because the potential metrics schedules are different for each resource. A metric schedule can be defined in any of three ways (or a combination):
  • A simple list, which has a <ci:list-property> list members defined by a property (<ci:simple-property>) and a list of values
    <default-configuration>
        <ci:list-property name="my-list">
            <c:simple-property name="element" type="string"/>
            <ci:values>
               <ci:simple-value value="a"/>
               <ci:simple-value value="b"/>
               <ci:simple-value value="c"/>
            </ci:values>
        </ci:list-property>
    </default-configuration>
  • A map of values, which is very similar to a simple list in that it uses a list of properties (<ci:simple-property>) and a corresponding list of values (<ci:simple-value>), except that each value corresponds to a single, specified property based on the name
    <default-configuration>
        <ci:map-property name="my-map">
            <c:simple-property name="prop1" type="integer"/>
            <c:simple-property name="prop2" type="string"/>
            <c:simple-property name="prop3" type"boolean"/>
            <ci:values>
                <ci:simple-value property-name="prop1" value="1"/>
                <ci:simple-value property-name="prop2" value="abc"/>
                <ci:simple-value property-name="prop3" value="true"/>
            </ci:values>
        </ci:map-property>
    </default-configuration>
  • A table, which is a list of maps. Each set of maps specifies one table in the row.
    <default-configuration>
        <ci:list-property name="table">
            <c:map-property name="row">
                <c:simple-property name="column1" type="integer"/>
                <c:simple-property name="column2" type="boolean"/>
                <c:simple-property name="column3" type="string"/>
            </c:map-property>
            <ci:values>
                <ci:map-value>
                   <ci:simple-value property-name="column1" value="1"/>
                   <ci:simple-value property-name="column2" value="true"/>
                   <ci:simple-value property-name="column3" value="a"/>
                </ci:map-value>
                <ci:map-value>
                   <ci:simple-value property-name="column1" value="2"/>
                   <ci:simple-value property-name="column2" value="true"/>
                   <ci:simple-value property-name="column3" value="b"/>
                </ci:map-value>
                <ci:map-value>
                   <ci:simple-value property-name="column1" value="3"/>
                   <ci:simple-value property-name="column2" value="false"/>
                   <ci:simple-value property-name="column3" value="c"/>
                </ci:map-value>
            </ci:values>
        </ci:list-property>
    </default-configuration>
For example, this uses a map to import only the metric schedule for the free memory metric for a JBoss AS 5 server:
<default-configuration>
    <ci:simple-property value="false" type="boolean" name="updateAllSchedules" />
    <ci:list-property name="metricUpdateOverrides">
        <c:map-property summary="false" required="true" readOnly="false" name="metricUpdateOverride">
            <c:simple-property type="string" summary="false" required="true" readOnly="false" name="metricName" />
            <c:simple-property type="string" summary="false" required="true" readOnly="false" name="resourceTypeName" />
            <c:simple-property type="string" summary="false" required="true" readOnly="false" name="resourceTypePlugin" />
            <c:simple-property type="boolean" summary="false" required="true" readOnly="false" name="updateSchedules" />
        </c:map-property>
        <ci:values>
           <ci:map-value>
               <ci:simple-value name="metricName" value="MCBean|ServerInfo|*|freeMemory"/>
               <ci:simple-value name="resourceTypeName" value="JBoss AS Server"/>
               <ci:simple-value name="resourceTypePlugin" value="JBossAS5"/>
               <ci:simple-value name="updateSchedules" value="true"/>
           </ci:map-value>
        </ci:values>
    </ci:list-property>
</default-configuration>
To update all metrics schedules, set the <ci:simple-property> element to name="updateAllSchedules".
To update a single metric schedule, then set the property element's name to metricUpdateOverride and set the updateSchedules property value to true.
5.4.2.2.2. Changing the Synchronizer Settings Programmatically
To change the configuration, create a new instance of the default and use the setValue configuration object to add or remove keys from the list. For the settings synchronizer, this lists the key name to import:
configurationObject.getSimple('propertiesToImport').setValue(defaultSettingsToImport + ', keyName')
For metrics schedules, it lists the metric schedule per resource type, based on a properties list or a properties map:
var update = new PropertyMap('metricUpdateOverrides')
update.put(new PropertySimple('propertyName', 'resourcePluginName'))
  1. Get the default definition.
    rhqadmin@localhost:7080$ var systemSettingsImportConfigurationDefinition = SynchronizationManager.getImportConfigurationDefinition('org.rhq.enterprise.server.sync.SystemSettingsSynchronizer')
  2. Create a new configuration instance.
    rhqadmin@localhost:7080$ var configurationObject = systemSettingsImportConfigurationDefinition.configurationDefinition.defaultTemplate.createConfiguration()
    
    rhqadmin@localhost:7080$ var systemSettingsImportConfiguration = new ImportConfiguration(systemSettingsImportConfigurationDefinition.synchronizerClassName, configurationObject)
  3. Change the settings in the new instance.
    For example, for the server settings synchronizer:
    rhqadmin@localhost:7080$ var defaultSettingsToImport = configurationObject.getSimple('propertiesToImport').stringValue
    	
    rhqadmin@localhost:7080$ configurationObject.getSimple('propertiesToImport').setValue(defaultSettingsToImport + ', CAM_BASE_URL')
    For the metrics template synchronizer:
    configurationObject.getSimple('updateAllSchedules').setBooleanValue(true)
    var updateList = new PropertyList('metricUpdateOverrides')
    var update = new PropertyMap('metricUpdateOverride')
    update.put(new PropertySimple('metricName', 'MCBean|ServerInfo|*|freeMemory'))
    update.put(new PropertySimple('resourceTypeName', 'JBossAS Server'))
    update.put(new PropertySimple('resourceTypePlugin', 'JBossAS5'))
    update.put(new PropertySimple('updateSchedules', 'true'))
    
    updateList.add(update)
    
    configurationObject.put(updateList)
5.4.2.3. Importing the Configuration
  1. Log into the JBoss ON CLI.
    [root@server bin]#  installDir/bin/rhq-cli.sh -u rhqadmin -p rhqadmin
  2. Import the XML file containing the configuration:
    rhqadmin@localhost:7080$ var data = getFileBytes('export.xml.gz');
    rhqadmin@localhost:7080$  SynchronizationManager.importAllSubsystems(ex, null);
    The null parameter means that the import process uses the default settings in the XML file or, if the defaults are missing from the XML, that it uses the settings defined on the target server. If alternate settings were constructed in Section 5.4.2.2, “Changing the Synchronizer Configuration”, then they can be specified programmatically instead. For example:
    rhqadmin@localhost:7080$ var configsToImport = new java.util.ArrayList()
    rhqadmin@localhost:7080$ configsToImport.add(systemSettingsImportConfiguration);
    rhqadmin@localhost:7080$ configsToImport.add(metricTemplatesImportConfiguration);
    rhqadmin@localhost:7080$ SynchronizationManager.importAllSubsystems(ex, configToImport);
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.