Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

7.11. Managing the Agent's Persisted Configuration

The agent uses Java preferences in the Java platform to store its configuration. Java preferences in general are described in the Java documentation at http://download.oracle.com/javase/1.5.0/docs/guide/preferences/index.html. JBoss ON stores user preferences in the backing store's root node.
The location of the backing store depends on the system:
  • On Windows, the backing store is located in the Windows registry.
  • On Linux and Unix systems, the backing store is in the agent user's home directory, in ~/.java.
    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.
    For example, if the agent is configured by a system user named jsmith, its persisted configuration is in ~jsmith/.java. If the agent is then configured to run as a background service as the root user, the agent looks for its configuration in ~root/.java, and it finds different 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 gets the configuration that it uses to run from its backing store. It only reads configuration settings from the agent-configuration.xml file when the agent needs to initialize its backing store, either at its first configuration or if the agent was started with --cleanconfig and fresh configuration settings should be loaded.
Report a bug

7.11.1. Viewing the Persisted Configuration
Copy link

Agent configuration is comprised of Java preferences, which are persisted for each JBoss ON user. The way that the configuration is persisted depends on the operating system; Windows stores the configuration in the registry, for example, while Unix keeps it in the user's home directory.
The agent configuration is loaded when it is first set up and then persisted in the database, with the exception of a few parameters which can be set and loaded through the rhq-agent-env.sh file. The agent's persisted configuration can be viewed in several different ways:
  1. If the agent is in the JBoss ON inventory, then its complete configuration settings are visible through the Configuration tab, with collapsible tables that display each configuration area.
    View larger image
  2. The configuration can also be returned through the getconfig or config prompt commands for the agent. These commands can be run through a terminal, if the agent is running through a command prompt, or through the Execute Command Prompt operation in the JBoss ON UI for the agent resource. 
    > getconfig  
rhq.agent.agent-update.enabled=true
rhq.agent.client.command-preprocessors=org.rhq.enterprise.agent. SecurityTokenCommandPreprocessor: org.rhq.enterprise.agent. ExternalizableStrategyCommandPreprocessor
rhq.agent.client.command-spool-file.compressed=true
rhq.agent.client.command-spool-file.name=command-spool.dat
rhq.agent.client.command-spool-file.params=10000000:75
rhq.agent.client.command-timeout-msecs=600000
rhq.agent.client.max-concurrent=5
rhq.agent.client.max-retries=10
rhq.agent.client.queue-size=50000
rhq.agent.client.queue-throttling=200:2000
rhq.agent.client.retry-interval-msecs=15000
rhq.agent.client.send-throttling=100:1000
rhq.agent.client.server-polling-interval-msecs=60000
rhq.agent.configuration-schema-version=5
rhq.agent.configuration-setup-flag=true
rhq.agent.data-directory=data
rhq.agent.disable-native-system=false
rhq.agent.name=localhost.localdomain
rhq.agent.plugins.directory=plugins
...
    Copy to Clipboard Toggle word wrap
  3. The agent configuration is persisted in Java preferences, so any tool which examines Java preferences can be used to view the persisted configuration.
Warning
Do not attempt to change the values of the preferences using third-party tools. Setting an agent preference to a bad value can completely disable the agent.
Report a bug
The agent's configuration is initially read from agent-configuration.xml and overlaid with the values entered at the setup prompts at start up. After the agent is initially configured, the agent persists that configuration and never refers to the agent-configuration.xml again, unless the configuration is purged and reloaded. Most configuration changes are made to the rhq-agent-env.sh file, which is loaded every time the agent starts.
It is possible to change the persisted configuration (without editing the configuration files) using the setconfig command at the agent prompt.
  1. Open the agent prompt. 
    agentRoot/rhq-agent/bin/rhq-agent.sh
    Copy to Clipboard Toggle word wrap
  2. Send the setconfig with the name of the preference to edit and its new value. The preference name is whatever the entry name is in the agent-configuration.xml file. For example: 
    > setconfig rhq.agent.client.max-concurrent=20
    Copy to Clipboard Toggle word wrap
  3. Restart the agent process to load the new configuration. 
    agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh stop

agentRoot/rhq-agent/bin/rhq-agent.sh
    Copy to Clipboard Toggle word wrap
Report a bug
The settings in the Java backing store and in the agent-configuration.xml file for the agent can be overridden using the -D option, the configuration parameter name, and the new value when the agent is started.
For example, to set a temporary value for how long the agent waits at startup to detect the JBoss ON server (rhq.agent.wait-for-server-at-startup-msecs), pass this argument with the start command: 
agentRoot/rhq-agent/bin/rhq-agent.sh -Drhq.agent.wait-for-server-at-startup-msecs=90000
Copy to Clipboard Toggle word wrap
Report a bug
Important
By default all the passwords in the {RHQ_AGENT_HOME}/conf/agent-configuration.xml file are protected during upgrades and installations. This process is only needed when users want to encode additional properties.
JBoss ON supports protecting almost all properties in the {RHQ_AGENT_HOME}/conf/agent-configuration.xml file. JBoss ON provides the rhq-encode-value.sh and rhq-encode-value.bat scripts in the {RHQ_SERVER_HOME}/bin/ directory to obfuscate properties. For agent-configuration.xml, property values are encoded using the RESTRICTED:: format and all password are protected by default at installation.
Report a bug
Note
While the rhq-encode-value script can be used for encoding server and agent configuration files, JBoss ON only provides a rhq-encode-value script at the server level. Users who wish to encode values for the agent-configuration.xml file are required to invoke the rhq-encode-value script at the JBoss ON server level.
Invoking the rhq-encode-value script will prompt users for the desired property and value to encode: 
> ./rhq-encode-value.sh
Property rhq.autoinstall.server.admin.password [y/n]: n
Property rhq.server.database.password [y/n]: n
Property: rhq.protect.property
Value: 1234
*** !!! WARNING !!!
*** Both standalone-full.xml and rhq-server.properties need to be updated if a property from rhq-server.properties is used in standalone-full.xml
*** !!! WARNING !!!
***
***
*** Encoded password for rhq-server.properties:
***    rhq.protect.property=RESTRICTED::-299a94df3b478ca8
***
*** Encoded password for standalone-full.xml with vault with password as default value:
***    ${VAULT::restricted::rhq.protect.property::-299a94df3b478ca8}
***
*** Encoded password for standalone-full.xml with vault without default:
***    ${VAULT::restricted::rhq.protect.property:: }
***
*** Encoded password for agent-configuration.xml:
***    <entry key="rhq.protect.property" value="RESTRICTED::-299a94df3b478ca8" />
***
*** Please consult the documentation for additional help.
Copy to Clipboard Toggle word wrap
After running the script, the values generated from rhq-encode-value should be copied and pasted into aagent-configuration.xml.
Report a bug
Back to top
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. Explore our recent updates.

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.

Theme

© 2025 Red Hat