Bug 707615 - Client side authentication SSL setup/documentation needs more detail
Summary: Client side authentication SSL setup/documentation needs more detail
Alias: None
Product: RHQ Project
Classification: Other
Component: Documentation
Version: 4.0.0
Hardware: Unspecified
OS: Unspecified
unspecified vote
Target Milestone: ---
: ---
Assignee: Deon Ballard
QA Contact: Mike Foley
Depends On:
Blocks: jon30-bugs
TreeView+ depends on / blocked
Reported: 2011-05-25 14:15 UTC by Simeon Pinder
Modified: 2012-06-21 23:17 UTC (History)
2 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Last Closed: 2012-06-21 23:17:30 UTC

Attachments (Terms of Use)

Description Simeon Pinder 2011-05-25 14:15:46 UTC
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:

Steps to Reproduce:
1. N/A
Actual results:

Expected results:

Additional info:

Comment 1 Simeon Pinder 2011-06-17 17:05:28 UTC
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:

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.

Comment 2 Simeon Pinder 2011-06-17 17:10:28 UTC
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.

Comment 3 Deon Ballard 2011-06-17 21:33:00 UTC
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.

Comment 4 Deon Ballard 2011-06-28 17:45:06 UTC
I added a troubleshooting section and examples for reference:

Comment 5 Mike Foley 2011-06-30 12:46:22 UTC
reviewed the documentation.

Comment 6 Deon Ballard 2012-06-21 23:17:30 UTC

Note You need to log in before you can comment on or make changes to this bug.