2.6. About the rhqctl Script

JBoss Operations Network has a control script which is used for basic lifecycle management for the server and storage nodes. It can open a server console and start and stop the server.
The control script (rhqctl) has two subcommands which are relevant to the installation process: install and upgrade.

Note

Before proceeding, open JBossON-install-location/bin/rhq-server.properties and change the following attributes: 
rhq.autoinstall.server.admin.password
and 
rhq.server.database.password
using the instructions in Section 2.6.2, “Attributes in the Properties File”.

2.6.1. Using the rhqctl Script

The rhqctl script has subcommands and options: 
rhqctl [command] [[options]
For the installation process, the only relevant command is install.
There are a number of options with the install command which allow for more custom ways of configuring the JBoss ON server, depending on your needs.

Example 2.1. Installing with No Options

The simplest way to configure the server is to run the install command alone. 
[root@server bin]# ./rhqctl install
23:07:00,901 INFO  [org.jboss.modules] JBoss Modules version 1.2.2.Final-redhat-1

The [jboss.bind.address] property is required but not set in [rhq-server.properties].
Do you want to set [jboss.bind.address] value now?
yes|no: yes
jboss.bind.address: 0.0.0.0
Is [0.0.0.0] correct?
yes|no: yes
This installs all three management components:
  • The server
  • The storage database node
  • The local agent
When the configuration process is complete, the server, storage node, and agent are not running, so those processes would need to be started manually. 
[root@server bin]# ./rhqctl start

Example 2.2. Installing and Starting Services

The --start option starts all services as soon as the installation process is complete. This is the same as running the start command immediately. 
[root@server bin]# ./rhqctl install --start

Example 2.3. Installing Specific Services

The install command configures the JBoss ON server, storage node, and agent all at the same time.
While it is recommended that all three management services be run on the same system (and from the same parent directory), there may be some environments where it is beneficial to run the JBoss ON server on a separate machine from the storage node. In other cases, it may be required to install the different services at different times.
The install command has options for each service. If that option is used, the only that service is installed; the other services are excluded.
For example, this installs the server, storage node, and agent in three separate command invocations: 
[root@server bin]# ./rhqctl install --storage --start
[root@server bin]# ./rhqctl install --server --start
[root@server bin]# ./rhqctl install --agent --start
If the services will be installed on the same system but separately, install the storage node first. The storage node needs to be installed and running when the server is installed.

Table 2.4. Options for Installing JBoss ON

Option Description
--start Starts all services as soon as the installation process is complete.
--server Installs the server. The server is installed by default; if this is specified, then the server is installed and other components are not installed (unless they are explicitly mentioned).
--storage Installs the storage database node. The storage database node is installed by default; if this is specified, then the storage database and a companion agent are installed, but the server is not.
--storage-data-root-dir directory Changes the directory where the storage data are stored. By default, the storage node directory is serverRoot/jon-server-3.2.0.GA/rhq-data/.
--agent Installs the agent. The agent is installed by default; if this is specified, then the agent is installed and other components are not installed (unless they are explicitly mentioned).

2.6.2. Attributes in the Properties File

All of the configuration for the JBoss ON server is pulled, at configuration time, from its rhq-server.properties file. Most of the configuration is defined by default:
  • Database connection information
  • The username and password for the database user
  • The JBoss ON server port numbers
  • The name for the server instance in the JBoss ON cloud
  • The way to handle any existing schema in the JBoss ON database
  • Server/agent communication settings, including SSL settings
  • Connection and concurrency limits for the server
There are other settings, as well, but those are the most common ones. The attribute names and descriptions are listed in Table 2.5, “rhq-server.properties Attributes for Server Configuration”.
Any of these settings can be edited before the rhqctl script is run to set new values.
If no changes are made, there are three notable configuration areas:
  • The default database configuration uses a PostgreSQL database installed on the same host as the JBoss ON server.
  • The bind address (IP address) for the server is left blank, and the control script prompts for a value.
  • The server name is left blank, and the default value is the server's hostname.

Table 2.5. rhq-server.properties Attributes for Server Configuration

Parameter Description
rhq.server.high-availability.name Sets an optional name to use to identify the server within the JBoss ON server cloud. If this is not given, then the default value is the server hostname.
jboss.bind.address Gives the IP address to use to connect to the JBoss ON server. If the server is available over all interfaces, then set this to 0.0.0.0.
rhq.autoinstall.database Sets how to handle any existing data in the JBoss ON database. The default is auto, which means that the installation process adds new schema but preserves any existing data. The other option is overwrite, which updates the schema and removes any existing data.
rhq.server.startup.web.http.port and rhq.server.startup.web.https.port Set the standard (HTTP) and secure (HTTPS) ports for the JBoss ON server. The default values are 7080 and 7443, respectively.
rhq.server.database.type-mapping Gives the type or vendor of the database that is used by the JBoss ON server. This is either PostgreSQL or Oracle10g (Oracle10g is used for both version 10 and version 11).
rhq.server.database.connection-url The JDBC URL that the JBoss ON server uses when connecting to the database. This has the format (roughly) of jdbc:db-type:hostname:port[:|/]db-name. An example is jdbc:postgresql://localhost:5432/rhq or jdbc:oracle:oci:@localhost:1521:orcl.
rhq.server.database.user-name The name of the user that the JBoss ON server uses when logging into the database. The default is rhqadmin.
rhq.server.database.password The password of the database user that is used by the JBoss ON server when logging into the database. This password is stored in a hash. The default password is rhqadmin. If a different password was created for the database user, then it should be encrypted using the serverRoot/jon-server-3.2.0.GA/bin/rhq-encode-password.sh script, and that encrypted value should be set in the rhq.server.database.password attribute.
rhq.server.database.server-name The server name where the database is found. This must match the server in the connection URL. This is currently only used when connecting to PostgreSQL.
rhq.server.database.port The port on which the database is listening. This must match the port in the connection URL. This is currently only used when connecting to PostgreSQL.
rhq.server.database.db-name The name of the database. This must match the name found in the connection URL. This is currently only used when connecting to PostgreSQL.
rhq.server.quartz.driverDelegateClass The Quartz driver used for connections between the server and the database. The value of this is set by the installer and depends on the type of database used to store the JBoss ON information. For PostgreSQL, this is org.quartz.impl.jdbcjobstore.PostgreSQLDelegate, and for Oracle, this is org.quartz.impl.jdbcjobstore.oracle.OracleDelegate.