windows-install-notes-20050904

[openafs.git] / doc / txt / winnotes / afs-install-notes.txt

OpenAFS for Windows 1.5.0000 Installation Notes
-----------------------------------------------

OpenAFS for Windows 1.5.0000 is an unstable development client available for 
Microsoft Windows operating systems.  It can be installed either as
a new installation or an upgrade from previous versions of OpenAFS
for Windows or IBM AFS for Windows.  Installers are provided in two
forms:

  * an executable (.exe) that is based upon the Nullsoft Scriptable
    Installation System, or

  * a Windows Installer package (.msi) that is built using WiX and
    can be customized for organizations via the use of MSI Transforms
    (see msi-deployment-guide.txt)

System Requirements:

Operating System: Windows 2000, 2000 Server, XP Home, XP Pro, 2003 Server.
64-bit versions of Windows and Windows Vista are not supported in this 
release.

Disk Space: up to 60mb required for the OpenAFS binaries plus 100MB 
for the default AFSCache file.   (The size of the AFSCache file may
be adjusted via the Registry after installation.)

Additional Softare:  MIT Kerberos for Windows 2.6.x if Kerberos 5 
authentication support is desired.

1. The Kerberos 4 infrastructure on which the 1.2 series is reliant is no 
longer secure.  Cross-realm Kerberos is very important in the AFS context and 
most sites have or are migrating to Kerberos 5 environments.  The 1.3 series 
integrates with the MIT Kerberos for Windows 2.6.x product to provide Kerberos 
5 functionality including the ability to auto-renew credentials and obtain 
single sign-on capabilities with the Microsoft Windows Kerberos Logon Service.

As of 1.3.65, the OpenAFS client will directly use Kerberos 5 tickets as 
tokens if KFW is installed.  The client requires that all of the AFS Servers 
with which it communicates support the use of Kerberos 5 tickets as tokens 
(aka 2b tokens). This means that all of the AFS servers must be running 
OpenAFS release 1.2.8 or higher.  Transarc servers do not support Kerberos 5 
tickets as tokens.

When using a Microsoft Windows Active Directory as the KDC which issues the 
service ticket for the AFS cell there are two things to consider.  First, the 
Kerberos 5 tickets issued by Active Directory can be quite large when compared 
to tickets issued by a traditional KDC due to the incorporation of 
authorization data in the PAC.  If this is your situation you either must 
modify your 1.2.x servers to support tokens larger than a few hundred bytes; 
or install the 1.3.64 or higher release on your servers.  Second, Windows 2003 
Active Directory will issue service tickets utilizing the DES-CBC-MD5 enctype. 
OpenAFS releases older than 1.3.64 will not properly support this enctype.


2. The AFS Client Service does not provide robust behavior in an environment 
with a plug-n-play network environment.  Changes to the number of network 
adapters or the assigned IP addresses will cause the service to panic.  The 
recommended work around for this problem is to install the Microsoft Loopback 
Adapter on the machine.  When the MLA is installed with a static IP address 
the AFS Client Service will bind only to the loopback and not be affected by 
changes to state of other network adapters installed on the system.  

Starting in the 1.3.65 release the installers provided by OpenAFS.org will 
install the Microsoft Loopback Adapter for you with a name of "AFS" and a 
pre-assigned IP address in the 10.x.x.x range.

One of the benefits of using the MLA is that the NETBIOS names used for the 
AFS Client's SMB server do not have to be published on any adapter other than 
the MLA.  This means that the names no longer need to be unique.  When the MLA 
is in use, the NETBIOS name associated with the AFS Client Service is simply 
"AFS".  When the MLA is not in use the NETBIOS name is "MACHINE-AFS".

When the MLA is installed, UNC paths of the form \\AFS\cellname\path may be 
used.

The MLA is installed with a binding to "Client for Microsoft Networks" but not 
to "File and Printer Sharing for Microsoft Networks".  If you fail to bind 
"Client Microsoft Networks" you will not be able to access the AFS Client 
Service when the machine is disconnected from the network.  If you bind "File 
and Printer Sharing ..." there will be a service type collision between the 
name "AFS" and the name of the machine on the published IP Address.  This will 
result in a failure to be able to access files in AFS.  The "NET VIEW" command 
will return a "System Error 52" message when this conflict exists.  To correct 
the problem:

 * stop the AFS Client Service
 * bind the "Client for Microsoft Networks" to the MLA
 * unbind "File and Printer Sharing for Microsoft Networks" from the MLA
 * Disable and then Enable the MLA
 * start the AFS Client Service


3. Traditionally, when the AFS Client Service starts it must be able to access 
the "root.afs" volume of the default cell.  The "root.afs" volume contains a 
set of read-only and read-write mount points to the "root.cell" volumes of 
various cells the administrator of the default cell believes should be 
accessible.  If the "root.afs" volume is inaccessible when the client service 
is started, the service will panic. Since many users now use laptops or 
otherwise operate in disconnected environments in which a VPN may be needed to 
access the cell's servers, it is often the case that the "root.afs" volume for 
the default cell is not reachable and the AFS Client Service will not 
successfully start. 
 
The OpenAFS Client Service now supports a fake "root.afs" volume which is 
dynamically constructed when the service starts.  This mode is called 
Freelance mode.  Freelance mode is turned on by default.

The contents of the fake "root.afs" volume are constructed dynamically as 
cells are accessed.  When the fake "root.afs" volume is constructed it will 
only contain two mount points: a read-only and read-write mount point used to 
access the "root.cell" volume of the default AFS cell.  Any attempt to access 
a valid cell name will automatically result in a new mount point being created 
in the fake "root.afs" volume.  If the cellname begins with a "." the mount 
point will be read-write; otherwise the mount point will be read-only.  These 
mount points are preserved in the registry at key:

  HKLM\SOFTWARE\OpenAFS\Client\Freelance

Additional mount points may be manually created using the "fs mkmount" 
command.  Mount points may be removed using the "fs rmmount" command.

    >fs mkmount \\AFS\all\athena.mit.edu root.cell athena.mit.edu
    >fs mkmount \\AFS\all\.athena.mit.edu root.cell athena.mit.edu -rw
    >fs rmmount \\AFS\all\athena.mit.edu
    >fs rmmount \\AFS\all\.athena.mit.edu

Beginning in 1.3.74, the Freelance fake root.afs volume will support the 
creation of symlinks.

  >symlink make \\afs\all\link \\afs\all\athena.mit.edu\user\j\a\jaltman

  >symlink list \\afs\all\link
  '\\afs\all\link' is a symlink to 'athena.mit.edu\user\j\a\jaltman'

  >symlink rm \\afs\all\link

The symlinks are stored in the registry at:

  HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks 
     

4. The OpenAFS for Windows client will use AFSDB DNS records to discover cell 
information when it is not located in the local CellServDB file 
(\%PROGRAMFILES%\OpenAFS\Client\CellServDB).


5. OpenAFS for Windows 1.3.72 only supports Windows 2000, Windows XP, and 
Windows 2003.  Windows NT 4.0 and the entire Windows 9x/Me line are no longer 
supported.  Older releases of OpenAFS are available for download if those 
operating systems must be supported.  The last version with support for Win9x 
is 1.2.2b.  The last version with support for Windows NT 4.0 is 1.2.10.


6. OpenAFS for Windows installs a WinLogon Network Provider to provide 
Integrated Logon (Single Sign-on) functionality. Integrated Logon can be used 
when the Windows username and password match the username and password 
associated with the default cell's Kerberos realm.  For example, if the 
windows username is "jaltman" and the default cell is "athena.mit.edu", then 
Integrated Logon can be successfully used if the windows password matches the 
password used for the Kerberos principal "jaltman@ATHENA.MIT.EDU".

Integrated Logon is required if you desire the ability to store roaming user 
profiles within the AFS file system.  OpenAFS does not provide tools for 
synchronizing the Windows and Kerberos user accounts and passwords.

If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain 
tokens.  Otherwise, Kerberos 4 is used.

There is a High Security mode for use with Integrated Logon when multiple 
users will share a single machine.  There are known problems with this mode. 
In particular, if you are using this mode it is crucial that new AFS tokens 
not be obtained after the logon session starts except via the AFS Systray tool 
as started by the AFS Network Provider.  If the AFS Systray tool is stopped 
you must log off to obtain new tokens.  Do not use external tools such as 
"aklog.exe" if High Security mode is turned on. As of 1.3.70, OpenAFS supports 
Authenticated SMB connections which removes the need for High Security mode. 
DO NOT USE IT!!!!! 

Starting in 1.3.83, when Integrated Logon is used in conjunction with KFW, the 
Kerberos 5 tickets obtained during the process of generating AFS tokens are 
preserved and stored into the default ccache within the user logon session.

What Integrated Logon does not do:
 (a) Integrated Logon does not have the ability to cache the user's 
     username and password for the purpose of obtaining tokens if the
     Kerberos KDC is inaccessible at logon time.


7. The AFS Systray tool (afscreds.exe) supports several command line 
options: 

    -A = autoinit 
    -E = force existing afscreds to exit
    -I = install startup shortcut
    -M = renew drive maps 
    -N = IP address change detection 
    -Q = quiet mode.  do not display start service dialog
         if afsd_service is not already running
    -S = show tokens dialog on startup
    -U = uninstall startup shortcut
    -X = test and do map share
    -Z = unmap drives
    -: = magic parameter for high security mode 

autoinit will result in automated attempts to acquire AFS tokens when 
afscreds.exe is started.  afscreds.exe will attempt to utilize tickets stored 
in the MSLSA credentials cache; any existing CCAPI credentials cache; and 
finally display an Obtain Tokens dialog to the user.  When used in combination 
with IP address change detection, afscreds.exe will attempt to acquire AFS 
tokens whenever the IP address list changes and the Kerberos KDC is 
accessible.

The renew drive maps option is used to ensure that the user drive maps 
constructed via the AFS tools (not NET USE) are re-constructed each time 
afscreds.exe is started.

By default afscreds.exe is configured by the OpenAFS.org installers to use -A 
-N -M -Q as startup options.  Currently, there is no UI to change this 
selection after install time although these options may be altered via the 
registry either per machine or per user.  See AfscredsShortcutParams in 
registry.txt.


8. As of 1.3.71, the OpenAFS for Windows client supports a local Windows 
authorization group called "AFS Client Admins".  This group is used in place 
of the "Administrators" group to determine which users are allowed to modify 
the AFS Client Service configuration via either afs_config.exe or fs.exe.  For 
example, the following fs.exe commands are now restricted to members of the 
"AFS Client Admins" group:

    - checkservers with a non-zero timer value
    - setcachesize
    - newcell
    - sysname with a new sysname list
    - exportafs
    - setcell
    - setserverprefs
    - storebehind
    - setcrypt
    - cscpolicy
    - trace

Setting the default sysname for a machine should be done via the registry and 
not via "fs sysname".

The local "SYSTEM" account is always a member of the "AFS Client Admins" 
group.

The initial membership of the "AFS Client Admins" group when created by the 
installer is equivalent to the local "Administrators" group.  If a user is 
added to the "Administrators" group after the creation of the "AFS Client 
Admin" group, that user will not be an AFS Client Administrator.  Only users 
that are members of the "AFS Client Admins" group are AFS Client 
Administrators.


9. The AFS Client should support UNC paths everywhere.  Power users that make 
extensive use of the command line shell, cmd.exe, might want to consider using 
JP Software's 4NT command processor.  Unlike cmd.exe, 4NT does fully support 
UNC paths and can use a UNC path as the default device.


10. The AFS Client ships with its own version of aklog.exe which should be 
used in preference to those obtained by third party sources.  The OpenAFS 
aklog.exe supports Kerberos 5 as well as the ability to auto-generate pts IDs 
for user's obtaining tokens to foreign cells.

Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
             [[-p | -path] pathname]
             [-noprdb] [-force]
             [-5 | -4]

   -d gives debugging information.
   krb_realm is the kerberos realm of a cell.
   pathname is the name of a directory to which you wish to authenticate.
   -noprdb means don't try to determine AFS ID.
   -5 or -4 selects whether to use Kerberos V or Kerberos IV.
      (default is Kerberos V)
   No commandline arguments means authenticate to the local cell.


11. The AFS Server functionality provided with OpenAFS 1.3.72 might work but 
should be considered highly experimental.  It has not been thoroughly tested. 
Any data which would cause pain if lost should not be stored in an OpenAFS 
Server on Windows.

A few notes on the usage of the AFS Client Service if it is going to be 
used with the OpenAFS AFS Server:

(a) When the AFS Server is installed Freelance mode must be turned off.  

(b) The AFS Server and related tools only support the built in kaserver
(Kerberos IV).  If the AFS Server is being used, MIT Kerberos for Windows
should not be used.


12. The OpenAFS for Windows installers now include Symbol information which 
should be installed if you are experiencing problems and need to send crash 
reports.  This is true in both the release and the debug versions of the 
installers.  The differences between the release and debug versions are 
whether or not the binaries were compiled with optimization; whether the debug 
symbols are installed by default; and whether additional debug statements were 
compiled into the binaries.


13. OpenAFS for Windows does not support files larger than 2GB.  This is due 
to the lack of support for the Unicode version of the SMB/CIFS protocol.


14. Local RPC is used as the default RPC mechanism for setting tokens.  TCP 
RPC is required to be installed and is used for debugging and other functions.


15. The OpenAFS for Windows installer by default activates a weak form of 
encrypted data transfer between the AFS client and the AFS servers.  This is 
often referred to as "fcrypt" mode.


16. OpenAFS 1.3.71 adds support for authenticated SMB connections using either 
NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...).  In previous versions of OpenAFS 
the SMB connections were unauthenticated which left open the door for several 
security holes which could be used to obtain access to other user's tokens on 
shared machines.  With the introduction of authenticated SMB connections the 
so called High Security mode should no longer be used.  

When GSS SPNEGO results in a Kerberos 5 authentication, the Windows SMB client 
will attempt to retrieve service tickets for "cifs/afs@REALM" (if the loopback 
adapter is in use) or "cifs/machine-afs@REALM" (if the loopback adapter is not 
being used).  It is extremely important that this service principal not exist 
in the KDC database.   If the request for this ticket fails, a subsequent 
request for "cifs/HOST$@REALM" will be issued.  This service principal should 
exist in the KDC database.  The key associated with this service principal 
must match the key assigned to "host/machine@REALM".  If the local machine is 
part of a Windows Domain this will all be taken care of for you.  If the local 
machine is using a non-MS KDC for authentication, then your KDC administrator 
will have to add these service principals to the list of principals to be 
maintained for each host.


17. As of 1.3.70, INI files are no longer used for the storage of AFS 
configuration data.  No longer are there any AFS related files stored in the 
%WINDIR% directory.  The CellServDB file is no longer called "afsdsbmt.ini" 
and it is stored in the OpenAFS\Client directory.  The afs_freelance.ini and 
afsdsbmt.ini file data has been moved to the registry.  

IMPORTANT: while the CellServDB file location and freelance mountpoint data 
will be automatically migrated; there is no mechanism for automatic migration 
of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.


18. As of 1.3.70, the OpenAFS Client is compatible with Windows XP SP2 and 
Windows 2003 SP1.  The Internet Connection Firewall will be automatically 
adjusted to allow the receipt of incoming callback messages from the AFS file 
server.  In addition, the appropriate Back Connection entries are added to the 
registry to allow SMB authentication to be performed across the loopback 
connection.


19. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote Admin 
Protocol which provides browsing of server and share information. This 
significantly enhances the interoperability of AFS volumes within the Explorer 
Shell and Microsoft Office applications.


20. OpenAFS will now automatically forget a user's tokens upon Logoff unless 
the user's profile was loaded from an AFS volume.  In this situation there is 
no mechanism to determine when the profile has been successfully written back 
to the network.  It is therefore unsafe to release the user's tokens.  Whether 
or not the profile has been loaded from the registry can be determined for 
Local Accounts, Active Directory accounts and NT4 accounts.

If there is a need to disable this functionality, the LogoffPreserveTokens 
registry value (see registry.txt) can be used.
                                                   

21. Terminal Server installations. 
When installing the NSIS (.exe) installer under Terminal Server, you must 
execute it from within the Add/Remove Programs Control Panel.  Failure to do 
so will result in AFS not running properly.  The AFS Server should not be 
installed on a machine with Terminal Server installed.


22. AFS is a Unix native file system.  As such the OpenAFS client attempts to 
treat the files stored in AFS as they would be on Unix.  File and directory 
names beginning with a "." are automatically given the Hidden attribute so 
they will not normally be displayed.


23. Some organizations which have AFS cell names and Kerberos realm names 
which differ by more then just lower and upper case rely on a modification to 
krb524d which maps a Kerberos 5 ticket from realm FOO to a Kerberos 4 ticket 
in realm BAR.  This allows user@FOO to appear to be user@bar for the purposes 
of accessing the AFS cell.  As of OpenAFS 1.2.8, support was added to allow 
the immediate use of Kerberos 5 tickets as AFS (2b) tokens. This is the first 
building block necessary to break away from the limitations of Kerberos 4 with 
AFS.  By using Kerberos 5 directly we avoid the security holes inherent in 
Kerberos 4 cross-realm.  We also gain access to cryptographically stronger 
algorithms for authentication and encryption. 

Another reason for using Kerberos 5 directly is because the krb524 service 
runs on a port (4444) which has become increasingly blocked by ISPs.  The port 
was used to spread a worm which attacked Microsoft Windows in the summer of 
2003.  When the port is blocked users find that they are unable to 
authenticate.

Replacing the Kerberos 4 ticket with a Kerberos 5 ticket is a win in all 
situations except when the cell name does not match the realm name and the 
principal names placed into the ACLs are not the principal names from the 
Kerberos 5 ticket.  To support this transition, OpenAFS for Windows in 1.3.72 
adds a new registry value to force the use of krb524d.  However, the 
availability of this option should only be used by individuals until such time 
as their organizations can provide a more permanent solution.


24. The Status Cache (AFS Config Control Panel: Advanced Page) is defined to 
have a maximum number of entries.  Each entry represents a single file or 
directory entry accessed within the AFS file system.  When the maximum number 
of entries are allocated, entries will begin to be reused according to a least 
recently used (LRU) algorithm.  If the number of files or directories being 
accessed repeatedly by your applications is greater then the maximum number of 
entries, your host will begin to experience thrashing of the Status Cache and 
all requests will result in network operations.

If you are experiencing poor performance you might want to increase the 
maximum number of Status Cache entries.  Each entry requires approximately 
1.2K.  Note that the default number of Status Cache entries was increased to 
10,000 starting in 1.3.80.


25. "Netbios over TCP/IP" must be active on the machine in order for 
communication with the AFS Client Service to succeed.  If "Netbios over 
TCP/IP" is disabled on the machine, then communication with the AFS Client 
Service will be impossible.


26. The AFS Client Service and related binaries are digitally signed by 
"Secure Endpoints Inc." beginning with the 1.3.7400 release of OpenAFS for 
Windows.  Starting in the 1.3.7500 release, the AFS Client Service will 
perform a run-time verification check to ensure that all AFS related DLLs 
loaded by the service match the same file version number and were signed by 
the same entity.  This check has been added to prevent the stability problems 
caused by more then one version of AFS being installed on a machine at the 
same time.  Many hours of support time have been wasted tracking down problems 
caused by the mixture of files from different releases.  

The registry.txt file documents the "VerifyServiceSignature" registry value 
which can be used to disable the signature check.  The file version check 
cannot be disabled.


27. The maximum cache size is approximately 1.3GB.  This is the largest 
contiguous block of memory in the 2GB process address space which can be used 
for the memory mapped file.  Due to fragmentation of the process spaced caused 
by the digital signature verification code, any attempt to specify a cache 
size greater then 700MB will result in the automatic disabling of the 
signature check.


28. OpenAFS for Windows implements an SMB server which is used as a gateway to 
the AFS filesystem.  Because of the use of SMB, Windows stores all files into 
AFS using the OEM code pages such as CP437 (United States) or CP850 (Western 
Europe).  These code pages are incompatible with the ISO Latin-1 character set 
typically used as a default on Unix systems in both the United States and 
Western Europe.  Filenames stored by OpenAFS for Windows are therefore 
unreadable on Unix systems if they include any of the following characters:

     [Ç]  128  08/00  200  80  C cedilla
     [ü]  129  08/01  201  81  u diaeresis
     [é]  130  08/02  202  82  e acute
     [â]  131  08/03  203  83  a circumflex
     [ä]  132  08/04  204  84  a diaeresis
     [à]  133  08/05  205  85  a grave
     [å]  134  08/06  206  86  a ring
     [ç]  135  08/07  207  87  c cedilla
     [ê]  136  08/08  210  88  e circumflex
     [ë]  137  08/09  211  89  e diaeresis
     [è]  138  08/10  212  8A  e grave
     [ï]  139  08/11  213  8B  i diaeresis
     [î]  140  08/12  214  8C  i circumflex
     [ì]  141  08/13  215  8D  i grave
     [Ä]  142  08/14  216  8E  A diaeresis
     [Å]  143  08/15  217  8F  A ring
     [É]  144  09/00  220  90  E acute
     [æ]  145  09/01  221  91  ae diphthong
     [Æ]  146  09/02  222  92  AE diphthong
     [ô]  147  09/03  223  93  o circumflex
     [ö]  148  09/04  224  94  o diaeresis
     [ò]  149  09/05  225  95  o grave
     [û]  150  09/06  226  96  u circumflex
     [ù]  151  09/07  227  97  u grave
     [ÿ]  152  09/08  230  98  y diaeresis
     [Ö]  153  09/09  231  99  O diaeresis
     [Ü]  154  09/10  232  9A  U diaeresis
     [ø]  155  09/11  233  9B  o slash
     [£]  156  09/12  234  9C  Pound sterling sign
     [Ø]  157  09/13  235  9D  O slash
     [×]  158  09/14  236  9E  Multiplication sign
     [ƒ]  159  09/15  237  9F  Florin sign

As of 1.3.75, a new registry value, HKLM\SOFTWARE\OpenAFS\Client 
"StoreAnsiFilenames" can be set to instruct OpenAFS for Windows to store 
filenames using the ANSI Code Page instead of the OEM Code Page.  The ANSI 
Code Page is a compatible superset of Latin-1.  This setting is not the 
default setting because making this change would prevent OpenAFS for Windows 
from being able to access filenames containing the above characters which were 
created without this setting.


29. There is a known issue with storing Windows Roaming Profiles when the 
profile contains either directories or files with names which cannot be 
represented in the local OEM character set.  In this case, attempts to write 
the profile back to AFS will fail.  OpenAFS for Windows does not currently 
support UNICODE.  To avoid this problem some sites run logoff scripts 
(assigned by group policy) which rename all files to use only the supported 
characters for the locale.


30. As of 1.3.80 the AFS Cache file is stored by default at %TEMP%\AFSCache in 
a persistent file marked with the Hidden and System attributes.  The 
persistent nature of the data stored in the cache file improves the 
performance of OpenAFS by reducing the number of times data must be read from 
the AFS file servers.


31. Integrated Login (as of 1.3.80) supports the ability to obtain tokens for 
multiple cells.  See the "TheseCells" value in registry.txt.


32. New command line tool:

    afsdacl : Set or reset the DACL to allow starting or stopping
         the afsd service by any ordinary user.

    Usage : afsdacl [-set | -reset] [-show]
          -set   : Sets the DACL
          -reset : Reset the DACL
          -show  : Show current DACL (SDSF)

33. As of 1.3.80, the default @sys name list has been changed to "x86_win32 
i386_w2k i386_nt40" for 32-bit x86 systems.  The default for itanium will be 
"ia64_win64" and "amd64_win64" for amd 64-bit processors.


34. As of 1.3.80, symlinks to \\AFS[\all]\... will now be treated the same as 
symlinks to /afs/...  However, please use /afs/... as the Windows UNC form 
will not work on Unix.


35. As of 1.3.80, OpenAFS for Windows implements the Cache Manager Debugging 
RPC Interface.  The CM debugger can be queried with cmdebug.exe.

Usage: cmdebug -servers <server machine> [-port <IP port>] [-long]
               [-addrs] [-cache] [-help]
Where: -long   print all info
       -addrs  print only host interfaces
       -cache  print only cache configuration


36.  If you are a site which utilizes MIT/Heimdal Kerberos principals to logon 
to Windows via a cross-realm relationship with a multi-domain Windows forest, 
you must enable Windows logon caching unless the workstation is Longhorn Beta 
1 or later.


37. VLDB and File Server Preferences can now be provided initial values using 
registry keys.  This is useful for managed machines in a Windows domain which 
are centrally located (e.g., in a computing lab.)  See registry.txt for 
details on the "Server Preferences" keys.


38. As of 1.3.81, timestamps on files stored in AFS are reported to Windows in 
UTC all year round.  Previously, in locales with daylight savings time, the 
time reported by AFS to Windows when DST is active was UTC+1.  This was done 
to preserve the relative local time for the user.  A file stored at 11:00am 
EST in January would be reported as having been stored at 11:00am EDT in June. 
 Unfortunately, this has the negative side effect of changing the reported 
timestamp from 16:00UTC to 15:00UTC.  Since Windows treats all file times in 
UTC, data synchronization applications which rely on the timestamp would 
believe that all files stored in AFS had changed.  This will no longer be the 
case. 

It should be noted that Unix based operating systems (such as Solaris) do not 
appear to report file times to applications in UTC.  They do preserve the 
relative local time.  This may confuse some users who are used to being able 
to compare the timestamp in an Unix shell with the timestamp from the Windows 
explorer.  During DST, these two times will no longer agree even though they 
are in fact describing the same time.


39. If the installer refuses to install and complains about an RPC 
configuration error, check to ensure that the following registry entries are 
present and that they refer to the dll "rpcrt4.dll":

   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_np"
   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_ip_tcp"
   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncadg_ip_udp"
   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncadg_ip_http"


40. 1.3.83 adds a new command, "fs minidump".  This command can be used at any 
time to generate a mini dump file containing the current stack of the 
afsd_service.exe process.   This output can be very helpful when debugging the 
AFS Client Service when it is unresponsive to SMB/CIFS requests.


------------------------------------------------------------------------

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.

* 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.

* 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.


* 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.

  An alternatve option to the use of "fs trace" is to use a tool such as
  Sysinternal's DbgView to capture real-time debugging output.  Set Bit 2
  of the TraceOption value in the registry to activate.

    [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
    REG_DWORD   TraceOption = 0x04


* 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.


* Integrated Logon debugging (TraceOption registry key)

  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 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".


* 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.  


* Cache Manager debugging (cmdebug)

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


* 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>
  

------------------------------------------------------------------------

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: 
   - click Start > Run...  
   - type drwtsn32 <enter>. 
   - Select either a Crash Dump Type: Mini or Full. 
   - Clear Dump Symbol Table
   - Clear Append to Existing Log file. 
   - Check Dump All Thread Contexts.
   - Check Create Crash Dump File
 * Next run the monitoring module of Dr. Watson: 
   - click Start > Run...
   - 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.

Once you have the Dr. Watson's logfile and minidump, zip them and send them as 
attachments with your e-mail to openafs-bugs@openafs.org.

When reporting a error, please be sure to include the version of OpenAFS.


------------------------------------------------------------------------

How to Contribute to the Development of OpenAFS for Windows:

Contributions to the development of OpenAFS for Windows are needed. 
Contributions may take many forms including cash donations, support contracts, 
donated developer time, and even donated tech writer time.

If you wish to be involved in OpenAFS for Windows development please join the 
openafs-win32-devel@openafs.org mailing list.

  https://lists.openafs.org/mailman/listinfo/openafs-win32-devel

User questions should be sent to the openafs-info@openafs.org mailing list.  

  https://lists.openafs.org/mailman/listinfo/openafs-info

You must join the mailing lists if you wish to post to the list without 
incurring a moderation delay.