* debugging.texi: New.

* gnupg.texi: Include it.

doc/debugging.texi

@@ -0,0 +1,82 @@
+@c Copyright (C) 2004 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Debugging
+@chapter How to solve problems
+
+Everone knows that software often does not do what it should do and thus
+there is a need to track down problems.  We call this debugging in a
+reminiscent to the moth jamming a relay in a Mark II box back in 1947.
+
+Most of the probelsm a merely configuration and user problems but
+nevertheless there are the most annoying ones and reposnible for may
+gray hairs.  We try to give some guidelines here on how to identify and
+solve the problem at hand.
+
+
+@menu
+* Debugging Tools::       Description of some useful tools
+
+@end menu
+
+
+@node Debugging Tools
+@section Debugging Tools
+
+The GnuPG distribution comes with a couple of tools, useful to help find
+and solving problems.
+
+@menu
+* kbxutil::        Scrutinizing a keybox file.
+@end menu
+
+@node kbxutil
+@subsection Scrutinizing a keybox file
+
+A keybox is a file fomat used to store public keys along with meta
+information and indices.  The commonly used one is the file
+@file{pubring.kbx} in the @file{.gnupg} directory. It contains all
+X.509 certificates as well as OpenPGP keys@footnote{Well, OpenPGP keys
+are not implemented, @command{gpg} still used the keyring file
+@file{pubring.gpg}} .
+
+@noindent
+When called the standard way, e.g.:
+
+@samp{kbxutil ~/.gnupg/pubring.kbx}
+
+@noindent
+it lists all records (called @acronym{blobs}) with there meta-information
+in a human readable format.
+
+@noindent
+To see statistics on the keybox in question, run it using
+
+@samp{kbxutil --stats ~/.gnupg/pubring.kbx}
+
+@noindent
+and you get an output like:
+
+@example
+Total number of blobs:       99
+               header:        1
+                empty:        0
+              openpgp:        0
+                 x509:       98
+          non flagged:       81
+       secret flagged:        0
+    ephemeral flagged:       17
+@end example
+
+In this example you see that the keybox does not have any OpenPGP keys
+but contains 98 X.509 cerificates and a total of 17 keys or certificates
+are flagges as ephemeral, meaning that they are only temporary stored
+(cached) in the keybox and won't get listed using the usual commands
+provided by @command{gpgsm} or @command{gpg}. 81 certifcates are stored
+in a standard way and directly available from @command{gpgsm}.
+
+
+
+
+