From b00f7c3ffe1102d36cd0b6a516030e02fa659a75 Mon Sep 17 00:00:00 2001 From: Jeffrey Altman Date: Mon, 4 Jun 2007 13:16:56 +0000 Subject: [PATCH] DEVEL15-windows-release-notes-20070604 in the 1.5.9 release time frame sections 4 and 5 on debugging and bug reporting got lost. restore them. --- .../en_US/html/ReleaseNotes/relnotes.htm | 361 +++++++++++++++--- .../en_US/html/ReleaseNotes/toc.htm | 22 +- 2 files changed, 323 insertions(+), 60 deletions(-) diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm index b34deb2aa..9191e0139 100644 --- a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm @@ -566,11 +566,12 @@ ul mso-bidi-language:#0400;} + Version 3.2 is required for the best user experience.

+src="relnotes_files/image002.jpg" v:shapes="_x0000_s1027">

The Network Identity Manager replaces the former KFW ticket manager, Leash, and when combined with the OpenAFS Provider, it is intended to @@ -936,10 +937,10 @@ Tool, Network Identity Manager with the OpenAFS Provider can easily manage AFS tokens for multiple cells from one or more Kerberos v5 identities.

+src="relnotes_files/image004.jpg" v:shapes="_x0000_s1026">

The AFS configuration panel for each Kerberos v5 identity is used to configure which cells credentials should be obtained for and how they @@ -949,10 +950,10 @@ specified. v5 tickets as tokens, then a krb524 service can be configured.

+src="relnotes_files/image006.jpg" v:shapes="_x0000_s1025">

The OpenAFS Provider configuration panel can be used to check the status of the AFS Client Service and its version. +

4. How to Debug Problems with OpenAFS for Windows:

+ +

OpenAFS for Windows provides a wide range of tools to assist +you in debugging problems. The techniques available to you are varied because +of the wide range of issues that have been discovered over the years.

+ +

4.1. +pioctl debugging (IoctlDebug +registry key)

+ +

pioctl (path-based ioctl) calls are used by various tools to +communicate with the AFS Client Service. Some of the operations performed +include:

+ +

· +setting/querying tokens (tokens.exe, aklog.exe, afscreds.exe)

+ +

· +setting/querying ACLs

+ +

· +setting/querying cache parameters

+ +

· +flushing files or volumes

+ +

· +setting/querying server preferences

+ +

· +querying path location

+ +

· +checking the status of servers and volumes

+ +

· +setting/querying the sysname list

+ +

pioctl calls are implemented by writing to a special UNC +path that is processed by the AFS Client Service. If there is a failure to +communicate with the AFS Client Service via SMB/CIFS, it will be impossible to +perform any of the above operations.

+ +

To assist in debugging these problems, the registry value:

+ +

[HKLM\SOFTWARE\OpenAFS\Client]

+ +

REG_DWORD: IoctlDebug = 0x01

+ +

should be set. Then any of the commands that perform pioctl +calls should be executed from the command prompt. With this key set the pioctl +library will generate debugging output to stderr. The output will contain the +Win32 API calls executed along with their most important parameters and their +return code. The MSDN Library and the Microsoft KnowledgeBase can be used as +a reference to help you determine the configuration probem with your system.

+ +

4.2. +afsd_service initialization log (%WinDir%\TEMP\afsd_init.log)

+ +

Every time the AFS Client Service starts it appends data +about its progress and configuration to a file. This file provides information +crucial to determining why the service cannot start when there are problems. +When the process terminates due to a panic condition it will write to this file +the source code file and line number of the error. In many cases the panic +condition is due to a misconfiguration of the machine. In other cases it might +be due to a programming error in the software. A quick review of the location +in the source code will quickly reveal the reason for the termination.

+ +

The MaxLogSize +registry value determines the maximum size of the %WINDIR%\TEMP\afsd_init.log +file. If the file is larger than this value when OpenAFS Client Service +starts, the file will be reset to 0 bytes. If value is set to 0, the file will +be allowed to grow indefinitely.

+ +

4.3. +afsd_service debug logs (fs trace {-on, -off, -dump} +->%WinDir%\TEMP\afsd.log)

+ +

When attempting to debug the behavior of the SMB/CIFS Server +and the Cache Manager it is often useful to examine a log of the operations +being performed. While running the AFS Client Service keeps an in memory log +of many of its actions. The default number of actions preserved at any one +time is 5000. This can be adjusted with the registry value:

+ +

+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

+ +

REG_DWORD TraceBufferSize

+ +

A restart of the service is necessary when adjusting this +value. Execute "fs trace -on" to clear to the log and "fs +trace -dump" to output the contents of the log to the file.

+ +

4.4. +Using SysInternals DbgView and ProcMon or FileMon Tools

+ +

An alternatve option to the use of "fs trace -dump" +to capture internal OpenAFS Client Service events is to use a tool such as +Sysinternal's DbgView to capture real-time debugging output. When the OpenAFS +Client Service starts and Bit 2 of the TraceOption +value in the registry is set, all trace log events are output using the Windows +Debug Monitor interface (OutputDebugString).

+ +

+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

+ +

REG_DWORD TraceOption = +0x04

+ +

Use fs trace on and fs trace off to toggle the +generation of log messages.

+ +

Sysinternals ProcMon or FileMon utilities can be use to monitor the +file operations requested by applications and their success or failure. +

+ +

+In FileMon, use the Volumes menu to restrict monitoring to Network volumes only in +order to reduce the output to just the CIFS requests. Turn on the Advanced +Output option in order to log with finer granularity.

+ +

+In ProcMon, set a filter to include only events on file paths that refer to the AFS name +space. Be sure to include both the UNC path as well as any drive letters mapped to AFS. +

+ +

Turn on the Clock Time and Show Milliseconds +options in both tools to make it easier to synchronize the application requests +and the resulting OpenAFS Client Service operations. The captured data can be +stored to files for inclusion in bug +reports.

+ +

4.5. Microsoft +MiniDumps
+(fs minidump -> %WinDir%\TEMP\afsd.dmp)

+ +

If the AFS Client Service become unresponsive to any form of +communication there may be a serious error that can only be debugged by someone +with access to the source code and a debugger. The "fs minidump" +command can be used to force the generation of a MiniDump file containing the +state of all of the threads in the AFS Client Service process.

+ +

4.6. +Single Sign-on (Integrated Logon) debugging

+ +

If you are having trouble with the Integrated Logon +operations it is often useful to be able to obtain a log of what it is +attempting to do. Setting Bit 0 of the TraceOption registry +value:

+ +

+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

+ +

REG_DWORD TraceOption = 0x01

+ +

will instruct the Integrated Logon Network Provider and +Event Handlers to log information to the Windows Event Log: Application under +the name AFS Logon".

+ +

4.7. +RX (AFS RPC) debugging (rxdebug)

+ +

The rxdebug.exe tool can be used to query a variety of +information about the AFS services installed on a given machine. The port for +the AFS Cache Manager is 7001.

+ +

Usage: rxdebug -servers <server machine> [-port +<IP port>] [-nodally]

+ +

+[-allconnections] [-rxstats] [-onlyserver] [-onlyclient]

+ +

[-onlyport <show +only <port>>]

+ +

[-onlyhost <show +only <host>>]

+ +

[-onlyauth <show +only <auth level>>] [-version]

+ +

[-noconns] [-peers] +[-help]

+ +

Where: -nodally don't show dallying conns

+ +

-allconnections don't filter out +uninteresting connections

+ +

-rxstats show Rx statistics

+ +

-onlyserver only show server conns

+ +

-onlyclient only show client conns

+ +

-version show AFS version id

+ +

-noconns show no connections

+ +

-peers show peers

+ +

4.8. +Cache Manager debugging (cmdebug)

+ +

The cmdebug.exe tool can be used to query the state of the +AFS Cache Manager on a given machine.

+ +

Usage: cmdebug -servers <server machine> [-port +<IP port>] [-long]

+ +

[-refcounts] +[-callbacks] [-addrs] [-cache] [-help]

+ +

Where: -long print all info

+ +

-refcounts print only cache entries with +positive reference counts

+ +

-callbacks print only cache entries with +callbacks

+ +

-addrs print only host interfaces

+ +

-cache print only cache configuration

+ +

4.9. +Persistent Cache consistency check

+ +

The persistent cache is stored in a Hidden System file at +%WinDir%\TEMP\AFSCache. If there is a problem with the persistent cache that +prevent the AFS Client Service from being able to start a validation check on +the file can be performed.

+ +

afsd_service.exe --validate-cache +<cache-path>

+ +

5. Reporting Bugs:

+ +

Bug reports should be sent to openafs-bugs@openafs.org. +Please include as much information as possible about the issue. If you are +reporting a crash, please install the debugging symbols by re-running the +installer. If a dump file is available for the problem, +%WINDIR%\TEMP\afsd.dmp, include it along with the AFS Client Trace file +%WINDIR%\TEMP\afsd.log. The AFS Client startup log is +%WINDIR%\TEMP\afsd_init.log. Send the last continuous block of log information +from this file.

Configuring DrWatson to generate dump files for crashes:

· Run -drwtsn32.exe to configure or to identify where the log and the crash dump files -are created:

+style='font-size:9.0pt;font-family:Symbol'>· +Run drwtsn32.exe to configure or to identify where the log and +the crash dump files are created:

· click -Start > Run...

+style='font-size:9.0pt;font-family:Symbol'>· +click Start > Run...

· type -drwtsn32 <enter>.

+style='font-size:9.0pt;font-family:Symbol'>· +type drwtsn32 <enter>.

· Select -either a Crash Dump Type: Mini or Full.

+style='font-size:9.0pt;font-family:Symbol'>· +Select either a Crash Dump Type: Mini or Full.

· Clear -Dump Symbol Table

+style='font-size:9.0pt;font-family:Symbol'>· +Clear Dump Symbol Table

· Clear -Append to Existing Log file.

+style='font-size:9.0pt;font-family:Symbol'>· +Clear Append to Existing Log file.

· Check -Dump All Thread Contexts.

+style='font-size:9.0pt;font-family:Symbol'>· +Check Dump All Thread Contexts.

· Check -Create Crash Dump File

+style='font-size:9.0pt;font-family:Symbol'>· +Check Create Crash Dump File

· Next -run the monitoring module of Dr. Watson:

+style='font-size:9.0pt;font-family:Symbol'>· +Next run the monitoring module of Dr. Watson:

· click -Start > Run...

+style='font-size:9.0pt;font-family:Symbol'>· +click Start > Run...

· type -drwatson <enter>.

+style='font-size:9.0pt;font-family:Symbol'>· +type drwatson <enter>.

· Once -a crash happens, Dr. Watson generates a dump file and a report in the log file, -including the address of the crash and the stack dump.

+style='font-size:9.0pt;font-family:Symbol'>· +Once a crash happens, Dr. Watson generates a dump file and a +report in the log file, including the address of the crash and the stack dump.

Once you have the Dr. Watson's logfile and minidump, zip them and attach them to your e-mail.

diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm index dfdfc3905..150ab0ca5 100644 --- a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm @@ -519,59 +519,59 @@ Vista

4. How to Debug Problems with OpenAFS for +href="relnotes.htm#_Toc115417112">4. How to Debug Problems with OpenAFS for Windows:

4.1. pioctl debugging (IoctlDebug registry +href="relnotes.htm#_Toc115416146">4.1. pioctl debugging (IoctlDebug registry key)

4.2. afsd_service initialization log +href="relnotes.htm#_Toc115416147">4.2. afsd_service initialization log (%WinDir%\TEMP\afsd_init.log)

4.3. afsd_service debug logs (fs trace {-on, +href="relnotes.htm#_Toc115416148">4.3. afsd_service debug logs (fs trace {-on, -off, -dump} ->%WinDir%\TEMP\afsd.log)

4.4. Using SysInternals DbgView and FileMon +href="relnotes.htm#_Toc115416149">4.4. Using SysInternals DbgView and ProcMon or FileMon Tools

4.5. Microsoft MiniDumps4.5. Microsoft MiniDumps (fs minidump -> %WinDir%\TEMP\afsd.dmp)

4.6. Single Sign-on (Integrated Logon) +href="relnotes.htm#_Toc115416151">4.6. Single Sign-on (Integrated Logon) debugging

4.7. RX (AFS RPC) debugging (rxdebug)4.7. RX (AFS RPC) debugging (rxdebug)

4.8. Cache Manager debugging (cmdebug)4.8. Cache Manager debugging (cmdebug)

4.9. Persistent Cache consistency check4.9. Persistent Cache consistency check

5. Reporting Bugs:5. Reporting Bugs: