How to enable SSL debug mode

“I’ve been asked to enable SSL debugging by a member of the PaperCut Support Team. I’ve looked everywhere, how am I meant to do that?”

From time to time the PaperCut developers may call on the PaperCut Support Team to enable Java SSL debugging in a PaperCut environment when troubleshooting SSL handshake issues. This can give us a highly verbose logging of SSL connections to the PaperCut NG/MF Application server. For most PaperCut System Administrators the resulting information can be overwhelming unless you know exactly what you’re looking for before you begin searching through the resulting debug logs, so only look to follow this guide if you’re an SSL or Security expert.

Please note: as all the steps below require you to download the debug mode diagnostics bundle as the final steps of retrieving your logs to provide to the PaperCut Support Team, we would recommend enabling debug mode on the PaperCut Application Server before enacting any of the following procedures.


WARNING: please remember to disable SSL debug when you have completed testing. The logging for SSL debug is extremely verbose and has been observed to cause the user interface to load noticeable slower (only when accessed over HTTPS) in moderately busy environments.

After v17.3

  1. Log onto the server hosting and running PaperCut NG/MF.
  2. Using a text editor (such as notepad.exe or SublimeText), open the server.properties file with administrator-level privileges. (For example; on a 64-bit Windows server running PaperCut MF this would be found in C:\Program Files\PaperCut MF\server\server.properties.)
  3. Using the text editor’s search function, find the line: #server.ssl.debug-output=N
  4. Remove the # entry and change the value to Y.(For example, server.ssl.debug-output=Y.)
  5. Save the server.properties file.
  6. Re-start the PaperCut Application Server service. The verbose SSL debugging will output additionally into the existing service.log file when the change takes effect. (For example, on a 64-bit Windows server running PaperCut MF this would be C:\Program Files\PaperCut MF\server\logs\service.log.)
  7. Attempt to reproduce the SSL issue you’re having.
  8. Download the debug .zip file from your PaperCut NG/MF server to share with the PaperCut Support Team. This is found in Options > Advanced > Diagnostics > Download Diagnostics File.

Before v17.3

Windows & Linux

  1. Log onto the server hosting and running PaperCut NG/MF.
  2. Using a text editor (such as notepad.exe or SublimeText), find and open the service.conf file. (For example, on a 64-bit Windows server running PaperCut MF would be C:\Program Files\PaperCut MF\server\custom\service.conf.)
  3. Add the following line: wrapper.java.additional.8=-Djavax.net.debug=all
  4. Save the service.conf file.
  5. Restart the PaperCut Application Server. The verbose SSL debugging will output to a new server-out.log file when the change takes effect. (For example, on a 64-bit Windows server running PaperCut MF this would be C:\Program Files\PaperCut MF\server\logs\server-out.log)
  6. Attempt to reproduce the SSL issue you’re having.
  7. Download the debug .zip file from your PaperCut NG/MF server to share with the PaperCut Support Team. This is found in Options > Advanced > Diagnostics > Download Diagnostics File.

macOS

  1. Log onto the server hosting and running PaperCut NG/MF.
  2. Using a text editor (such as SublimeText), find and open the service.conf file. (For example, on a macOS server running PaperCut MF this would be PaperCut MF/server/custom/launch-app-server.conf)
  3. Add the following line at the end of the service.conf file: PC_CUSTOM_SERVER_ARG=-Djavax.net.debug=all
  4. Save the service.conf file.
  5. Restart the PaperCut Application Server. The verbose SSL debugging will output to a new server-out.log file when the change takes effect. (For example; on a PaperCut MF server on macOS, this file would be located in: PaperCut MF/server/logs/server-out.log)
  6. Attempt to reproduce the SSL issue you’re having.
  7. Download the debug .zip file from your PaperCut NG/MF server to share with the PaperCut Support Team. This is found in Options > Advanced > Diagnostics > Download Diagnostics File.

Still have questions?

Let us know! We love chatting about what’s going on under the hood. Feel free to leave a comment below or visit our Support Portal for further assistance.


Categories: Troubleshooting Articles, Security and Privacy, Logs

Keywords: ssl, tls, handshake, debug

Comments