1
@c Copyright (C) 2004 Free Software Foundation, Inc.
2
@c This is part of the GnuPG manual.
3
@c For copying conditions, see the file gnupg.texi.
6
@chapter How to solve problems
8
Everyone knows that software often does not do what it should do and thus
9
there is a need to track down problems. We call this debugging in a
10
reminiscent to the moth jamming a relay in a Mark II box back in 1947.
12
Most of the probelsm a merely configuration and user problems but
13
nevertheless there are the most annoying ones and reposnible for may
14
gray hairs. We try to give some guidelines here on how to identify and
15
solve the problem at hand.
19
* Debugging Tools:: Description of some useful tools
20
* Common Problems:: Commonly seen problems.
25
@section Debugging Tools
27
The GnuPG distribution comes with a couple of tools, useful to help find
31
* kbxutil:: Scrutinizing a keybox file.
35
@subsection Scrutinizing a keybox file
37
A keybox is a file fomat used to store public keys along with meta
38
information and indices. The commonly used one is the file
39
@file{pubring.kbx} in the @file{.gnupg} directory. It contains all
40
X.509 certificates as well as OpenPGP keys@footnote{Well, OpenPGP keys
41
are not implemented, @command{gpg} still used the keyring file
45
When called the standard way, e.g.:
47
@samp{kbxutil ~/.gnupg/pubring.kbx}
50
it lists all records (called @acronym{blobs}) with there meta-information
51
in a human readable format.
54
To see statistics on the keybox in question, run it using
56
@samp{kbxutil --stats ~/.gnupg/pubring.kbx}
59
and you get an output like:
62
Total number of blobs: 99
72
In this example you see that the keybox does not have any OpenPGP keys
73
but contains 98 X.509 cerificates and a total of 17 keys or certificates
74
are flagges as ephemeral, meaning that they are only temporary stored
75
(cached) in the keybox and won't get listed using the usual commands
76
provided by @command{gpgsm} or @command{gpg}. 81 certifcates are stored
77
in a standard way and directly available from @command{gpgsm}.
84
@section Commonly Seen Problems
88
@item Error code @samp{Not supported} from Dirmngr
90
Most likely the option @option{enable-ocsp} is active for gpgsm
91
but Dirmngr's OCSP feature has not been enabled using
92
@option{allow-ocsp} in @file{dirmngr.conf}.
94
@item The Curses based Pinentry does not work
96
The far most common reason for this is that the environment variable
97
@code{GPG_TTY} has not been set correctly. Make sure that it has been
98
set to a real tty devce and not just to @samp{/dev/tty};
99
i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
100
@samp{GPG_TTY=`tty`} --- note the back ticks. Also make sure that
101
this environment variable gets exported, that is you should follow up
102
the setting with an @samp{export GPG_TTY} (assuming a Bourne style
103
shell). Even for GUI based Pinentries; you should have set
104
@code{GPG_TTY}. See the section on installing the @command{gpg-agent}
added
removed
doc/debugging.texi
