7.3. Working with the Agent Command Prompt

When the agent is started in a terminal, then (along with starting the agent process) the script starts the agent command prompt. The agent prompt can be used to managed the agent by checking configuration, executing some tasks, or editing the agent setup.

7.3.1. Opening the Agent Command Prompt

The agent command prompt opens when the agent start script is run.
$ rhq-agent.sh

7.3.2. Agent Start Options

Some agent management can be performed by passing options with the rhq-agent.sh start script; these mainly relate to passing persistent configuration options to the server by loading external preferences through input files or passed parameters. These options are listed in Table 7.1, “Options for the rhq-agent.sh Script”.

Table 7.1. Options for the rhq-agent.sh Script

Short Argument Long Argument Description
-a --advanced Runs the agent script in setup mode, rather than basic start mode.
-c --config=filename Specifies an agent configuration preferences file on filesystem or classpath.
-d --daemon Runs the agent in daemon mode, which means it will not read additional commands from stdin.
-Dname[=value]   Overrides an agent configuration preference and sets a system property.
-e --console=type Specifies the implementation to use when reading console input. The three available values are jline, sigar, and java.
-g --purgeplugins Deletes all plug-ins, forcing the agent to re-download all of them
-h --help Opens the help message.
-i --input=filename Specifies a script file to use for input.
-l --cleanconfig Clears out any existing configuration and data files so the agent starts with blank configuration, with the exception of the agent security token, which is preserved.
-L --fullcleanconfig Clears out any existing configuration and data files so the agent starts with a totally clean slate, including purging the security token.
-n --nostart Runs the agent script without starting the agent process.
-o --output=filename Specifies a file to write all output from the script, excluding log messages (which are always written to the agent logs).
-p --pref=preferences_name Specifies the Java preference node to use for the agent configuration.
-s --setup Forces the agent to ask setup questions.
-t --nonative Forces the agent to disable the native system.
-u --purgedata Purges persistent inventory and other data files.
--   Stops the agent from processing options.

7.3.3. Agent Prompt Commands

The agent processes prompt commands that are passed to it, either interactively through the agent prompt or from an input file that can be passed when the start script is launched. Agent prompt commands (listed in Table 7.2, “Agent Prompt Commands”) can be used to manage resource (by checking availability, running discovery, or checking monitoring information) or to manage the agent itself (such as registering with a server, loading plug-ins, or viewing or reloading configuration settings).

Table 7.2. Agent Prompt Commands

Prompt Command Description
avail
Provides availability of inventoried resources.
config
Manages the agent configuration.
debug
Provides features to help debug the agent.
discovery
Asks a plug-in to run a server scan discovery.
download
Downloads a file from the JBoss ON server.
dumpspool
Shows the entries found in the command spool file.
exit
Shuts down the agent's communications services and kills the agent.
failover
Shows or updates the high availability server failover list.
gc
Helps free up memory by invoking the garbage collector.
getconfig
Displays one, several or all agent configuration preferences.
help
Shows help for a given command.
identify
Asks to identify a remote server.
inventory
Provides information about the current inventory of resources.
log
Configures some settings for the log messages.
metrics
Shows the agent metrics.
native
Accesses native system information.
pc
Starts and stops the plug-in container and all deployed plug-ins.
ping
Pings the JBoss ON server.
piql
Executes a PIQL query to search for running processes.
plugins
Updates the agent plug-ins with the latest versions from the server.
quit
Exits the agent prompt (without stopping the agent).
register
Registers this agent with the JBoss ON server.
schedules
Retrieves measurement schedule information for the specified resource.
sender
Controls the command sender to start or stop sending commands.
setconfig
Sets an agent configuration preference.
setup
Sets up the agent configuration by asking a series of questions.
shutdown
Shuts down all communications services without killing the agent.
sleep
Puts the agent prompt to sleep for a given amount of seconds.
start
Starts the agent comm services so it can accept remote requests.
timer
Times how long it takes to execute another prompt command.
update
Provides agent update functionality.
version
Shows the agent version information.