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
- Make sure the agent is fully set up. The agent does not prompt for the configuration when it is started as a service.
- 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 overridesRHQ_AGENT_RUN_AS
.
NoteBefore settingRHQ_AGENT_RUN_AS_ME
orRHQ_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 therhq-agent-wrapper.bat
script. - Run the
rhq-agent-wrapper.bat
script to install the init script as a service. Use the install command to install the init script. - 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
- Make sure the agent is fully set up. The agent does not prompt for the configuration when it is started as a service.
- Open the
rhq-agent-env.sh
file. - 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
NoteWhen setting theRHQ_AGENT_PIDFILE_DIR
on Red Hat Enterprise Linux, edit thepidfile
setting in therhq-agent-wrapper.sh
script file. The wrapper script value is used by chkconfig. - 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.
- Optional. Configure any custom start commands, as in Section 6.4.3, “Starting an Agent with a Custom Command”.
- Log into the system as root.ImportantThe 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.
- Make sure the wrapper script is executable.
[jsmith@server rhq-agent]$ chmod a+x agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh
- Symlink the
rhq-agent-wrapper.sh
file to/etc/init.d/
. For example:[jsmith@server rhq-agent]$ ln -s agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh /etc/init.d/rhq-agent-wrapper.sh
ImportantOn Solaris, symlinking the agent script file requires invokingreadlink
inrhq-agent-wrapper.sh
.readlink
is not supplied by default in some Solaris installations. Solaris users must downloadreadlink
from a source such as Sunfreeware. - Register
rhq-agent-wrapper.sh
with chkconfig.[root@server rhq-agent] # /sbin/chkconfig --add rhq-agent-wrapper.sh
- 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
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
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.