PingDirectory

Log messages

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

  • Protocol

  • 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 includes a 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 reason element 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.

    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.