wrapper.app.parameter.3=--config wrapper.app.parameter.4=C:\my-configs\my-agent-config.xml
The RHQ Agent is a standalone Java application. This page will talk about the different ways you can run the RHQ Agent. Note that if you run the agent in a foreground console window, you can interact with the agent from the console through its prompt commands.
Running In Debug Mode
Sometimes you need the agent launcher scripts (i.e. rhq-agent-wrapper.sh/.bat, rhq-agent.sh/.bat) and the RHQ Agent itself to emit debug messages. To run the scripts and the RHQ Agent in debug mode, define the environment variable RHQ_AGENT_DEBUG to 'true'. To disable this debug mode, unset that environment variable, or set it to 'false'. There is an agent prompt command that lets you enable and disable debug mode while the agent is running; type "help debug" at the agent prompt for more information.
The RHQ Agent can be run from within a console window or it can be installed as a Windows Service and run as a service.
The rhq-agent-env.bat file, located in the <agent-install-dir>/bin/ directory, contains a detailed list of the environment variables that the RHQ Agent requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important however, to set the correct path to your Java installation. Before starting the RHQ Agent, it is best to ensure that either the RHQ_AGENT_JAVA_HOME or the RHQ_AGENT_JAVA_EXE_FILE_PATH variable is set appropriately.
You should not edit rhq-agent.bat or rhq-agent-wrapper.bat - if you need to customize the launch parameters of the RHQ Agent, edit the environment variable values in rhq-agent-env.bat. Doing otherwise may affect the ability of your agent to auto-update itself in the future.
Some of these settings are ignored when running the RHQ Agent as a Windows Service. Please read the comments at the top of rhq-agent-env.bat to know which variables can be set depending on which mode of operation you are using.
To run the RHQ Agent in a console, execute the rhq-agent.bat script found in the rhq-agent\bin directory of the distribution. You can pass in any of the command line options that are described in RHQ Agent Command Line Options.
The rhq-agent.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the RHQ Agent at a new JVM or you can define VM options. Note that you must not edit the rhq-agent.bat file (doing so may affect your ability to auto-update the agent in the future). If you need to customize the launch parameters of the RHQ Agent, either set the environment variables at the command prompt, or edit the values in rhq-agent-env.bat. The comments at the top of the rhq-agent-env.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the RHQ Agent to run; sensible defaults are used.
The agent will not ask for the configuration when installing as a Windows service. This means that you need to either pre-configure the agent (which means you pass all required information to the agent via the agent's configuration file), or you must run the agent in standard (non-service) mode once as the user the service will run as in order to answer all the setup questions prior to installing it as service.
If you wish to run the RHQ Agent at boot time, you can install the RHQ Agent as a Windows Service. To do so, you use the rhq-agent-wrapper.bat file. This script file accepts any of the following command line options:
install - this will install the RHQ Agent as a Windows Service. When you do this, you will be prompted for the password of the user that the service will run as. Information on how to define what user the service will run as is outlined below. The Windows Service will be installed to automatically start at boot time. You can change this behavior by modifying the wrapper configuration file as described below.
start - this will start the Windows Service, effectively starting the RHQ Agent. You must have installed the Windows Service first in order to be able to start it using this mechanism. Note that you can also start the RHQ Agent by using the Windows Services Administrative Tool instead.
stop - this will stop the Windows Service, effectively stopping the RHQ Agent. You need to have the Windows Service installed and started to stop it using this mechanism. Note that you can also stop the RHQ Agent by using the Windows Services Administrative Tool instead.
remove - this will remove the Windows Service from your Windows operating system. If the service was running, it will first be stopped. Once the service is removed, it will no longer be started at boot time and you can no longer start it with this wrapper script (unless you re-install it using the "install" command line option as described above).
status - this simply tells you if the service is installed or not; if it is installed, it will tell you if it is currently running or not.
Two environment variables need to be explicitly mentioned here since they are important and have security implications.
RHQ_AGENT_RUN_AS - if this variable is set, its value will be the domain\username of the user account that the RHQ Agent Windows Service will be run as. The format of this variable's value must match that which Windows expects for a user account - specifically the Windows domain name followed by a backslash followed by the username. An example would be MYDOMAIN\john. This variable is used when you install the service via rhq-agent-wrapper.bat install.
RHQ_AGENT_RUN_AS_ME - if this variable is defined, it forces the user account to be that of the current user (specifically ".\ %USERNAME%)". The variable's value does not have to be anything in particular; as long as it is defined to something, it will take effect. If this
variable is defined, it will override the RHQ_AGENT_RUN_AS environment variable. This variable is used when you install the service via rhq-agent-wrapper.bat install.
Refer to the comments at the top of the rhq-agent-env.bat script file for the full list of variables you can set when using the rhq-agent-wrapper.bat script and the documentation on what they control.
If you do not pass the agent a file containing its required configuration then you must specify one of the two environment variables mentioned above in order for the agent to properly initialize itself. If you specify RHQ_AGENT_RUN_AS_ME then you must have previously run the agent at least once in standard (interactive) mode as the current user before installing it as a service.
If you specify RHQ_AGENT_RUN_AS then you must have previously run the agent at least once in standard (interactive) mode as the user specified by RHQ_AGENT_RUN_AS before installing it as a service. If neither of the above two environment variables are set, the RHQ Agent Windows Service will run as the System account. In this scenario the information the agent needs must be specified in its configuration file.
If you specify either RHQ_AGENT_RUN_AS_ME or RHQ_AGENT_RUN_AS then you need to ensure that the selected user can actually start services in Windows. If you find that your selected user cannot do this, you can fix this on most Windows systems by going to the Administrative Tools folder in your control panel, open "Local Security Policy", expand "Local Policies" and then click on "User Rights Assignment". On the right side of your page, there is a "Log on as a service" policy where you can add the selected user.
In addition to setting the wrapper script file's environment variables, you can also further configure the RHQ Agent Windows Service by modifying the service wrapper configuration file - this file is located in the agent's distribution, specifically at bin\wrapper\rhq-agent-wrapper.conf. This configuration file sets some Java Service Wrapper configuration items (Java Service Wrapper is the utility that rhq-agent-wrapper.bat script uses to install and control the Windows Service). If you wish to add, remove or modify some wrapper.* settings, it is recommended that you read the Java Service Wrapper's configuration properties documentation. A few common settings you might be interested in modifying are:
wrapper.app.parameter.# - these are command line options you can pass to the RHQ Agent itself. Note that each individual option and their values must be given their own wrapper configuration property and each property must be placed in numerical order. You cannot change the wrapper.app.parameter.1 or wrapper.app.parameter.2 properties - start with wrapper.app.parameter.3 and increment up from there. The option numbers must be contiguous and not skip numbers! Example:
wrapper.app.parameter.3=--config wrapper.app.parameter.4=C:\my-configs\my-agent-config.xml
wrapper.java.additional.# - these are additional VM options you can pass directly to the VM (such as -Xmx or -D). As with the wrapper.app.parameter.# properties, you must increment each option in numerical order. You should leave wrapper.java.additional.1 alone unless you want to point to your own log configuration file. You can add, remove or modify others, but make sure you know what you are doing. Example:
wrapper.java.additional.2=-Xms256m wrapper.java.additional.3=-Xmx800m wrapper.java.additional.4=-XX:+DisableExplicitGC wrapper.java.additional.5="-Djava.endorsed.dirs=%RHQ_AGENT_HOME%/lib/endorsed"
wrapper.ntservice.starttype - by default, this is set to AUTO_START, meaning the RHQ Agent's service will be started automatically at boot time. If you prefer to force a manual start of the service, you can set this to DEMAND_START.
There are many other Java Service Wrapper configuration properties you can set. If you are interested in learning more, refer to the Java Service Wrapper documentation at http://wrapper.tanukisoftware.org/doc/english/properties.html. Also refer to the comments located in the rhq-agent-wrapper.conf file. You can also configure the RHQ Server Windows Service by creating a bin\wrapper\rhq-server-wrapper.inc include file. This effectively augments the service wrapper configuration file, agent-install-dir\bin\wrapper\rhq-server-wrapper.conf. If you want to add additional Java VM options, we recommend that you add your settings in the .inc, as opposed to the rhq-server-wrapper.conf file (doing otherwise may affect the ability of your agent to successfully auto-update itself in the future).
When running the RHQ Agent as a Windows Service, many settings are only configurable via the rhq-server-wrapper.conf file, and not the rhq-agent-env.bat. Because Java Service Wrapper is involved, it sets up the RHQ Agent environment, not the rhq-agent-env.bat file, hence you must configure the RHQ Agent environment using the Java Service Wrapper mechanism.
The RHQ Agent can be run directly from a console window or it can be installed as an init.d process such that it starts up when the computer boots up.
The rhq-agent-env.sh file, located in the <agent-install-dir>/bin/ directory, contains a detailed list of the environment variables that the RHQ Agent requires to run. Read the comments at the top of rhq-agent-env.sh for a full description of the environment variables. For most variables, sensible defaults are used and therefore do not need editing. It is important however, to set the correct path to your Java installation. Before starting the RHQ Agent, it is best to ensure that either the RHQ_AGENT_JAVA_HOME or the RHQ_AGENT_JAVA_EXE_FILE_PATH variable is set appropriately.
You should not edit rhq-agent.sh or rhq-agent-wrapper.sh - if you need to customize the launch parameters of the RHQ Agent, edit the environment variable values in rhq-agent-env.sh. Doing otherwise may affect the ability of your agent to auto-update itself in the future.
If your RHQ Agent will be managing a large amount of resources, it may be necessary to increase the memory allocated to the agent's Java Virtual Machine. You can do this by overriding the RHQ_AGENT_JAVA_OPTS environment variable. RHQ_AGENT_JAVA_OPTS, if not defined, will default to "-Xms64m -Xmx128m -Djava.net.preferIPv4Stack=true" meaning the Java VM heap space will have a maximum of 128MB. This is usually enough for most applications, but if you find the agent runs out of memory, set this variable in rhq-agent-env.sh so it overrides your memory settings, e.g.
RHQ_AGENT_JAVA_OPTS="-Xms1024M -Xmx1024M -XX:PermSize=256M -XX:MaxPermSize=256M -Djava.net.preferIPv4Stack=true"
When you restart your agent, it will be allocated 1024MB of heap space and allocated 256MB of PermGen non-heap space.
To run the RHQ Agent in a shell (i.e. console window), run the rhq-agent.sh script found in the /bin directory of the agent distribution. You can pass in any of the RHQ Agent Command Line Options.
The RHQ Agent script rhq-agent-wrapper.sh located in the /bin directory can be used to run the agent as a daemon. There are two distinct scenarios in which you can run the agent as a daemon:
If you previously ran the agent in a console: Assuming you run rhq-agent-wrapper.sh as the same user you initially ran the agent as, then all you should have to do is to execute rhq-agent-wrapper.sh start and the agent will start up in daemon mode.
If you have never previously run the agent: In this case you need to preconfigure the agent before running the agent as a daemon for the first time. This is necessary because you will not be able to answer the questions the agent asks when it first starts up, so the answers to those setup questions need to already be preconfigured in the agent configuration file. Assuming the agent is preconfigured, you can start the agent by executing rhq-agent-wrapper.sh start which starts the agent up in daemon mode.
For Solaris Admins: Symbolically linking the agent scripts require invocation of readlink in rhq-agent-wrapper.sh. However, readlink is not supplied by default in some Solaris installations. Solaris users must either download readlink from a third party provider, such as Sunfreeware, or refrain from symbolically linking the agent scripts when using the wrapper script. Note that if you do not use symbolic links, the agent will not be able to auto-update the script if it needs to do so in the future.
Unlike the Windows script, this UNIX script does not utilize the Java Service Wrapper utility.
To ensure the RHQ Agent is started at boot time, the rhq-agent-wrapper.sh script can be managed by the init process.
The script must be symbolically linked to the appropriate location and rhq-agent-env.sh must set the RHQ_SERVER_HOME variable to the installation directory of the RHQ Agent. Using symbolic links will enable the agent to auto-update the launcher script, should it need to do so in the future.
For Solaris Admins: Symbolically linking the agent scripts require invocation of readlink in rhq-agent-wrapper.sh. However, readlink is not supplied by default in some Solaris installations. Solaris users must either download readlink from a third party provider, such as Sunfreeware, or refrain from symbolically linking the agent scripts when using the wrapper script. Note that if you do not use symbolic links, the agent will not be able to auto-update the script if it needs to do so in the future.
Unlike the Windows script, this UNIX script does not utilize the Java Service Wrapper utility.
The exact procedure on how to set this up this varies between different flavors of UNIX. The example procedure below describes this process on Red Hat Enterprise Linux 5.2. Please consult your system administrator for instructions on how to install and configure the Agent init script with your init system.
The rhq-agent-wrapper script contains standard chkconfig options that can be used by the chkconfig init script management system. You will need to be root or have sudo root access to perform these steps.
Symlink your rhq-agent-wrapper.sh file to /etc/init.d/. Example command:
ln -s <agent-install-dir>/bin/rhq-agent-wrapper.sh /etc/init.d/rhq-agent-wrapper.sh
Register rhq-agent-wrapper.sh with the chkconfig system by entering the following command:
/sbin/chkconfig --add rhq-agent-wrapper.sh
Enable the Agent service at boot time and have it stop gracefully at shutdown/reboot by entering the following command:
/sbin/chkconfig rhq-agent-wrapper.sh on
If you need to disable the Agent boot-time service enter the following command:
/sbin/chkconfig rhq-agent-wrapper.sh off
You have the option of running the RHQ Agent directly embedded within the RHQ Server. This means the RHQ Server VM will actually host a running RHQ Agent inside of it. For more information on this feature, please see Running the RHQ Server#Running the Embedded Agent in the RHQ Server.
Use the embedded agent for demo/testing purposes only. It is not recommended to use it in a production environment.
Out-of-box, RHQ comes with a plugin that lets you manage the agent itself. If you so choose, you can use this plugin to import your agent into inventory and then use the normal RHQ Server GUI to monitor and control the RHQ Agent, just as if it were any other managed resource in your inventory. See Using the Agent Plugin for more information.