Describe trace logging in troubleshooting docs

Add a section to the troubleshooting page in the RST documentation
describing how to use trace logging and giving sample output.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25782 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/doc/rst_source/krb_admins/troubleshoot.rst b/doc/rst_source/krb_admins/troubleshoot.rst
index 036f0b50b8339ac81522027989467f5fb97b2672..7dc25795d8abb20c4abfcf2ede2462595ab42c75 100644 (file)
--- a/doc/rst_source/krb_admins/troubleshoot.rst
+++ b/doc/rst_source/krb_admins/troubleshoot.rst
@@ -1,6 +1,33 @@
 Troubleshooting
 ===============
 
+Trace logging
+-------------
+
+Most programs using MIT krb5 1.9 or later can be made to provide
+information about internal krb5 library operations using trace
+logging.  To enable this, set the **KRB5_TRACE** environment variable
+to a filename before running the program.  On many operating systems,
+the filename ``/dev/stdout`` can be used to send trace logging output
+to standard output.
+
+Some programs do not honor **KRB5_TRACE**, either because they use
+secure library contexts (this generally applies to setuid programs and
+parts of the login system) or because they take direct control of the
+trace logging system using the API.
+
+Here is a short example showing trace logging output for an invocation
+of the :ref:`kvno(1)` command::
+
+    shell% env KRB5_TRACE=/dev/stdout kvno krbtgt/KRBTEST.COM
+    [9138] 1332348778.823276: Getting credentials user@KRBTEST.COM ->
+        krbtgt/KRBTEST.COM@KRBTEST.COM using ccache
+        FILE:/me/krb5/build/testdir/ccache
+    [9138] 1332348778.823381: Retrieving user@KRBTEST.COM ->
+        krbtgt/KRBTEST.COM@KRBTEST.COM from
+        FILE:/me/krb5/build/testdir/ccache with result: 0/Unknown code 0
+    krbtgt/KRBTEST.COM@KRBTEST.COM: kvno = 1
+
 List
 ----