Menu Close

Red Hat Training

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

6.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.

6.4.1. Running the Agent as a Windows 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. 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.
    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.

6.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 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).
    export RHQ_JAVA_HOME=/usr
    When setting the RHQ_AGENT_PIDFILE_DIR on Red Hat Enterprise Linux, edit the pidfile setting in the 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 6.4.3, “Starting an Agent with a Custom Command”.
  6. Log into the system as root.
    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.
    [jsmith@server rhq-agent]$ chmod a+x agentRoot/rhq-agent/bin/
  8. Symlink the file to /etc/init.d/. For example:
    [jsmith@server rhq-agent]$ ln -s agentRoot/rhq-agent/bin/ /etc/init.d/
    On Solaris, symlinking the agent script file requires invoking readlink in readlink is not supplied by default in some Solaris installations. Solaris users must download readlink from a source such as Sunfreeware.
  9. Register with chkconfig.
    [root@server rhq-agent] # /sbin/chkconfig --add
  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 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 off

6.4.3. Starting an Agent with a Custom Command

When configuring the agent to run as a service in Section 6.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 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/'"
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.