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

Important

The agent does not prompt for the configuration when it is started as a service. The agent must either be pre-configured or have already been started once and the configuration entered. Both options are described in the Installation Guide.
The agent's configuration is determined by what user is running the agent. If the agent is run as one user and then later run as another user, the agent will have a different configuration that second time because it will use a different backing store for its configuration settings.
This means that if one user is used to configure the agent when it is installed, that same user must be used to run the agent subsequently, or the agent will apparently lose its configuration and need to be reconfigured under the new user.
The agent configuration backing store is described in Section 6.10, “Managing the Agent's Persisted Configuration”.
Once the agent is configured (or pre-configured), the agent can be started in two ways. The rhq-agent.sh script starts the agent and opens the command console. The rhq-agent-wrapper.sh script simply starts the agent daemon and exits. Both methods can have additional environment variables configured through the rhq-agent-env.sh script file.
The daemon can be started and run as a system service. On Red Hat Enterprise Linux, this is done by configuring /etc/init.d and then installing it using chkconfig. For Solaris and other Unix systems, this is done by configuring /etc/init.d and then using other system tools to set up the service.
  1. Make sure the agent is fully set up.
  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/bin/
    export RHQ_AGENT_JAVA_HOME=/usr
    PIDFILEDIR=/var/run

    Note

    When setting the PIDFILEDIR 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. 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.
  6. Make sure the wrapper script is executable.
    [root@server rhq-agent]# chmod a+x agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh
  7. Symlink the rhq-agent-wrapper.sh file to /etc/init.d/. For example:
    # 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.
  8. Register rhq-agent-wrapper.sh with chkconfig.
    # /sbin/chkconfig --add rhq-agent-wrapper.sh
  9. Enable the agent service to run at boot time and have it stop gracefully at when the system shuts down.
    # /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:
# /sbin/chkconfig rhq-agent-wrapper.sh off