Red Hat Training

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

2.3. Installing and Configuring the JBoss ON Server

The JBoss ON server binaries are installed simply by unzipping the packages. After that, then the specific server instance must be configured. This can be done through a simple, web-based installer or by editing the configuration file manually and configuring it silently.

2.3.1. Using the GUI Installer (Red Hat Enterprise Linux)

Note

See Chapter 5, Troubleshooting Installation and Upgrade if there are any problems during the install process.
  1. Stop any currently running JBoss ON instances. 
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh stop

    Warning

    If the new JBoss ON server will use a database that existing JBoss ON instances are also using, then all of the existing JBoss ON instances have to be stopped. Otherwise, the installer will hang when it tries to contact the database and the database is unavailable because it is in use by another JBoss ON server.
  2. Download the JBoss ON binaries from the Customer Support Portal.
    1. In the Customer Support Portal, click Software, and then select JBoss Operations Network in the product drop-down box.
    2. Download the JBoss Operations Network 3.0 Base Distribution package by clicking the Download icon.
    3. There are additional plug-in packs available for EAP, EDS, EWS, and SOA-P. If any of those plug-ins will be used with the JBoss ON server, then download them as well.
  3. Unzip the server distribution to the directory where will be executed from. 
    cd /opt

unzip jon-server-3.0.0.GA1.zip
    This creates a version-specific installation directory, /opt/jon-server-3.0.0.GA1. A directory with this name should not exist prior to the unzip operation.
  4. Install any additional agent plug-ins.
    Some JBoss applications (EWS, EDS, EAP, and SOA-P) have separate plug-ins, which are only available with special subscriptions. These agent plug-ins are part of JBoss ON can be be installed and enabled as part of the server installation process.

    Note

    Installing the EWS, EDS, EAP, or SOA-P plug-ins is not the same as deploying a custom agent plug-in or a server-side plug-in. Deploying custom plug-ins is done after JBoss ON server installation and is described in the Basic Admin Guide.
    1. Unzip the additional plug-in packs that were downloaded from the Customer Support Portal in step 2. 
      unzip jon-plugin-pack-agent_plugin_name-3.0.0.GA1.zip -d /opt/jon/jon-server-3.0.0.GA1/
      This creates a subdirectory with the name jon-plugin-pack-plugin_name-3.0.0.GA1/.
    2. List the current contents of the JBoss ON server plug-in directory. 
      ls -l  serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/deploy/rhq.ear.rej/rhq-downloads/rhq-plugins
    3. Copy the new plug-ins from the jon-plugin-pack-plugin_name-3.0.0.GA1/ directory to the JBoss ON server plug-in directory. 
      cp /opt/jon/jon-server-3.0.0.GA1/jon-plugin-pack-plugin_name-3.0.0.GA1/* serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/deploy/rhq.ear.rej/rhq-downloads/rhq-plugins
  5. Run the JBoss ON server: 
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh start
  6. Open the server UI at http://localhost:7080/.
  7. Clicking the Click here to continue the installation link brings you to the main installer page.
  8. By default, the installer displays only the typical settings required for installation. For more custom environments, click the Show Advanced Settings check box to display the advanced settings in the next two sections.

    Important

    Do not unselect the advanced settings checkbox after setting advanced values, or the advanced settings will be reset to the default values.
  9. Set the database connection properties.
    The installation options are slightly different depending on the database configuration.

    Important

    With Oracle, selecting the overwrite tables option when there is nothing to overwrite causes an error message with ErrorCode=[2289]. This can be ignored.
  10. Set the basic connection information for the new JBoss ON server, such as its HTTP and HTTP ports.
  11. Set preliminary notification information for the JBoss ON server for alerts to use for SNMP and email notifications.
  12. Click the INSTALL button to begin configuring the server. This can take several minutes, and a loading screen will be up until the server is configured and a redirect is available.
  13. When the server is configured, click the link to go to the UI.
  14. Log into the GUI using the user account with the default superuser and password, rhqadmin/rhqadmin. The default username and password are predefined for the superuser; the password can be reset later.

    Note

    Change the password for the superuser account, rhqadmin, when you first log in. Passwords are changed in the Administration > Users area.

2.3.2. Using the GUI Installer (Windows)

Note

See Chapter 5, Troubleshooting Installation and Upgrade if there are any problems during the install process.
  1. Log into the Windows machine as Administrator. The server and plug-in packages must be installed as the Administrator account.
  2. Stop any currently running JBoss ON instances. 
    C:\rhq\jon-server-3.0.0.GA1\bin\rhq-server.bat stop

    Warning

    If the new JBoss ON server will use a database that existing JBoss ON instances are also using, then all of the existing JBoss ON instances have to be stopped. Otherwise, the installer will hang when it tries to contact the database and the database is unavailable because it is in use by another JBoss ON server.
  3. Download the JBoss ON binaries from the Customer Support Portal.
    1. In the Customer Support Portal, click Software, and then click the Product drop-down box arrow to open the JBoss Operations Network software download.
    2. Download the JBoss Operations Network 3.0 Base Distribution package by clicking the Download icon.
    3. There are additional plug-in packs available for EAP, EDS, EWS, and SOA-P. If any of those plug-ins will be used with the JBoss ON server, then download them as well.
  4. Create a directory for the server to be installed in. 
    mkdir C:\rhq

    Important

    Do not install the server in a directory with a path longer than 19 characters. Long path names can cause problems with executing some server tasks. Use a location such as C:\rhq rather than C:\Documents and Settings\myusername.
  5. Unzip the server distribution in the directory where will be executed from. For example, using 7-Zip: 
    cd C:\rhq

7z e jon-server-3.0.0.GA1.zip
    This creates a version-specific installation directory, such as C:\rhq\jon-server-3.0.0.GA1. A directory with this name should not exist prior to the unzip operation.
  6. Install any additional agent plug-ins.
    Some JBoss applications (EWS, EDS, EAP, and SOA-P) have separate plug-ins, which are only available with special subscriptions. These agent plug-ins are part of JBoss ON can be be installed and enabled as part of the server installation process.

    Note

    Installing the EWS, EDS, EAP, or SOA-P plug-ins is not the same as deploying a custom agent plug-in or a server-side plug-in. Deploying custom plug-ins is done after JBoss ON server installation and is described in the Basic Admin Guide.
    1. Unzip the additional plug-in packs that were downloaded from the Customer Support Portal in step 3. This creates a subdirectory with the name jon-plugin-pack-plugin_name-3.0.0.GA1. 
      cd C:\rhq

7z e  jon-plugin-pack-agent_plugin_name-3.0.0.GA1.zip
    2. Copy the new plug-ins from the jon-plugin-pack-plugin_name-3.0.0.GA1 directory to the JBoss ON server plug-in directory.
  7. Set the directory path to the JRE or JDK installation. For example: 
    set RHQ_SERVER_JAVA_HOME=C:\Program Files\Java\jdk1.6.0_29
  8. Install the JBoss ON server as a Windows service. This action must be "Run as Administrator." 
    C:\rhq\jon-server-3.0.0.GA1\bin\rhq-server.bat install
  9. Start the JBoss ON server. This action must be "Run as Administrator." 
    C:\rhq\jon-server-3.0.0.GA1\bin\rhq-server.bat start
  10. Open the server UI at http://localhost:7080/.
  11. Complete steps 6 to 14 in Section 2.3.1, “Using the GUI Installer (Red Hat Enterprise Linux)”.

2.3.3. Silently Installing the JBoss ON Server

The initial setup of the server is the same as in Section 2.3.1, “Using the GUI Installer (Red Hat Enterprise Linux)”. Instead of using the visual, web-based installer, however, a silent installation loads a pre-configured properties file and starts the server with all of its configuration in place.

Note

This procedure uses command examples for Red Hat Enterprise Linux. If you are installing the server on a Windows server, then adapt the commands accordingly.
  1. Stop any currently running JBoss ON instances. 
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh stop

    Warning

    If the new JBoss ON server will use a database that existing JBoss ON instances are also using, then all of the existing JBoss ON instances have to be stopped. Otherwise, the installer will hang when it tries to contact the database and the database is unavailable because it is in use by another JBoss ON server.
  2. Download the JBoss ON binaries from the Customer Support Portal.
    1. In the Customer Support Portal, click Software, and then click the Product drop-down box arrow to open the JBoss Operations Network software download.
    2. Download the JBoss Operations Network 3.0 Base Distribution package by clicking the Download icon.
    3. There are additional plug-in packs available for EDS, EAP, EWS, and SOA-P. If any of those plug-ins will be used with the JBoss ON server, then download them as well.
  3. Unzip the server distribution to the directory from where it will be executed. For example, on Red Hat Enterprise Linux: 
    cd /opt

unzip jon-server-3.0.0.GA1.zip
    On Windows, using 7-Zip: 
    cd C:\rhq

7z e jon-server-3.0.0.GA1.zip
    On Windows systems, create or select a directory with a relatively short name. Path names longer than 19 characters can cause problems with executing some server tasks. Use a location such as C:\rhq rather than C:\Documents and Settings\myusername.
  4. Install the agent plug-ins. On Red Hat Enterprise Linux: 
    cd /opt/jon/jon-server-3.0.0.GA1

unzip jon-plugin-pack-agent_plugin_name-3.0.0.GA1.zip
    On Windows: 
    cd C:\rhq

7z e  jon-plugin-pack-agent_plugin_name-3.0.0.GA1.zip
  5. Open the JBoss ON server configuration properties file: 
    vim serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.properties
  6. Set the rhq.autoinstall.enabled parameter to true to instruct the server to load the configuration automatically from file. 
    rhq.autoinstall.enabled=true
  7. Set the parameter to tell the server whether preserve the any existing data in the database. For a new installation, this can be set to auto so the installer will supply the database schema. 
    rhq.autoinstall.database=auto
  8. Optionally, set the IP address or hostname for the server. If this is not set, then the server will detect it when it starts. 
    rhq.autoinstall.public-endpoint-address=server1.example.com
  9. Set the port numbers for the instance. 
    rhq.server.startup.web.http.port=7080
rhq.server.startup.web.https.port=7443
  10. Set the username and password to connect to the backend database. The password is stored in the properties file in an encoded form. Use the generate-db-password.sh script to hash the password. 
    serverRoot/jon-server-3.0.0.GA1/bin/generate-db-password.sh mypassword
Encoded password: 1d31b70b3650168f79edee9e04977e34
    Then, set the hashed password as the rhq.server.database.password value. 
    rhq.server.database.user-name=rhqadmin
rhq.server.database.password=1d31b70b3650168f79edee9e04977e34
  11. Scan the rest of the database configuration to make sure that it corresponds to your specific database type and instance. The parameters, and some possible values for PostgreSQL and Oracle databases, are described in Table 2.2, “rhq-server.properties Parameters for Database Configuration”. 
    # Database
rhq.server.database.connection-url=jdbc:postgresql://127.0.0.1:5432/rhq
rhq.server.database.driver-class=org.postgresql.Driver
rhq.server.database.xa-datasource-class=org.postgresql.xa.PGXADataSource
rhq.server.database.type-mapping=PostgreSQL
rhq.server.database.server-name=127.0.0.1
rhq.server.database.port=5432
rhq.server.database.db-name=rhq
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# Quartz
rhq.server.quartz.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
rhq.server.quartz.selectWithLockSQL=SELECT * FROM {0}LOCKS ROWLOCK WHERE LOCK_NAME = ? FOR UPDATE
rhq.server.quartz.lockHandlerClass=org.quartz.impl.jdbcjobstore.StdRowLockSemaphore
  12. Start the JBoss ON server: 
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh start
When the server starts, it loads the edited rhq-server.properties file and is fully configured.

Table 2.2. rhq-server.properties Parameters for Database Configuration

Parameter Description
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 Oracle.
rhq.server.database.connection-url The JDBC URL that the JBoss ON server uses when connecting to the database. An example is jdbc:postgresql://localhost:5432/rhq or jdbc:oracle:oci:@localhost:1521:orcl.
rhq.server.database.driver-class The fully qualified class name of the JDBC driver that the JBoss ON server uses to communicate with the database. An example is oracle.jdbc.driver.OracleDriver.
rhq.server.database.xa-datasource-class The fully qualified class name of the JDBC driver that the JBoss ON server uses to communicate with the database. Examples of this are org.postgresql.xa.PGXADataSource or oracle.jdbc.xa.client.OracleXADatasource.
rhq.server.database.user-name The name of the user that the JBoss ON server uses when logging into the database
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.
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.