doc/debugging.texi

   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.
   4
   5 @node Debugging
   6 @chapter How to solve problems
   7
   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.
  11
  12 Most of the problems a merely configuration and user problems but
  13 nevertheless there are the most annoying ones and reponsible for many
  14 gray hairs.  We try to give some guidelines here on how to identify and
  15 solve the problem at hand.
  16
  17
  18 @menu
  19 * Debugging Tools::       Description of some useful tools
  20 * Common Problems::       Commonly seen problems.
  21 * Architecture Details::  How the whole thing works internally.
  22 @end menu
  23
  24
  25 @node Debugging Tools
  26 @section Debugging Tools
  27
  28 The GnuPG distribution comes with a couple of tools, useful to help find
  29 and solving problems.
  30
  31 @menu
  32 * kbxutil::        Scrutinizing a keybox file.
  33 @end menu
  34
  35 @node kbxutil
  36 @subsection Scrutinizing a keybox file
  37
  38 A keybox is a file fomat used to store public keys along with meta
  39 information and indices.  The commonly used one is the file
  40 @file{pubring.kbx} in the @file{.gnupg} directory. It contains all
  41 X.509 certificates as well as OpenPGP keys@footnote{Well, OpenPGP keys
  42 are not implemented, @command{gpg} still used the keyring file
  43 @file{pubring.gpg}} .
  44
  45 @noindent
  46 When called the standard way, e.g.:
  47
  48 @samp{kbxutil ~/.gnupg/pubring.kbx}
  49
  50 @noindent
  51 it lists all records (called @acronym{blobs}) with there meta-information
  52 in a human readable format.
  53
  54 @noindent
  55 To see statistics on the keybox in question, run it using
  56
  57 @samp{kbxutil --stats ~/.gnupg/pubring.kbx}
  58
  59 @noindent
  60 and you get an output like:
  61
  62 @example
  63 Total number of blobs:       99
  64                header:        1
  65                 empty:        0
  66               openpgp:        0
  67                  x509:       98
  68           non flagged:       81
  69        secret flagged:        0
  70     ephemeral flagged:       17
  71 @end example
  72
  73 In this example you see that the keybox does not have any OpenPGP keys
  74 but contains 98 X.509 cerificates and a total of 17 keys or certificates
  75 are flagges as ephemeral, meaning that they are only temporary stored
  76 (cached) in the keybox and won't get listed using the usual commands
  77 provided by @command{gpgsm} or @command{gpg}. 81 certifcates are stored
  78 in a standard way and directly available from @command{gpgsm}.
  79
  80
  81
  82
  83
  84 @node Common Problems
  85 @section Commonly Seen Problems
  86
  87
  88 @itemize @bullet
  89 @item Error code @samp{Not supported} from Dirmngr
  90
  91 Most likely the option @option{enable-ocsp} is active for gpgsm
  92 but Dirmngr's OCSP feature has not been enabled using
  93 @option{allow-ocsp} in @file{dirmngr.conf}.
  94
  95 @item The Curses based Pinentry does not work
  96
  97 The far most common reason for this is that the environment variable
  98 @code{GPG_TTY} has not been set correctly.  Make sure that it has been
  99 set to a real tty devce and not just to @samp{/dev/tty};
 100 i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
 101 @samp{GPG_TTY=`tty`} --- note the back ticks.  Also make sure that
 102 this environment variable gets exported, that is you should follow up
 103 the setting with an @samp{export GPG_TTY} (assuming a Bourne style
 104 shell). Even for GUI based Pinentries; you should have set
 105 @code{GPG_TTY}. See the section on installing the @command{gpg-agent}
 106 on how to do it.
 107
 108
 109 @item SSH hangs while a popping up pinentry was expected
 110
 111 SSH has no way to tell the gpg-agent what terminal or X display it is
 112 running on.  So when remotely logging into a box where a gpg-agent with
 113 SSH support is running, the pinentry will get popped up on whatever
 114 display t he gpg-agent has been started.  To solve this problem you may
 115 issue the command
 116
 117 @smallexample
 118 echo UPDATESTARTUPTTY | gpg-connect-agent
 119 @end smallexample
 120
 121 and the next pinentry will pop up on your display or screen. However,
 122 you need to kill the running pinentry first because only one pinentry
 123 may be running at once.  If you plan to use ssh on a new display you
 124 should issue the above command before invoking ssh or any other service
 125 making use of ssh.
 126
 127
 128 @end itemize
 129
 130
 131 @c ********************************************
 132 @c ***  Architecture Details  *****************
 133 @c ********************************************
 134 @node Architecture Details
 135 @section How the whole thing works internally.
 136
 137
 138 @menu
 139 * gpg 1.4 vs. 1.9::   Relationship between the two branches.
 140 @end menu
 141
 142 @node gpg 1.4 vs. 1.9
 143 @subsection  Relationship between the two branches.
 144
 145 Here is a little picture showing how the components work together:
 146
 147 @image{gnupg-card-architecture, 10cm}
 148
 149 @noindent
 150 Lets try to explain it:
 151
 152 TO BE DONE.
 153
 154