Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

3.6. About the rhqctl Script

Red Hat 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 attribute to use the password set during Section 2.1.2, “Configuring PostgreSQL” for the PostgreSQL database user rhqadmin: 
rhq.server.database.password
using the instructions in Section 3.6.2, “Attributes in the Properties File”.
Report a bug

3.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 3.1. Installing with No Options

The simplest way to configure the server is to run the install command alone. 
jsmith@server bin]$ ./rhqctl install
06:21:40,773 INFO  [org.jboss.modules] JBoss Modules version 1.3.3.Final-redhat-1

The [rhq.autoinstall.server.admin.password] property is required but not set in [rhq-server.properties].
Do you want to set [rhq.autoinstall.server.admin.password] value now?
yes|no: yes
rhq.autoinstall.server.admin.password (enter as plain text): 
Confirm:
rhq.autoinstall.server.admin.password (enter as plain text): 

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 these processes must be started manually. 
[jsmith@server bin]# ./rhqctl start

Example 3.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. 
[jsmith@server bin]# ./rhqctl install --start

Example 3.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: 
[jsmith@server bin]# ./rhqctl install --storage --start
[jsmith@server bin]# ./rhqctl install --server --start
[jsmith@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 3.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.3.2.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).
Report a bug

3.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 below. 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.

rhq-server.properties Attributes for Server Configuration

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.
jboss.tx.node.id
This is high availability identifier for each JON Server instance. Must be unique, max 23 characters. Defaults to value '1'.
Note
Because each of the JBoss Operations Network servers in an HA configuration use the same database, they will each require a separate and unique node identifier for the purpose of managing their database transactions. However, the default JBoss Operations Network server configuration does not specify a node identifier value to be used for database transaction meaning that the underlying application server will use a default node identifier value of 1. This can result in transaction execution and recovery failures that seem sporadic and can result in extra load on the JBoss Operations Network server or the database it is using.
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.autoinstall.server.admin.password
Stores the encrypted server password, generated as a step of the rhqctl install command for new installations. The encrypted value can be manually generated using the rhq-encode-value.(bat|sh) script, and the value updated manually by the user.
rhq.server.startup.web.http.port , 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 Oracle database versions 10, 11, and 12).
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, encrypt the password using the serverRoot/jon-server-3.3.2.GA/bin/rhq-encode-value.sh script, and update the encrypted password value in the rhq.server.database.password attribute.
Note
The rhq-encode-password.sh script is deprecated, but remains in JBoss ON for backwards compatibility. It is recommended to discontinue use of the old script and begin using serverRoot/jon-server-3.3.2.GA/bin/rhq-encode-value.sh for password encryption.
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 installation program 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.
Report a bug