Skip to end of metadata
Go to start of metadata

Windows Installation Notes

All RHQ components, Server, Storage Node and Agent, can be installed on the supported Windows platforms. To ensure a good experience there are several things to be aware of when running on Windows. Please read through this information before proceeding with your Windows install, or upgrade.

Avoid Long Path Issues When Unzipping

Windows has a limited length for file paths. Unzip into a relatively short parent directory, no more than 10-15 characters, It is recommended to install under an rhq umbrella directory. So, for example:

c:/rhq

See this Microsoft MSDN article for more information.

Some 3rd party tools, like 7-Zip can avoid the issue but using a short path is the recommended approach.

Java Distribution

A 64-Bit Java JRE or JDK is supported.

If using a 32-Bit distribution it must be a JDK (Server) distribution, not a JRE (Client) distribution. Because the 32-bit distributions still make distinction between server (JDK) and client (JRE) versions, and RHQ requires a server distribution, you must use a 32-bit JDK.

Use Forward-Slash Paths

When specifying Windows paths in .properties files, or in general as part of any RHQ configuration, Values are typically treated like Java strings:

  • Use forward slashes where possible, especially in directory or file paths. For example: C:/rhq
  • If you need an explicit backslash, escape it using a double-backslash. For example: set some.property.value=foo
    bar

RHQ runs as Windows Services

RHQ 4.9 introduced the rhqctl script to control the RHQ components. On Windows, the rhqctl.bat works analogously to rhqctl on UNIX-based platforms. However, on Windows the RHQ components are installed and managed as Windows services. There are some important notes regarding Windows Services:

Using rhqctl --agent-preference or --agent-configuration options
The Windows services run by default as the local system account (known as "Default" or ".\LocalSystem"). RHQ associates agent configuration preferences with users. Care must be taken to ensure that custom agent preferences actually get applied to the user running the RHQ Agent service. There are three options:
  1. Install using RHQ_AGENT_RUN_AS_ME (see below) and use --agent-preference
    • This will run the service as the same user executing rhqctl, so the command line --agent-preference settings will apply.
  2. Install using --agent-config <custom-agent-configuration.xml>
    • Without RHQ_AGENT_RUN_AS_ME the user executing rhqctl will be different that the user running the service. But with this option, RHQ will apply the custom configuration file on the initial start of the RHQ Agent.
  3. Update the RHQ Agent configuration post-install
    • Without RHQ_AGENT_RUN_AS_ME the user executing rhqctl will be different that the user running the service. Without --agent-config the installed agent will have default configuration. After installation the agent config can be updated using the agent prompt commands (or direct manipulation of the registry - not recommended).

Start the command window with Run as Administrator.

Start the command window with "Run as Administrator". This is required for manipulating Windows services (just as has been required in the past when running the RHQ Server and RHQ Agent as a service).

Set the Desired Account for the Services

The Windows services run by default as the local system account (known as "Default" or ".\LocalSystem"). To install the services as a different user set the following environment variables in rhq-server-env.bat, prior to installation or upgrade:

  • The desired user account must have "log on as service" permission. On some Windows configurations this may need to be granted explicitly.
  • RHQ Server Service
    • RHQ_SERVER_RUN_AS=.\<username> or RHQ_SERVER_RUN_AS_ME=true
    • RHQ_SERVER_PASSWORD=<password>
  • RHQ Storage Service
    • RHQ_STORAGE_RUN_AS=.\<username> or RHQ_STORAGE_RUN_AS_ME=true
    • RHQ_STORAGE_PASSWORD=<password>
  • RHQ Agent Service
    • RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true
    • RHQ_AGENT_PASSWORD=<password>
Upgrade Note
When upgrading from a version prior to those using rhqctl for installation it is possible that the RHQ_XXX_RUN_AS feature was used without also setting the RHQ_XXX_PASSWORD environment variable. It is now required to set RHQ_XXX_PASSWORD when using RHQ_XXX_RUN_AS.
Agent Only Install
This page is targeted to installs of the RHQ Server, Storage Node and Agent using rhqctl. For standalone agent installations see RHQ Agent Installation.
Running the Agent from the Command Line

In general it is recommended to just run the agent as a Windows service. But if you plan to stop the service and run the agent interactively (typically this is done for development or debugging purposes) it is recommended not to install the agent service with the local system account. It will be necessary to run the agent as the same user both as the service and interactively to ensure the same agent configuration is applied in both scenarios. The agent service can be installed to run as a different user by setting the following environment variables before running "rhqctl install":

  • RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true
  • RHQ_AGENT_PASSWORD=<password>
The location of java.io.tmpdir

The RHQ Server and RHQ Agent make use of the temporary directory set as java.io.tmpdir. On Windows this is typically located under %USERPROFILE%/AppData/Local/Temp. This directory must exist and be accessible to the user account running the RHQ components, typically the account assigned to running the services, or at times, the account running the component in a console.

If the directory is not accessible RHQ will log a warning and then attempt to create and use <InstallDir>/temp.

Using the Default Local System Account and 32-bit Java
When using a 32-bit Java distribution, and the default Local System account to run the RHQ Windows service, the java.io.tmpdir account will not be accessible. This is a known Windows issue and not due to RHQ. In this case RHQ will create its own temp directory as described above. To avoid this do not use the default Local System account, or install a 64-bit version of the Java Service Wrapper (not provided with RHQ), or override the setting of java.io.tmpdir.
Overriding java.io.tmpdir

To use a non-default temp directory for an RHQ component on Windows edit the Java Service Wrapper include file. See Overriding Properties in the Java Service Wrapper for details. For example, for the RHQ Server this would be <InstallDir>/bin/wrapper/rhq-server-wrapper.inc. Follow the inline instructions for setting java.io.tmpdir, or any other Java property that you may want to set.

  • Note that to update the wrapper configuration you should first install the RHQ Agent, then edit the configuration, then start the RHQ Agent.
  • Note that at this writing the RHQ Storage Node does not utilize java.io.tmpdir.

Wrapper Configuration Files

Once installed the RHQ Windows service is configured by the service wrapper configuration file, located at <install-dir>\bin\wrapper\rhq-xxx-wrapper.conf. This file sets some of the Java Service Wrapper configuration settings. Before editing this file, refer to the Java Service Wrapper's property configuration documentation located at http://wrapper.tanukisoftware.org/doc/english/properties.html. Editing this file is not usually necessary. More common will be adding or overriding properties in <install-dir>\bin\wrapper\rhq-xxx-wrapper.conf.

Overriding Properties in the Java Service Wrapper

RHQ Windows services are configured via the service wrapper configuration files found in bin/wrapper. The standard settings are in the rhq-xxx-wrapper.conf file. That file can be edited but the recommended approach is to override and add properties in the rhq-xxx-wrapper.inc file. To override or add properties follow the inline instructions for adding "wrapper.java.additional.N" lines. For example:

Make sure the numbering is correct. The first property in the .inc file must increment from the last property in the .conf file.

Removing a Service

To remove services use rhqctl. For example: "rhqctl remove". Note that removing Windows services does not uninstall the RHQ component. In general it should not be necessary to remove the Windows services but if done the "rhqctl install" command will recreate the service even if the component is already installed.

Browser support

See RHQ Browsers for information on browser support, including IE versions.

Windows FAQ

More Windows related information may be contained in the RHQ FAQ.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.