Description of problem: While attempting to setup two way client authentication I found the documentation, ssl communication logging and RHQ communications settings to be in need of more detail. More specifics below. Version-Release number of selected component (if applicable): How reproducible: N/A. Steps to Reproduce: 1. N/A 2. 3. Actual results: Expected results: Additional info:
Our current instructions for securing RHQ Communications need to be enhanced to make it more consumable for users who are not very familiar with SSL. Setting up SSL communications is non-trivial and our current instructions do a very detailed job of explaining all of the requisite steps and even providing examples. Unfortunately when one or two settings are not exactly right then the user is: i) is left with nothing but an agent that sits there waiting to connect to an ssl server but never does. ii) without many helpful error messages on agent or server side. Fundamentally problems in any of the following areas can complicate the setup process and frustrate the user into moving on: -certificate creation and deployment -groups of server and agent configurations entries that must be set correctly for good communication between both sides -the decision to use socket or servlet transports has performance and client side ramifications -when the agent and server are acting as clients in the communications and which settings to modify Additionally because the ssl communications happens so low in the java communications process(i.e. within javax.net.*) that one must resort to passing in runtime parameter to the JVM to get additional details. I am proposing that the following actions be taken to update the JON documentation to include a new trouble shooting section that: - makes it clearer which server and agent configurations need to be set for the operating modes - describes how to enable more verbose debugging of SSL communications if all else fails. See here for updated troubleshooting content that I've added to the RHQ wiki: http://www.rhq-project.org/display/JOPR2/Securing+Communications#SecuringCommunications-TroubleshootingSecureCommunicationsSetup%3A Optionally, we should provide some sort of standalone UI that helps users:i) tune their server and agent settings ii) in coordination with their certificate details and firewall settings to figure out how to enable secure communications within the customer's environment.
Assigning this to Deon so that she can update the JON docs with an appropriate section to help clarify this process. The intent is just to make it a bit clearer which settings are relevant for the possible combinations.
Note to self: Add a troubleshooting section in http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Operations_Network/3.0/html/Basic_Admin_Guide/configuring-ssl.html. In the setup section, use the examples on the wiki as examples of different config options.
I added a troubleshooting section and examples for reference: http://docs.redhat.com/docs/en-US/JBoss_Operations_Network/2.4/html/Basic_Admin_Guide/configuring-ssl.html#ssl-troubleshooting
reviewed the documentation.
Closing.