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.passwordusing the instructions in Section 3.6.2, “Attributes in the Properties File”.
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.
| 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). |
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'.NoteBecause 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.shscript, and update the encrypted password value in the rhq.server.database.password attribute.NoteTherhq-encode-password.shscript is deprecated, but remains in JBoss ON for backwards compatibility. It is recommended to discontinue use of the old script and begin usingserverRoot/jon-server-3.3.2.GA/bin/rhq-encode-value.shfor 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 isorg.quartz.impl.jdbcjobstore.oracle.OracleDelegate.
