Description of problem:  Consider adding documentation around Agent configuration (RPM, and regular).   It came up in the 7/11/2012 JON Agent RPM BZ review meeting that there might be an opportunity to add documentation on the topic of Agent configruation.



Agent Configuration Updates - RPM

BZs:
https://bugzilla.redhat.com/show_bug.cgi?id=834695
https://bugzilla.redhat.com/show_bug.cgi?id=836137

 
Scenario:
1) Install agent RPM
2) Start the service before any configuration - service jon-agent start
the agent will start with default configuration (eg. local server, standard config ports)
3) Realize that configuration needs to change - eg. server address
4) Stop service - service jon-agent stop
5) Update agent-configuration.xml - set server address, port, etc.
6) Restart the service - service jon-agent start

Isn't this a problem we already have we people calling rhq-agent-wrapper.sh ?
How do other services handle this, i.e. installing the rpm doesn't leave a fully configured install?
Can we just have step 2) just bailout if the agent's config hasn't been set? Isn't this how rhq-agent-wrapper.sh works today? This isn't a total solution

Having rhq-agent.sh using different preferences from service jon-agent start   is going to be very confusing.

would it be possible to run through the agent installer as part of the RPM run? like a silent install? But we dont know the correct values to use at installation you could use defaults for everything but the server name, which is a head scratcher.

Problems:
1) The changes to agent-configuration.xml (step 5) will never be picked up by agent because .java preferences folder is already on disk (created by step 2). The agent always defaults to .java configuration if present.
2) No way to get the prompt to reconfigure the agent using todays start scripts. The service is a deamon and is started by agent-wrapper.sh, which has no way to request reconfiguration today.
3) Little documentation in this area  by documentation ...do you mean something on the Wiki? or is this an opportunity for JON documentation? both, i would think. ok ... i mind if i add an enhancement BZ for doc in this area?


Short-term Solutions (for JON Agent RPM 3.1.0)

Solution 1:
1) The user has to manually do this before changing agent-configuration.xml
Uninventory the platform
Delete .java folder   just being QE-paranoid ...is there any sensitivity around this .java folder... :re JDK7 or Java upgrades?   (and by "this" I mean the .java folder for storing agent preferences)  ie...if I install JDK7 ...do I lose the preferences I have saved ?
This shouldn't be a problem. Apps, not the jdk, write to .java

2) Document all this

Solution 2:
1) The user has to manually uninventory the platform
2) Have an option the service that clears .java folder
service jon-agent clearpreferences
no way to prevent the removal of the agent security token with current functionality
3) Document all this

Solution 3:
????


Long-term Solutions (for JON Agent RPM 3.1.1 and beyond)

Solution 1:
1) Clear all the .java preferences with the exception of the token via a service command
service jon-agent cleanconfig
will not need to uninventory the platform since the security token is preserved

Solution 2:
1) Show the typical configuration prompt for agent configuration via a service command
service jon-agent config

Solution 3:
spinder: how about a real low tech solution like modifying the wrapper scripts to list a warning to the users like "You've not yet initialized your agent configuration. Run 'rhq-agent.sh/bat file to properly register agent with RHQ server.".  
- Doesn't help for agents automatically installed as services.. as there is no opportunity to get feedback to the user.

Solutions 1 & 2 can be combined