JBoss Community Archive (Read Only)

RHQ 4.9

Startup Properties

The startup configuration settings read by the RHQ Server are stored in the rhq-server.properties file located in the /bin directory of the server distribution. This file includes settings not persistent in the database (i.e. these startup settings are specific for a single RHQ Server instance - they are not applied across all RHQ Servers in the cloud). If you modify any setting in this file, you must restart the RHQ Server in order for the changes to take effect.

Due to some limitations within the app server, there are two RHQ settings that will not take effect immediately upon restart if you change their values after the initial installation. These are settings for the web connector's keystore and truststore file locations (rhq.server.tomcat.security.keystore.file and rhq.server.tomcat.security.truststore.file). If you ever need to change those values after you've installed RHQ, you will need to change them in the app server's standalone/configuration/standalone-full.xml file in the <ssl> node of the https <connector>.

This rhq-server.properties file defines typical server settings such as the TCP ports that RHQ Server components listen to and the security settings for the server-agent communications subsystem. The values are customized by you during the installation process as per your requirements.

Below are these startup properties.

The rhq-server.properties file contains the database username and password. This password is not obfuscated in earlier RHQ versions. Even in later versions where the password is obfuscated, a competent hacker can decrypt it. Therefore, ensure this file is protected from unwanted access.


These properties defines the RHQ Server's database and how it can connect to it. Review all default settings and update as necessary for your environment. All properties must be set for the desired database vendor:


Defines the vendor of your database that will be used as RHQ's backend persistence store. The only supported values are PostgreSQL or Oracle.


The JDBC URL that the RHQ Server will use when connecting to the database. An example is jdbc:postgresql://localhost:5432/rhq or jdbc:oracle:oci:@localhost:1521:orcl.


The fully qualified class name of the JDBC driver that the RHQ Server will use to communicate with the database. An example is org.postgresql.Driver or oracle.jdbc.driver.OracleDriver.


The name of the user that the RHQ Server will use when logging into the database. This user must be the owner of the RHQ tables.


The obfuscated password of the database user that is used by the RHQ Server when logging into the database. To generate the obfuscated value see Generating Obfuscated Passwords.


The server name where the database is found. This must match the server in the connection URL. Currently only used when connecting to PostgreSQL.


The port on which the database is listening. This must match the port in the connection URL. Currently only used when connecting to PostgreSQL.


The name of the database. This must match the name found in the connection URL. Currently only used when connecting to PostgreSQL.


The name of the Hibernate dialect that identifies the strategy used by Hibernate to connect to and access your database. For example, the Postgres dialect is org.hibernate.dialect.PostgresSQLDialect. The other option is Oracle's dialect which is org.hibernate.dialect.Oracle10gDialect.


Quartz is the scheduling engine used by RHQ. This is a Quartz configuration setting that is specific to your database and provides the strategy for how Quartz connects to and accesses your database. If using Postgres, this value should be org.quartz.impl.jdbcjobstore.PostgreSQLDelegate. If using Oracle, this value should be org.quartz.impl.jdbcjobstore.oracle.OracleDelegate.

Server Settings

Review all default settings and update as necessary for your environment. The following property must be explicitly set:

  • rhq.server.management.password


This is the unique name the RHQ Server. It doesn't necessarily have to be an IP address or hostname but it can be. The only restriction is that all server names be unique in the RHQ server cloud. If left blank, the RHQ Server will be assigned a name based on the machine's hostname. NOTE: if you are upgrading an existing server, this must be the same name as the server being upgraded.


The obfuscated management password for the RHQ Server. RHQ Server resources are pre-set to use the password value provided in a comment in rhq-server.properties. For added security it is recommended to generate a custom password. But realize that the custom obfuscated password value will need to also be set in the connection properties of imported RHQ Server resources. Until updated the RHQ Agent will not be able to connect to the RHQ Server, and it will have down/red status. To generate the obfuscated value see Generating Obfuscated Passwords.


The hostname of the SMTP server that is used when the RHQ Server sends emails.


The port that the RHQ Server will send emails over when communicating with the SMTP server.


The "From:" header of all emails sent by the RHQ Server.

Host and Port Bindings

These are settings that bind the RHQ Server to particular IP addresses and ports. You will normally only need to change these if you have firewall issues that require specific addresses and ports to be used.

Review all default settings and update as necessary for your environment. The following property must be explicitly set:

  • jboss.bind.address


The RHQ GUI Console (among other services) will bind to this IP address. This is the host in the RHQ Console URLs; e.g. the myhost in http://myhost:7080. Setting to will use all network interfaces, this may not be desired in production environments.


The RHQ GUI Console will listen to this port for unsecured HTTP requests coming in. This is the port number in the RHQ Console URLs; e.g. the 7080 in http://localhost:7080. The server will accept incoming agent messages over this port if the agent is told to send messages to the server over the unsecured servlet protocol.


The RHQ GUI Console will listen to this port for secured HTTPS requests coming in. This is the port number in the RHQ Console URLs; e.g. the 7443 in https://localhost:7443. The server will accept incoming agent messages over this port if the agent is told to send messages to the server over the secured sslservlet protocol.


The rest of these are ports used internally by the RHQ Server.


Used by the installer to communicate to this server when completing the installation of the RHQ Server. This is also the port the RHQ Server agent plugin uses when you are managing the RHQ Server via the RHQ Agent itself.


This can be used by the JBossAS agent plugin when you are managing the RHQ Server via the RHQ Agent itself.


This can be used by the JBossAS agent plugin when you are managing the RHQ Server via the RHQ Agent itself.

Installer Settings


Set this to true when you are ready to run the installer that completes your RHQ Server installation.


The allowed values for this setting are auto, overwrite, or skip.

  • auto will create a new database schema if one does not yet exist or, if a schema does exist, will simply upgrade it as needed (which keeps existing data).

  • overwrite if you want to create an empty schema, even if one already exists (loses existing data).

  • skip if you don't want to do any database upgrade or creation. WARNING! You must ensure your database schema already exists and is up to date.


public IP/hostname that all agents will use to talk to this server. If not set, a value to use is determined at auto-install time.

Storage Settings


The username that will be used to authenticate against the storage node cluster.


The obfuscated password that will be used to authenticate the username. To generate the obfuscated value see Generating Obfuscated Passwords.


A comma-delimited list of storage nodes. Each Cassandra node uses this list as contact points to find other nodes in the cluster and learn the ring topology. The RHQ server(s) use this list to connect to the cluster; therefore, this property MUST BE SET in order for RHQ to talk to Cassandra. this is an installer setting. Changing the value after installation will have no effect.


The list of ports used by the RHQ server(s) to communicate with the cluster.


The list of ports used by storage nodes to communicate with each other.


This property is obsolete and is ignored. As of RHQ 4.9, there is no support for compression with the Cassandra CQL driver.

Advanced Settings


Sets the logging level for all RHQ code. If under normal operations, you should set this to INFO. However, when debugging problems with the RHQ Server, you can set this to DEBUG to enable more verbose logging.


If true, the server will start in maintenance mode at startup. If false, whatever mode the server was in when it shutdown will be the mode it will be in when it starts up.


One of the features of RHQ is the ability to invoke operations on a resource. The RHQ Server will be able to ask an agent to invoke a particular operation on a particular resource managed by that agent. Because of the remote, asynchronous nature of operation invocations, alot of things can go wrong (the network goes down, the resource crashes, etc.). This operation timeout is the default number of seconds that the RHQ Server will wait for an operation to complete and an agent to provide the results. If this timeout expires, the operation will be considered to have failed. Note that this is only a fallback default value - individual operations can define their own timeouts (in the plugin descriptor) or individual operation invocations can themselves specify a timeout. Those override this default rhq.operation-timeout setting.


Periodically, the RHQ Server will scan it is local file system and the database to see if any changes have been made to deployed agent plugins and server plugins. This value is the amount of milliseconds the server waits before checking its plugins again.


When this is enabled (i.e. set to true), the server will, at start up, compare its endpoint address to the host name/address found on the host machine. If they differ, the server endpoint address will be updated to the value found on the host machine. This addresses the problem of address/host name changes that will occur in cloud deployments such as EC2 when a server machine is restarted.

Communications Settings


These are communication configuration settings for the server's endpoint that agents will talk. See Communications Configuration and Securing Communications for details on these and related settings.


These are security settings for the server's endpoint that agents can talk securely to over the "sslsocket" protocol. See Securing Communications for details on these and related settings.


These are security settings for the Tomcat web connector. These are used both during browser access and when agents talk to the server over the sslservlet protocol. See Securing Communications for details on these and related settings.


These are security settings the server used when sending messages to the agent. See Securing Communications for details on these and related settings.

Concurrency Limits

RHQ is designed to scale to large numbers of agents. The RHQ Server must, therefore, take into account the possibility that it could get flooded with messages if many or all agents attempt to communicate with the server simultaneously (as will be the case if the RHQ Server is restarted after being down for a while; RHQ Agents will detect the RHQ Server has come back up and will attempt to immediately send it a backlog of messages).

To help alleviate problems that could occur during high load, the RHQ Server is configured to limit the number of concurrent messages allowed to be processed by different subsystems within the RHQ Server. If more messages arrive concurrently, such that the limit is exceeded, those additional messages will be dropped and the agent will be asked to send them later. The following configuration settings define types of messages that have concurrency limits associated with them.


RHQ limits the number of web connections that can be concurrently created. This includes GUI connections made by browsers. It may also include connections made by agents, if agent connections are made via the servlet or sslservlet transport. Note that if agent requests are routed over web connections, you should ensure that the Global Concurrency Limit is slightly lower than this Web Connections limit so as not to lock out GUI users from accessing the user interface during times of high agent load. This limit on web connections is the same for both non-secured http requests and secured https 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 possible total of 600 concurrent web connections.


Aside from the Web Connections limit, all other concurrency limits will only affect incoming agent messages (not GUI/browser requests). This global concurrency limit will limit the total number of agent messages coming into the server, regardless of the type of message. In other words, if this global concurrency limit is set to 300, no more than 300 total agent messages can be processed at any one time, no matter what kinds of messages are coming in. The rest of the concurrency limit settings will put a limit on the number of messages of particular message types. Keep in mind that if other concurrency limits are set higher than this global limit, they are effectively capped at this global limit since you can never have more than this global limit number of messages concurrently being processed.


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.


Availability reports are sent from the agent very often (typically every 5 minutes). Availability reports are usually very small, but occur in large numbers due to the high frequency of their transmission.


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.


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.


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.


Measurement reports are sent to the server periodically whenever the agent completes measurement collections. The number of measurement reports vary as do their size, depending on the number and frequency of measurements that are 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 they are.


Similar to inventory synchronization, measurement schedule requests are sent to the agent when the agent wants to ask the server for its up-to-date set of measurement schedules that have to be collected.


When the agent detects configuration changes, it will send those updated configurations unsolicited to the server. This limits the number of configuration updates a server can process.

Generating Obfuscated Passwords

The following properties require obfuscated password values:

  • rhq.storage.password

  • rhq.server.database.password

  • rhq.server.management.password

To generate the obfuscated password:

> rhq-installer.sh|bat --encodepassword <password>

This will generate obfuscated values for the three properties. Run the command one or more times dependning on how many different passwords will be used, capturing the relevant property value(s) on each run.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 08:47:47 UTC, last content change 2013-09-18 19:43:32 UTC.