- Windows Installation Notes
- Avoid Long Path Issues When Unzipping
- Java Distribution
- Use Forward-Slash Paths
- RHQ runs as Windows Services
- Start the command window with Run as Administrator.
- Set the Desired Account for the Services
- Wrapper Configuration Files
- Removing a Service
- Browser support
- Windows FAQ
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.
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:
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.
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.
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
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:
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).
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 Storage Service
- RHQ_STORAGE_RUN_AS=.\<username> or RHQ_STORAGE_RUN_AS_ME=true
- RHQ Agent Service
- RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true
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.
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
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.
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.
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.
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.
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.
See RHQ Browsers for information on browser support, including IE versions.
More Windows related information may be contained in the RHQ FAQ.