4.3. Troubleshooting SSL Problems
The most common symptom of an SSL connection problem is that the agent will hang when it starts up because it is unable to establish a connection to the JBoss ON server. There are several different areas to check when an SSL problem occurs.
4.3.1. Common SSL Connection Issues
An SSL problem is simply a connection problem, which indicates that there is a problem with the agent or server configuration. There are some general areas to check to make sure that the configuration is all right:
- Make sure that both the agent and the server hostnames are resolvable to the hostnames in their server certificates.
- Make sure that port number given for the server's secure port is actually the port number configured for the server. Check the Administration > High Availability > Servers page and verify that the public endpoint address and port are correct. Edit the server definition in the UI so they are the same as the SSL configuration.
Figure 4.1. Server Hostname and Port Configuration
If these values do not match the same values configured for the SSL connection, the agent will not be able to talk to the server. - Make sure that both the agent and the server hostnames are resolvable to the hostnames in their server certificates.
- Make sure that every certificate that is used for agent-server communication is stored in the requisite keystores with the proper aliases.
- Check that the password is properly set to access the keystore.
- Make sure that the communication is set to use TLS.
- Validate the server and agent configuration, especially the assigned transport (socket or servlet) options. There are examples of configuration in Section 4.3.3, “Example SSL Configuration”.
- If client authentication is required and the server is using the sslservlet transport option, make sure that every user who connects to the JBoss ON UI has an installed user certificate so that they can connect to the server UI using client authentication. As with the agent certificate, the user certificates must be stored in the server's keystore, Section 4.2, “Setting up Client Authentication Between Servers and Agents”.If users are unable to connect using client authentication, then change the server to use sslsocket instead of sslservlet.
4.3.2. Enabling SSL Debugging
Enabling verbose logging in the agent can return more details SSL communication messages in the agent log, which can help diagnose connection problems.
- Open the agent environment variable file. This defines some settings for the JVM which the agent runs in, including debug log settings.
vim agentRoot/rhq-agent/bin/rhq-agent-env.sh
- Add a RHQ_AGENT_ADDITIONAL_JAVA_OPTS line to set a debug environment variable.
RHQ_AGENT_ADDITIONAL_JAVA_OPTS="-Djavax.net.debug=all"
- Restart the agent.
agentRoot/rhq-agent/bin/rhq-agent.sh
4.3.3. Example SSL Configuration
These examples show what correct configuration looks like in both the server and the agent configuration files for the different encryption and authentication configuration scenarios.
Note
The examples below show only minimal configuration and assume the use of the default keystore and truststore. Users should update the relevant keystore and truststore properties with appropriate values.
Example 4.1. Encryption Only: Server (sslservlet) and Agent (sslsocket)
| Server Configuration | Agent Configuration |
|---|---|
rhq.communications.connector.transport=sslservlet rhq.communications.connector.bind-address= rhq.communications.connector.bind-port= rhq.communications.connector.transport-params=/jboss-remoting-servlet-invoker/ServerInvokerServlet rhq.server.tomcat.security.client-auth-mode=false rhq.server.client.security.server-auth-mode-enabled=false |
<entry key="rhq.communications.connector.transport" value="sslsocket" /> <entry key="rhq.agent.server.transport" value="sslservlet" /> <entry key="rhq.agent.server.bind-port" value="7443" /> |
The agent configuration defines the server's connection information, so it can be either sslservlet or sslsocket. The agent can only receive incoming messages over sslsocket.
Example 4.2. Encryption Only: Server (sslsocket) and Agent (sslsocket)
| Server Configuration | Agent Configuration |
|---|---|
rhq.communications.connector.transport=sslsocket rhq.communications.connector.bind-address= rhq.communications.connector.bind-port=7800 rhq.communications.connector.transport-params= rhq.server.tomcat.security.client-auth-mode=false rhq.server.client.security.server-auth-mode-enabled=false |
<entry key="rhq.agent.server.transport" value="sslsocket" /> <entry key="rhq.agent.server.bind-port" value="7800" /> <entry key="rhq.agent.server.transport-params" value="" /> |
Because the agent configuration defines the server's connection information, it must match the configuration in the server's
rhq-server.properties file.
Example 4.3. Encryption and Client Authentication: Server (sslservlet) and Agent (sslsocket)
| Server Configuration | Agent Configuration |
|---|---|
rhq.communications.connector.transport=sslservlet rhq.communications.connector.bind-address= rhq.communications.connector.bind-port= rhq.communications.connector.transport-params=/jboss-remoting-servlet-invoker/ServerInvokerServlet rhq.server.tomcat.security.client-auth-mode=true rhq.server.client.security.server-auth-mode-enabled=true |
<entry key="rhq.communications.connector.transport" value="sslsocket" /> <entry key="rhq.agent.server.transport" value="sslservlet" /> <entry key="rhq.agent.server.bind-port" value="7443" /> <entry key="rhq.communications.connector.security.client-auth-mode" value="need" /> <entry key="rhq.agent.client.security.server-auth-mode-enabled" value="true" /> |
Example 4.4. Encryption and Client Authentication: Server (sslsocket) and Agent (sslsocket)
| Server Configuration | Agent Configuration |
|---|---|
rhq.communications.connector.transport=sslsocket rhq.communications.connector.bind-address= rhq.communications.connector.bind-port=55555 rhq.communications.connector.transport-params= rhq.communications.connector.security.client-auth-mode=need rhq.server.client.security.server-auth-mode-enabled=true |
<entry key="rhq.agent.server.transport" value="sslsocket" /> <entry key="rhq.agent.server.bind-port" value="55555" /> <entry key="rhq.agent.server.transport-params" value="" /> <entry key="rhq.communications.connector.security.client-auth-mode" value="need" /> <entry key="rhq.agent.client.security.server-auth-mode-enabled" value="true" /> |
