HOME 22.7 User marking of trustworthiness of root certificates Top 24 Why Gpg4win cannot be broken ...23 Detecting problems in Gpg4win programs (log files) Contents German

23 Detecting problems in Gpg4win programs (log files)

It is possible that one of the Gpg4win program components does not work as expected.

Quite often this is due to a feature related to the work environment, which Gpg4win software developers are not able to detect.

To assist them with finding the problem, or to allow users to see the detailed technical processes, Gpg4win programs also offer help.

Usually though, this type of help must first be activated. One of the most important tools are log files: This is where detailed diagnostic information on internal technical processes is stored. By looking at a log file, a software developer can often quickly detect a problem and the possible solution, even if the program may seem very complex at the beginning.

If you wish to send an error report to the software developer, you may this information helpful:

http://gpg4win.org/reporting-bugs.html

Log files - described as ,,debug information" in the above-mentioned URL - frequently offer valuable information and should therefore be attached to an error report.

This chapter describes how to activate program process information (which is what log files essentially are) for individual Gpg4win programs.

23.1 Activating Kleopatra log files

Kleopatra log data consists of many files, therefore the first step is to create a file folder for the log files, for example: C:\TEMP\kleologdir

Please note that these are user settings, not system administrator settings. Therefore the settings must be made for each user who wants to create Kleopatra log data, and you must ensure that different kleologdir file folders are used.

The path to this folder must be noted in the new environment variables KLEOPATRA_LOGIDR:

To do this, open the control panel, choose System, then the tab Advanced and finally the button [Environment variables].

Add the following new user variable:

Name of variable: KLEOPATRA_LOGDIR

Value of variable:  C:\TEMP\kleologdir

Make sure that the entered file folder actually exists. You can also create it afterwards.

To ensure the log function goes into effect, Kleopatra must be shut down and restarted, the file folder of log data must exist and must be available for Kleopatra to write on.

While Kleopatra is used, it will record process information in the file kleo-log (main log file) as well as possibly many files with a name that following this pattern:
pipe-input-<TIME STAMP>-<RANDOM CHARACTER>

It may be that this information is not enough for a software developer to detect the error. He will then ask you to create another environment variable - just as you did earlier:

Name of variable: KLEOPATRA_LOGOPTIONS

Value of variable:  all

It is possible that the log files become very big very quickly. You should activate the log function only for provoking a specific error function and hence record it.

You can then turn the log function off again by deleting the environment file or slightly varying its name (so it can be easily reactivated later on). Do not forget to delete or move the log files, especially if they have become very large or there are a lot of files. It also makes sense to remove the log files before you start a new recording.

23.2 Activating GpgOL log files

To activate a GpgOL log file, you have to start a "Registry Editor". To do this, enter the command regedit under Start -> Execute or into an input request field.

Now select the following GpgOL key from the tree structure on the left hand side:
HKEY_CURRENT_USER\Software\GNU\GpgOL

On the right hand side you will see a list of entries (so-called character sequences), some of which already have pre-defined values. These entries are created when Outlook is first started with GpgOL.

To activate the GpgOL log file, double-click on the entry enableDebug and set this value to 1.

To set a value for logFile, enter the name of the file into which the log file should be written, for example: C:\TEMP\gpgol.log

Restart Outlook to start the recording process.

Remember that this file can become very large. Set enableDebug to 0 as soon as you no longer require the GpgOL log data recordings.

Also do not forget to delete or move the log file, especially if it has become a very large file. Before starting a new recording, it also makes sense to remove the log file.

More advanced technical information on GpgOL - such as more possible values for enableDebug - can be found in the technical (English) GpgOL handbook. It can be found in your Gpg4win installation directory, usually:
C:\Programme\GNU\GnuPG\share\doc\gpgol\gpgol.pdf

23.3 Activating DirMngr log file

The DirMngr is a system-wide service, therefore log files can only be activated with administrator rights.

To activate the log file, open the following configuration file:
C:\Documents and settings\All Users\Application data\GNU\etc\dirmngr\dirmngr.conf

Add the following two rows in the configuration file (the path to the log file can of course be adjusted):

debug-all
log-file C:\TEMP\dirmngr.log

Then restart DirMngr under System controls -> Administration -> Services so that the modified configuration file is reimported and the new settings become active.

Comment out your adjustment in the aforementioned configuration file (hence # debug-all) as soon as you no longer need the DirMngr log file recording.

Also do not forget to delete or move the log file, especially if it has become a very large file. Before starting a new recording, it also makes sense to remove the log file.

23.4 Activating GnuPG log files

You can activate the individual creation of a log file for each of the following GnuPG components:

  • GPG Agent
  • GPG for S/MIME
  • GPG for OpenPGP
  • Smartcard Daemon

Users can also make personal configurations for these programs. This also includes the setup of a log file for the program process.

The respective log file is activated in the GnuPG backend - which can be reached via the Kleopatra menu Settings -> Configure Kleopatra... -> GnuPG system. This configuration window features two debug options for eac hof the four programs:

  • Option Set debug level to
    Here you define the details of the information to be recorded. Debug level 4 - Guru is the highest level and creates very big files. If you no longer need these files, set the debug level to 0 - None).
  • Option Write log to FILE in server mode
    Here, you enter the log file into which all debug information should be stored, e.g. C:\TEMP\gpg-agent.log

Restart Kleopatra (you may have to shut down the pgp-agent via Task Manager, if it is still running), or you log out and log back into your Windows system.

Also do not forget to delete or move the log file, especially if it has become a very large file. Before starting a new recording, it also makes sense to remove the log file.

23.5 Activating GpgME log files

The log file settings for GpgME ("GnuPG Made Easy") must be made for each user - just like in Kleopatra.

Open the Windows control panel, select System, then the tab Advanced and then the button [Environment variables].

Add the new user variable:

Name der Variable: GPGME_DEBUG

Wert der Variable:  <DEBUGLEVEL;PFAD>, also z.B.: 5;c:\TEMP\gpgme.log

Please note that the file order you have entered must also exist. You can also set it up afterwards.

The recommended diagnostic level is the value 5. In most cases, this level supplies sufficient information. If not, then advanced users can gradually increase this level.

To turn log data recording off, set the diagnostic level to the value 0 or remove the user variable.

Also do not forget to delete or move the log file, especially if it has become a very large file. Before starting a new recording, it also makes sense to remove the log file.


© 31. August 2010, v3.0.0-beta1 (last minor changes from 21. September 2010)
The Gpg4win Compendium is filed under the GNU Free Documentation License v1.2.


HOME 22.7 User marking of trustworthiness of root certificates Top 24 Why Gpg4win cannot be broken ...23 Detecting problems in Gpg4win programs (log files) Contents German