Chapter 4. How to Debug Problems with OpenAFS for Windows

Table of Contents

4.1. pioctl debugging ( IoctlDebug registry key)
4.2. afsd_service initialization log (%WinDir%\TEMP\afsd_init.log)
4.3. afsd_service debug logs (fs trace {-on, -off, -dump} ->%WinDir%\TEMP\afsd.log)
4.4. Using SysInternal’s Debug Viewer, Process Monitor and Process Explorer Tools
4.5. Creating Microsoft MiniDumps (fs minidump -> %WinDir%\TEMP\afsd.dmp)
4.6. Single Sign-on (Integrated Logon) debugging
4.7. RX (AFS RPC) debugging (rxdebug)
4.8. Cache Manager debugging (cmdebug)
4.9. Persistent Cache consistency check
4.10. Token Acquisition Debugging

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.