Red Hat Training

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

4.4. Running the JBoss ON Agent as a Service

In almost all production environments, the agent should be started as a background daemon process. On Windows, this runs as a service. On Linux and Unix systems, the agent starts at boot time from init.d.
More detail on editing the agent server wrapper script and managing the agent daemon is covered in the Administration and Configuration Guide guide.

4.4.1. Running the Agent as a Windows Service

The default Java service wrapper included with JBoss ON requires a 32-bit JVM, so the Java preference set for the agent must be a 32-bit JRE. The JBoss ON agent must use a 32-bit JVM even on 64-bit systems.
Running the agent with a 32-bit JVM does not in any way affect how JBoss ON manages other resources which may run with a 64-bit JVM. JBoss ON can still manage those resources and those resources can still use the 64-bit Java libraries for their own processes.
  1. Make sure the agent is fully set up. The agent does not prompt for the configuration when it is started as a service.
  2. Edit the rhq-agent-env.bat script and set the environment variable to define the system user as whom the init script will run. There are two options:
    • RHQ_AGENT_RUN_AS explicitly sets the user account name. This must match the format of a Windows user account name, DOMAIN\username.
    • RHQ_AGENT_RUN_AS_ME forces the agent to run as whoever the current user is; this uses the format . \ %USERNAME %. If both environment variables are defined, this variable overrides RHQ_AGENT_RUN_AS.

    Note

    Before setting RHQ_AGENT_RUN_AS_ME or RHQ_AGENT_RUN_AS, make sure that the given user actually has permission to start services. If necessary, assign the user the appropriate rights. Assigning rights is covered in the Windows documentation.
    If neither variable is set, the agent init script runs as the local system account (Default or .\LocalSystem).
    Other available environment variables are listed and defined in the comments in the rhq-agent-wrapper.bat script.
  3. Run the rhq-agent-wrapper.bat script to install the init script as a service. Use the install command to install the init script.
  4. When prompted, fill in the password for the system user as whom the service will run.

4.4.2. Running the Agent as a Daemon or init.d Service

  1. Make sure the agent is fully set up. The agent does not prompt for the configuration when it is started as a service.
  2. Open the rhq-agent-env.sh file.
  3. Uncomment and configure the required environment variables for the agent's bin directory, the JDK directory, and the PID directory (which must be writable by the agent user). 
    RHQ_AGENT_HOME=agentRoot/rhq-agent/
export RHQ_JAVA_HOME=/usr
RHQ_AGENT_PIDFILE_DIR=/var/run

    Note

    When setting the RHQ_AGENT_PIDFILE_DIR on Red Hat Enterprise Linux, edit the pidfile setting in the rhq-agent-wrapper.sh script file. The wrapper script value is used by chkconfig.
  4. Set any of the optional environment variables.
    • RHQ_AGENT_DEBUG enables debug logging.
    • RHQ_AGENT_JAVA_EXE_FILE_PATH specifies a Java executable.
    • RHQ_AGENT_JAVA_OPTS passes settings to the agent JVM.
    • RHQ_AGENT_ADDITIONAL_JAVA_OPTS passes additional Java options to the JVM.
  5. Optional. Configure any custom start commands, as in Section 4.4.3, “Starting an Agent with a Custom Command”.
  6. Log into the system as root.

    Important

    The rest of this procedure describes how to configure the agent init script as a service on Red Hat Enterprise Linux. For other Unix systems, follow a similar procedure that corresponds to the specific platform.
  7. Make sure the wrapper script is executable. 
    [root@server rhq-agent]# chmod a+x agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh
  8. Symlink the rhq-agent-wrapper.sh file to /etc/init.d/. For example: 
    [root@server rhq-agent]# ln -s agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh /etc/init.d/rhq-agent-wrapper.sh

    Important

    On Solaris, symlinking the agent script file requires invoking readlink in rhq-agent-wrapper.sh. readlink is not supplied by default in some Solaris installations. Solaris users must download readlink from a source such as Sunfreeware.
  9. Register rhq-agent-wrapper.sh with chkconfig. 
    [root@server rhq-agent] # /sbin/chkconfig --add rhq-agent-wrapper.sh
  10. Enable the agent service to run at boot time and have it stop gracefully at when the system shuts down. 
    [root@server rhq-agent] # /sbin/chkconfig rhq-agent-wrapper.sh on
If the agent service should not be started when the system boots, turn the script off in chkconfig: 
[root@server rhq-agent] # /sbin/chkconfig rhq-agent-wrapper.sh off

4.4.3. Starting an Agent with a Custom Command

When configuring the agent to run as a service in Section 4.4.2, “Running the Agent as a Daemon or init.d Service”, the agent can be configured to start with a custom start command. This is used mainly to start the agent using su or sudo, allowing the agent to run as a different user.
The start command is defined with the other agent properties in the rhq-agent-env.sh file. There are two parts to the configuration: the start command itself and then a setting to enable a password prompt. 
RHQ_AGENT_START_COMMAND="su -m test -c '${RHQ_AGENT_HOME}/bin/rhq-agent.sh'"
RHQ_AGENT_PASSWORD_PROMPT=true
Setting a start command overrides whatever command is passed in the command line to start the agent.
The password prompt may not be required; it depends on the sudo and agent user configuration. If it is required, then the password prompt should be enabled so that the user can enter the password or a password should be set in the RHQ_AGENT_PASSWORD parameter; otherwise, the start process will appear to hang.
If the defined start command is invalid, then the agent can fail to start. Along with the command formatting, the directory name can be affected; if there are spaces or special characters in the name, those must be escaped for the command to run.