The following describes how to use the server's log messages to troubleshoot TLS-related issues.
To troubleshoot TLS-related issues, start by checking the server's access log. If the client can establish a TCP connection to the server, which must occur before TLS negotiation can start, the access log shows a CONNECT message with the following information:
- Source and destination address and port for the connection
- Selected client connection policy
The CONNECT message does not appear
If the CONNECT does not appear, the client might be unable to communicate with the server. The culprit can be a network problem, a firewall that is blocking attempts to communicate, or the client is trying to use an incorrect address or port.
The CONNECT message does appear
If the CONNECT message appears in the access log, it typically
conn element that specifies the connection ID. To view
additional log messages for the client connection, use the
search-logs tool. For example, if the connection ID is
12345, the following command displays the complete set of
associated log messages.
$ bin/search-logs --logFile logs/access conn=12345
If you are using LDAPS
If you are attempting to use LDAPS, one of the following log messages appears next:
- SECURITY-NEGOTIATION message – Indicates that the client and server successfully completed the negotiation process and that the issue likely occurred after the TLS session was established. This message also includes details about the negotiation, including the TLS protocol and the selected cipher suite.
DISCONNECT message – The issue might involve a failure in the TLS-negotiation process. In such scenarios, the message usually includes a
reasonelement that provides additional information about the reason for the disconnect.
If the failure occurred during TLS negotiation, the usefulness of the DISCONNECT message depends in part on whether the failure occurred on the client or the server. For example, if the server decided to abort the negotiation, the message ideally contains the specific reason. If the problem occurred on the client, the log message likely contains only the general category for the failure.Note:
The TLS protocol does not provide a mechanism for conveying detailed error messages. Instead, it offers only a basic alert mechanism with a fixed set of alert types. For example, if a client does not trust the certificate chain that the server presents to it, the server might receive a generic alert like certificate_unknown, even if the client knows the precise reason for rejecting the chain. In such instances, you might need to determine whether the client can provide additional details about the issue.
If the access log does not provide useful information
If the access log does not provide useful information, check the server error log. Although the error log does not normally include information about issues that relate to client communication, it provides helpful information in certain circumstances, like when an internal error within the server interferes with communication attempts.