Search
SupportConsoleDevelopersStart a trialContact

2.5. Starting the JBoss ON Agent

download PDF
The JBoss ON agent can be started manually or can be configured to start and run as a system service.
Important
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 7.11, “Managing the Agent's Persisted Configuration”.
Report a bug

2.5.1. Starting the JBoss ON Agent on a Managed System

The agent is started and runs using a script in the agent's bin/ directory. Unlike the server start script, which starts the server process and then exits the script, the agent script remains open, with a prompt to accept further input if necessary. (Usually, the script can be started, and left to run in the background.) 
/opt/rhq-agent/bin/rhq-agent.sh

RHQ 3.3.0-SNAPSHOT [cda7569] (Tue Apr 13 13:39:16 EDT 2017)
>
Most of the time, the JBoss ON agent can run without any additional options or settings. All of the available options for the rhq-agent.sh script are listed in Section 7.3.3, “Agent Prompt Commands”. Additional configuration options can be set by editing the rhq-agent-env.sh script file.
Note
If there are any errors when starting the JBoss ON agent, run the agent start script with the --cleanconfig to wipe the previous agent configuration and start fresh.
Report a bug

2.5.2. Starting an Agent Installed on a Server Machine

If an agent is installed on the same system as a server or a storage node, then the agent is controlled by the same control script (rhqctl) that the server and storage node are. To start an agent, use the --agent option with the script. 
[root@server ~]# serverRoot/jon-server-3.3.0.GA/bin/rhqctl start --agent
This starts the agent in the background, rather than opening the agent console.
By default, the agent init script runs as the local system account (Default or .\LocalSystem). The ssytem user account can be changed by editing the rhq-agent-env.bat script, as described in Section 2.5.3, “Configuring the Agent as a Windows Service”. The agent on the server machine is still started and stopped using the rhqctl command.
Report a bug

2.5.3. Configuring the Agent as a Windows Service

  1. 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, verify 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 System user.
    Other available environment variables are listed and defined in the comments in the rhq-agent-wrapper.bat script.
  2. Run the rhq-agent-wrapper.bat script to install the init script as a service. Use the install command to install the init script.
  3. When prompted, fill in the password for the system user as whom the service will run.
The agent service starts automatically when the Windows system boots. The service can be started or stopped through the Windows Services Administrative Tools.
The agent service can also be started and stopped through the rhq-agent-wrapper.bat script using the start and stop commands. The status command shows whether the agent init script is installed as a service and whether it is running. The remove command removes the agent init script as a service.
The JBoss ON agent Windows scripts use the Java Wrapper Service to control the service. A configuration file, agentRoot\bin\wrapper\rhq-agent-wrapper.conf, contains the service configuration properties. These are standard wrapper service properties; more information is available at http://wrapper.tanukisoftware.org/doc/english/properties.html.
There are some common properties to edit to custom the service:
  • wrapper.app.parameter.# set command-line options to pass to the agent. These are the same options listed in Section 7.3, “Working with the Agent Command Prompt”. Each option requires its own configuration property. Properties must be placed in numeric order and the first two properties (wrapper.app.parameter.1 and wrapper.app.parameter.2) are reserved. Start with wrapper.app.parameter.3.
  • wrapper.java.additional.# set additional JVM options that are passed directly to the VM, corresponding to the -D and -X options. These also must be incremented numerically. wrapper.java.additional.1 always specifies the log configuration file.
  • wrapper.ntservice.starttype sets when to start the service. The default is AUTO_START, which starts the service when the system boots. To start the service manually, the value is DEMAND_START.
Report a bug

2.5.4. 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 7.11, “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_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
Report a bug

2.5.5. Starting an Agent with a Custom Command

When configuring the agent to run as a service in Section 2.5.4, “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.
Report a bug

2.5.6. Restarting the Agent and the JVM

The agent can be restarted without taking down the agent JVM process. It is also possible to restart both the agent and its JVM.
The agent is managed through a plug-in container managed by the JBoss ON server. The container loads and manages the lifecycle of all agents. Restarting the plug-in container restarts the agent and all its components without destroying the JVM.
  1. Select the Resources menu in the top navigation bar, and select the Servers menu item.
  2. Click the agent resource in the list.
  3. Click the Operations tab.
  4. Select and launch the Restart task.
Alternatively, both the agent and its JVM can be restarted (this can be useful if, for instance, the launcher script or the JVM options have been edited).
  1. Select the Resources menu in the top navigation bar, and select the Servers menu item.
  2. Click the agent resource in the list.
  3. Navigate to the launcher script child resource beneath the agent.
  4. Click the Operations tab for the launcher script resource.
  5. Select and launch the Restart task.
Report a bug
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.