svn rev #25782: trunk/doc/rst_source/krb_admins/

[ghudson@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=25782
Commit By: ghudson
Log Message:
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.


Changed Files:
U   trunk/doc/rst_source/krb_admins/troubleshoot.rst
Modified: trunk/doc/rst_source/krb_admins/troubleshoot.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/troubleshoot.rst	2012-03-21 16:57:05 UTC (rev 25781)
+++ trunk/doc/rst_source/krb_admins/troubleshoot.rst	2012-03-21 17:44:18 UTC (rev 25782)
@@ -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 at KRBTEST.COM ->
+        krbtgt/KRBTEST.COM at KRBTEST.COM using ccache
+        FILE:/me/krb5/build/testdir/ccache
+    [9138] 1332348778.823381: Retrieving user at KRBTEST.COM ->
+        krbtgt/KRBTEST.COM at KRBTEST.COM from
+        FILE:/me/krb5/build/testdir/ccache with result: 0/Unknown code 0
+    krbtgt/KRBTEST.COM at KRBTEST.COM: kvno = 1
+
 List
 ----