windows-version-1-5-20050817
[openafs.git] / doc / txt / winnotes / afs-install-notes.txt
1 OpenAFS for Windows 1.5.0000 Installation Notes
2 -----------------------------------------------
3
4 OpenAFS for Windows 1.5.0000 is an unstable development client available for 
5 Microsoft Windows operating systems.  It can be installed either as
6 a new installation or an upgrade from previous versions of OpenAFS
7 for Windows or IBM AFS for Windows.  Installers are provided in two
8 forms:
9
10   * an executable (.exe) that is based upon the Nullsoft Scriptable
11     Installation System, or
12
13   * a Windows Installer package (.msi) that is built using WiX and
14     can be customized for organizations via the use of MSI Transforms
15     (see msi-deployment-guide.txt)
16
17 System Requirements:
18
19 Operating System: Windows 2000, 2000 Server, XP Home, XP Pro, 2003 Server.
20 64-bit versions of Windows and Windows Vista are not supported in this 
21 release.
22
23 Disk Space: up to 60mb required for the OpenAFS binaries plus 100MB 
24 for the default AFSCache file.   (The size of the AFSCache file may
25 be adjusted via the Registry after installation.)
26
27 Additional Softare:  MIT Kerberos for Windows 2.6.x if Kerberos 5 
28 authentication support is desired.
29
30 1. The Kerberos 4 infrastructure on which the 1.2 series is reliant is no 
31 longer secure.  Cross-realm Kerberos is very important in the AFS context and 
32 most sites have or are migrating to Kerberos 5 environments.  The 1.3 series 
33 integrates with the MIT Kerberos for Windows 2.6.x product to provide Kerberos 
34 5 functionality including the ability to auto-renew credentials and obtain 
35 single sign-on capabilities with the Microsoft Windows Kerberos Logon Service.
36
37 As of 1.3.65, the OpenAFS client will directly use Kerberos 5 tickets as 
38 tokens if KFW is installed.  The client requires that all of the AFS Servers 
39 with which it communicates support the use of Kerberos 5 tickets as tokens 
40 (aka 2b tokens). This means that all of the AFS servers must be running 
41 OpenAFS release 1.2.8 or higher.  Transarc servers do not support Kerberos 5 
42 tickets as tokens.
43
44 When using a Microsoft Windows Active Directory as the KDC which issues the 
45 service ticket for the AFS cell there are two things to consider.  First, the 
46 Kerberos 5 tickets issued by Active Directory can be quite large when compared 
47 to tickets issued by a traditional KDC due to the incorporation of 
48 authorization data in the PAC.  If this is your situation you either must 
49 modify your 1.2.x servers to support tokens larger than a few hundred bytes; 
50 or install the 1.3.64 or higher release on your servers.  Second, Windows 2003 
51 Active Directory will issue service tickets utilizing the DES-CBC-MD5 enctype. 
52 OpenAFS releases older than 1.3.64 will not properly support this enctype.
53
54
55 2. The AFS Client Service does not provide robust behavior in an environment 
56 with a plug-n-play network environment.  Changes to the number of network 
57 adapters or the assigned IP addresses will cause the service to panic.  The 
58 recommended work around for this problem is to install the Microsoft Loopback 
59 Adapter on the machine.  When the MLA is installed with a static IP address 
60 the AFS Client Service will bind only to the loopback and not be affected by 
61 changes to state of other network adapters installed on the system.  
62
63 Starting in the 1.3.65 release the installers provided by OpenAFS.org will 
64 install the Microsoft Loopback Adapter for you with a name of "AFS" and a 
65 pre-assigned IP address in the 10.x.x.x range.
66
67 One of the benefits of using the MLA is that the NETBIOS names used for the 
68 AFS Client's SMB server do not have to be published on any adapter other than 
69 the MLA.  This means that the names no longer need to be unique.  When the MLA 
70 is in use, the NETBIOS name associated with the AFS Client Service is simply 
71 "AFS".  When the MLA is not in use the NETBIOS name is "MACHINE-AFS".
72
73 When the MLA is installed, UNC paths of the form \\AFS\cellname\path may be 
74 used.
75
76 The MLA is installed with a binding to "Client for Microsoft Networks" but not 
77 to "File and Printer Sharing for Microsoft Networks".  If you fail to bind 
78 "Client Microsoft Networks" you will not be able to access the AFS Client 
79 Service when the machine is disconnected from the network.  If you bind "File 
80 and Printer Sharing ..." there will be a service type collision between the 
81 name "AFS" and the name of the machine on the published IP Address.  This will 
82 result in a failure to be able to access files in AFS.  The "NET VIEW" command 
83 will return a "System Error 52" message when this conflict exists.  To correct 
84 the problem:
85
86  * stop the AFS Client Service
87  * bind the "Client for Microsoft Networks" to the MLA
88  * unbind "File and Printer Sharing for Microsoft Networks" from the MLA
89  * Disable and then Enable the MLA
90  * start the AFS Client Service
91
92
93 3. Traditionally, when the AFS Client Service starts it must be able to access 
94 the "root.afs" volume of the default cell.  The "root.afs" volume contains a 
95 set of read-only and read-write mount points to the "root.cell" volumes of 
96 various cells the administrator of the default cell believes should be 
97 accessible.  If the "root.afs" volume is inaccessible when the client service 
98 is started, the service will panic. Since many users now use laptops or 
99 otherwise operate in disconnected environments in which a VPN may be needed to 
100 access the cell's servers, it is often the case that the "root.afs" volume for 
101 the default cell is not reachable and the AFS Client Service will not 
102 successfully start. 
103  
104 The OpenAFS Client Service now supports a fake "root.afs" volume which is 
105 dynamically constructed when the service starts.  This mode is called 
106 Freelance mode.  Freelance mode is turned on by default.
107
108 The contents of the fake "root.afs" volume are constructed dynamically as 
109 cells are accessed.  When the fake "root.afs" volume is constructed it will 
110 only contain two mount points: a read-only and read-write mount point used to 
111 access the "root.cell" volume of the default AFS cell.  Any attempt to access 
112 a valid cell name will automatically result in a new mount point being created 
113 in the fake "root.afs" volume.  If the cellname begins with a "." the mount 
114 point will be read-write; otherwise the mount point will be read-only.  These 
115 mount points are preserved in the registry at key:
116
117   HKLM\SOFTWARE\OpenAFS\Client\Freelance
118
119 Additional mount points may be manually created using the "fs mkmount" 
120 command.  Mount points may be removed using the "fs rmmount" command.
121
122     >fs mkmount \\AFS\all\athena.mit.edu root.cell athena.mit.edu
123     >fs mkmount \\AFS\all\.athena.mit.edu root.cell athena.mit.edu -rw
124     >fs rmmount \\AFS\all\athena.mit.edu
125     >fs rmmount \\AFS\all\.athena.mit.edu
126
127 Beginning in 1.3.74, the Freelance fake root.afs volume will support the 
128 creation of symlinks.
129
130   >symlink make \\afs\all\link \\afs\all\athena.mit.edu\user\j\a\jaltman
131
132   >symlink list \\afs\all\link
133   '\\afs\all\link' is a symlink to 'athena.mit.edu\user\j\a\jaltman'
134
135   >symlink rm \\afs\all\link
136
137 The symlinks are stored in the registry at:
138
139   HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks 
140      
141
142 4. The OpenAFS for Windows client will use AFSDB DNS records to discover cell 
143 information when it is not located in the local CellServDB file 
144 (\%PROGRAMFILES%\OpenAFS\Client\CellServDB).
145
146
147 5. OpenAFS for Windows 1.3.72 only supports Windows 2000, Windows XP, and 
148 Windows 2003.  Windows NT 4.0 and the entire Windows 9x/Me line are no longer 
149 supported.  Older releases of OpenAFS are available for download if those 
150 operating systems must be supported.  The last version with support for Win9x 
151 is 1.2.2b.  The last version with support for Windows NT 4.0 is 1.2.10.
152
153
154 6. OpenAFS for Windows installs a WinLogon Network Provider to provide 
155 Integrated Logon (Single Sign-on) functionality. Integrated Logon can be used 
156 when the Windows username and password match the username and password 
157 associated with the default cell's Kerberos realm.  For example, if the 
158 windows username is "jaltman" and the default cell is "athena.mit.edu", then 
159 Integrated Logon can be successfully used if the windows password matches the 
160 password used for the Kerberos principal "jaltman@ATHENA.MIT.EDU".
161
162 Integrated Logon is required if you desire the ability to store roaming user 
163 profiles within the AFS file system.  OpenAFS does not provide tools for 
164 synchronizing the Windows and Kerberos user accounts and passwords.
165
166 If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain 
167 tokens.  Otherwise, Kerberos 4 is used.
168
169 There is a High Security mode for use with Integrated Logon when multiple 
170 users will share a single machine.  There are known problems with this mode. 
171 In particular, if you are using this mode it is crucial that new AFS tokens 
172 not be obtained after the logon session starts except via the AFS Systray tool 
173 as started by the AFS Network Provider.  If the AFS Systray tool is stopped 
174 you must log off to obtain new tokens.  Do not use external tools such as 
175 "aklog.exe" if High Security mode is turned on. As of 1.3.70, OpenAFS supports 
176 Authenticated SMB connections which removes the need for High Security mode. 
177 DO NOT USE IT!!!!! 
178
179 Starting in 1.3.83, when Integrated Logon is used in conjunction with KFW, the 
180 Kerberos 5 tickets obtained during the process of generating AFS tokens are 
181 preserved and stored into the default ccache within the user logon session.
182
183 What Integrated Logon does not do:
184  (a) Integrated Logon does not have the ability to cache the user's 
185      username and password for the purpose of obtaining tokens if the
186      Kerberos KDC is inaccessible at logon time.
187
188
189 7. The AFS Systray tool (afscreds.exe) supports several command line 
190 options: 
191
192     -A = autoinit 
193     -E = force existing afscreds to exit
194     -I = install startup shortcut
195     -M = renew drive maps 
196     -N = IP address change detection 
197     -Q = quiet mode.  do not display start service dialog
198          if afsd_service is not already running
199     -S = show tokens dialog on startup
200     -U = uninstall startup shortcut
201     -X = test and do map share
202     -Z = unmap drives
203     -: = magic parameter for high security mode 
204
205 autoinit will result in automated attempts to acquire AFS tokens when 
206 afscreds.exe is started.  afscreds.exe will attempt to utilize tickets stored 
207 in the MSLSA credentials cache; any existing CCAPI credentials cache; and 
208 finally display an Obtain Tokens dialog to the user.  When used in combination 
209 with IP address change detection, afscreds.exe will attempt to acquire AFS 
210 tokens whenever the IP address list changes and the Kerberos KDC is 
211 accessible.
212
213 The renew drive maps option is used to ensure that the user drive maps 
214 constructed via the AFS tools (not NET USE) are re-constructed each time 
215 afscreds.exe is started.
216
217 By default afscreds.exe is configured by the OpenAFS.org installers to use -A 
218 -N -M -Q as startup options.  Currently, there is no UI to change this 
219 selection after install time although these options may be altered via the 
220 registry either per machine or per user.  See AfscredsShortcutParams in 
221 registry.txt.
222
223
224 8. As of 1.3.71, the OpenAFS for Windows client supports a local Windows 
225 authorization group called "AFS Client Admins".  This group is used in place 
226 of the "Administrators" group to determine which users are allowed to modify 
227 the AFS Client Service configuration via either afs_config.exe or fs.exe.  For 
228 example, the following fs.exe commands are now restricted to members of the 
229 "AFS Client Admins" group:
230
231     - checkservers with a non-zero timer value
232     - setcachesize
233     - newcell
234     - sysname with a new sysname list
235     - exportafs
236     - setcell
237     - setserverprefs
238     - storebehind
239     - setcrypt
240     - cscpolicy
241     - trace
242
243 Setting the default sysname for a machine should be done via the registry and 
244 not via "fs sysname".
245
246 The local "SYSTEM" account is always a member of the "AFS Client Admins" 
247 group.
248
249 The initial membership of the "AFS Client Admins" group when created by the 
250 installer is equivalent to the local "Administrators" group.  If a user is 
251 added to the "Administrators" group after the creation of the "AFS Client 
252 Admin" group, that user will not be an AFS Client Administrator.  Only users 
253 that are members of the "AFS Client Admins" group are AFS Client 
254 Administrators.
255
256
257 9. The AFS Client should support UNC paths everywhere.  Power users that make 
258 extensive use of the command line shell, cmd.exe, might want to consider using 
259 JP Software's 4NT command processor.  Unlike cmd.exe, 4NT does fully support 
260 UNC paths and can use a UNC path as the default device.
261
262
263 10. The AFS Client ships with its own version of aklog.exe which should be 
264 used in preference to those obtained by third party sources.  The OpenAFS 
265 aklog.exe supports Kerberos 5 as well as the ability to auto-generate pts IDs 
266 for user's obtaining tokens to foreign cells.
267
268 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
269              [[-p | -path] pathname]
270              [-noprdb] [-force]
271              [-5 | -4]
272
273    -d gives debugging information.
274    krb_realm is the kerberos realm of a cell.
275    pathname is the name of a directory to which you wish to authenticate.
276    -noprdb means don't try to determine AFS ID.
277    -5 or -4 selects whether to use Kerberos V or Kerberos IV.
278       (default is Kerberos V)
279    No commandline arguments means authenticate to the local cell.
280
281
282 11. The AFS Server functionality provided with OpenAFS 1.3.72 might work but 
283 should be considered highly experimental.  It has not been thoroughly tested. 
284 Any data which would cause pain if lost should not be stored in an OpenAFS 
285 Server on Windows.
286
287 A few notes on the usage of the AFS Client Service if it is going to be 
288 used with the OpenAFS AFS Server:
289
290 (a) When the AFS Server is installed Freelance mode must be turned off.  
291
292 (b) The AFS Server and related tools only support the built in kaserver
293 (Kerberos IV).  If the AFS Server is being used, MIT Kerberos for Windows
294 should not be used.
295
296
297 12. The OpenAFS for Windows installers now include Symbol information which 
298 should be installed if you are experiencing problems and need to send crash 
299 reports.  This is true in both the release and the debug versions of the 
300 installers.  The differences between the release and debug versions are 
301 whether or not the binaries were compiled with optimization; whether the debug 
302 symbols are installed by default; and whether additional debug statements were 
303 compiled into the binaries.
304
305
306 13. OpenAFS for Windows does not support files larger than 2GB.  This is due 
307 to the lack of support for the Unicode version of the SMB/CIFS protocol.
308
309
310 14. Local RPC is used as the default RPC mechanism for setting tokens.  TCP 
311 RPC is required to be installed and is used for debugging and other functions.
312
313
314 15. The OpenAFS for Windows installer by default activates a weak form of 
315 encrypted data transfer between the AFS client and the AFS servers.  This is 
316 often referred to as "fcrypt" mode.
317
318
319 16. OpenAFS 1.3.71 adds support for authenticated SMB connections using either 
320 NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...).  In previous versions of OpenAFS 
321 the SMB connections were unauthenticated which left open the door for several 
322 security holes which could be used to obtain access to other user's tokens on 
323 shared machines.  With the introduction of authenticated SMB connections the 
324 so called High Security mode should no longer be used.  
325
326 When GSS SPNEGO results in a Kerberos 5 authentication, the Windows SMB client 
327 will attempt to retrieve service tickets for "cifs/afs@REALM" (if the loopback 
328 adapter is in use) or "cifs/machine-afs@REALM" (if the loopback adapter is not 
329 being used).  It is extremely important that this service principal not exist 
330 in the KDC database.   If the request for this ticket fails, a subsequent 
331 request for "cifs/HOST$@REALM" will be issued.  This service principal should 
332 exist in the KDC database.  The key associated with this service principal 
333 must match the key assigned to "host/machine@REALM".  If the local machine is 
334 part of a Windows Domain this will all be taken care of for you.  If the local 
335 machine is using a non-MS KDC for authentication, then your KDC administrator 
336 will have to add these service principals to the list of principals to be 
337 maintained for each host.
338
339
340 17. As of 1.3.70, INI files are no longer used for the storage of AFS 
341 configuration data.  No longer are there any AFS related files stored in the 
342 %WINDIR% directory.  The CellServDB file is no longer called "afsdsbmt.ini" 
343 and it is stored in the OpenAFS\Client directory.  The afs_freelance.ini and 
344 afsdsbmt.ini file data has been moved to the registry.  
345
346 IMPORTANT: while the CellServDB file location and freelance mountpoint data 
347 will be automatically migrated; there is no mechanism for automatic migration 
348 of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.
349
350
351 18. As of 1.3.70, the OpenAFS Client is compatible with Windows XP SP2 and 
352 Windows 2003 SP1.  The Internet Connection Firewall will be automatically 
353 adjusted to allow the receipt of incoming callback messages from the AFS file 
354 server.  In addition, the appropriate Back Connection entries are added to the 
355 registry to allow SMB authentication to be performed across the loopback 
356 connection.
357
358
359 19. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote Admin 
360 Protocol which provides browsing of server and share information. This 
361 significantly enhances the interoperability of AFS volumes within the Explorer 
362 Shell and Microsoft Office applications.
363
364
365 20. OpenAFS will now automatically forget a user's tokens upon Logoff unless 
366 the user's profile was loaded from an AFS volume.  In this situation there is 
367 no mechanism to determine when the profile has been successfully written back 
368 to the network.  It is therefore unsafe to release the user's tokens.  Whether 
369 or not the profile has been loaded from the registry can be determined for 
370 Local Accounts, Active Directory accounts and NT4 accounts.
371
372 If there is a need to disable this functionality, the LogoffPreserveTokens 
373 registry value (see registry.txt) can be used.
374                                                    
375
376 21. Terminal Server installations. 
377 When installing the NSIS (.exe) installer under Terminal Server, you must 
378 execute it from within the Add/Remove Programs Control Panel.  Failure to do 
379 so will result in AFS not running properly.  The AFS Server should not be 
380 installed on a machine with Terminal Server installed.
381
382
383 22. AFS is a Unix native file system.  As such the OpenAFS client attempts to 
384 treat the files stored in AFS as they would be on Unix.  File and directory 
385 names beginning with a "." are automatically given the Hidden attribute so 
386 they will not normally be displayed.
387
388
389 23. Some organizations which have AFS cell names and Kerberos realm names 
390 which differ by more then just lower and upper case rely on a modification to 
391 krb524d which maps a Kerberos 5 ticket from realm FOO to a Kerberos 4 ticket 
392 in realm BAR.  This allows user@FOO to appear to be user@bar for the purposes 
393 of accessing the AFS cell.  As of OpenAFS 1.2.8, support was added to allow 
394 the immediate use of Kerberos 5 tickets as AFS (2b) tokens. This is the first 
395 building block necessary to break away from the limitations of Kerberos 4 with 
396 AFS.  By using Kerberos 5 directly we avoid the security holes inherent in 
397 Kerberos 4 cross-realm.  We also gain access to cryptographically stronger 
398 algorithms for authentication and encryption. 
399
400 Another reason for using Kerberos 5 directly is because the krb524 service 
401 runs on a port (4444) which has become increasingly blocked by ISPs.  The port 
402 was used to spread a worm which attacked Microsoft Windows in the summer of 
403 2003.  When the port is blocked users find that they are unable to 
404 authenticate.
405
406 Replacing the Kerberos 4 ticket with a Kerberos 5 ticket is a win in all 
407 situations except when the cell name does not match the realm name and the 
408 principal names placed into the ACLs are not the principal names from the 
409 Kerberos 5 ticket.  To support this transition, OpenAFS for Windows in 1.3.72 
410 adds a new registry value to force the use of krb524d.  However, the 
411 availability of this option should only be used by individuals until such time 
412 as their organizations can provide a more permanent solution.
413
414
415 24. The Status Cache (AFS Config Control Panel: Advanced Page) is defined to 
416 have a maximum number of entries.  Each entry represents a single file or 
417 directory entry accessed within the AFS file system.  When the maximum number 
418 of entries are allocated, entries will begin to be reused according to a least 
419 recently used (LRU) algorithm.  If the number of files or directories being 
420 accessed repeatedly by your applications is greater then the maximum number of 
421 entries, your host will begin to experience thrashing of the Status Cache and 
422 all requests will result in network operations.
423
424 If you are experiencing poor performance you might want to increase the 
425 maximum number of Status Cache entries.  Each entry requires approximately 
426 1.2K.  Note that the default number of Status Cache entries was increased to 
427 10,000 starting in 1.3.80.
428
429
430 25. "Netbios over TCP/IP" must be active on the machine in order for 
431 communication with the AFS Client Service to succeed.  If "Netbios over 
432 TCP/IP" is disabled on the machine, then communication with the AFS Client 
433 Service will be impossible.
434
435
436 26. The AFS Client Service and related binaries are digitally signed by 
437 "Secure Endpoints Inc." beginning with the 1.3.7400 release of OpenAFS for 
438 Windows.  Starting in the 1.3.7500 release, the AFS Client Service will 
439 perform a run-time verification check to ensure that all AFS related DLLs 
440 loaded by the service match the same file version number and were signed by 
441 the same entity.  This check has been added to prevent the stability problems 
442 caused by more then one version of AFS being installed on a machine at the 
443 same time.  Many hours of support time have been wasted tracking down problems 
444 caused by the mixture of files from different releases.  
445
446 The registry.txt file documents the "VerifyServiceSignature" registry value 
447 which can be used to disable the signature check.  The file version check 
448 cannot be disabled.
449
450
451 27. The maximum cache size is approximately 1.3GB.  This is the largest 
452 contiguous block of memory in the 2GB process address space which can be used 
453 for the memory mapped file.  Due to fragmentation of the process spaced caused 
454 by the digital signature verification code, any attempt to specify a cache 
455 size greater then 700MB will result in the automatic disabling of the 
456 signature check.
457
458
459 28. OpenAFS for Windows implements an SMB server which is used as a gateway to 
460 the AFS filesystem.  Because of the use of SMB, Windows stores all files into 
461 AFS using the OEM code pages such as CP437 (United States) or CP850 (Western 
462 Europe).  These code pages are incompatible with the ISO Latin-1 character set 
463 typically used as a default on Unix systems in both the United States and 
464 Western Europe.  Filenames stored by OpenAFS for Windows are therefore 
465 unreadable on Unix systems if they include any of the following characters:
466
467      [Ç]  128  08/00  200  80  C cedilla
468      [ü]  129  08/01  201  81  u diaeresis
469      [é]  130  08/02  202  82  e acute
470      [â]  131  08/03  203  83  a circumflex
471      [ä]  132  08/04  204  84  a diaeresis
472      [à]  133  08/05  205  85  a grave
473      [å]  134  08/06  206  86  a ring
474      [ç]  135  08/07  207  87  c cedilla
475      [ê]  136  08/08  210  88  e circumflex
476      [ë]  137  08/09  211  89  e diaeresis
477      [è]  138  08/10  212  8A  e grave
478      [ï]  139  08/11  213  8B  i diaeresis
479      [î]  140  08/12  214  8C  i circumflex
480      [ì]  141  08/13  215  8D  i grave
481      [Ä]  142  08/14  216  8E  A diaeresis
482      [Å]  143  08/15  217  8F  A ring
483      [É]  144  09/00  220  90  E acute
484      [æ]  145  09/01  221  91  ae diphthong
485      [Æ]  146  09/02  222  92  AE diphthong
486      [ô]  147  09/03  223  93  o circumflex
487      [ö]  148  09/04  224  94  o diaeresis
488      [ò]  149  09/05  225  95  o grave
489      [û]  150  09/06  226  96  u circumflex
490      [ù]  151  09/07  227  97  u grave
491      [ÿ]  152  09/08  230  98  y diaeresis
492      [Ö]  153  09/09  231  99  O diaeresis
493      [Ü]  154  09/10  232  9A  U diaeresis
494      [ø]  155  09/11  233  9B  o slash
495      [£]  156  09/12  234  9C  Pound sterling sign
496      [Ø]  157  09/13  235  9D  O slash
497      [×]  158  09/14  236  9E  Multiplication sign
498      [ƒ]  159  09/15  237  9F  Florin sign
499
500 As of 1.3.75, a new registry value, HKLM\SOFTWARE\OpenAFS\Client 
501 "StoreAnsiFilenames" can be set to instruct OpenAFS for Windows to store 
502 filenames using the ANSI Code Page instead of the OEM Code Page.  The ANSI 
503 Code Page is a compatible superset of Latin-1.  This setting is not the 
504 default setting because making this change would prevent OpenAFS for Windows 
505 from being able to access filenames containing the above characters which were 
506 created without this setting.
507
508
509 29. There is a known issue with storing Windows Roaming Profiles when the 
510 profile contains either directories or files with names which cannot be 
511 represented in the local OEM character set.  In this case, attempts to write 
512 the profile back to AFS will fail.  OpenAFS for Windows does not currently 
513 support UNICODE.  To avoid this problem some sites run logoff scripts 
514 (assigned by group policy) which rename all files to use only the supported 
515 characters for the locale.
516
517
518 30. As of 1.3.80 the AFS Cache file is stored by default at %TEMP%\AFSCache in 
519 a persistent file marked with the Hidden and System attributes.  The 
520 persistent nature of the data stored in the cache file improves the 
521 performance of OpenAFS by reducing the number of times data must be read from 
522 the AFS file servers.
523
524
525 31. Integrated Login (as of 1.3.80) supports the ability to obtain tokens for 
526 multiple cells.  See the "TheseCells" value in registry.txt.
527
528
529 32. New command line tool:
530
531     afsdacl : Set or reset the DACL to allow starting or stopping
532          the afsd service by any ordinary user.
533
534     Usage : afsdacl [-set | -reset] [-show]
535           -set   : Sets the DACL
536           -reset : Reset the DACL
537           -show  : Show current DACL (SDSF)
538
539 33. As of 1.3.80, the default @sys name list has been changed to "x86_win32 
540 i386_w2k i386_nt40" for 32-bit x86 systems.  The default for itanium will be 
541 "ia64_win64" and "amd64_win64" for amd 64-bit processors.
542
543
544 34. As of 1.3.80, symlinks to \\AFS[\all]\... will now be treated the same as 
545 symlinks to /afs/...  However, please use /afs/... as the Windows UNC form 
546 will not work on Unix.
547
548
549 35. As of 1.3.80, OpenAFS for Windows implements the Cache Manager Debugging 
550 RPC Interface.  The CM debugger can be queried with cmdebug.exe.
551
552 Usage: cmdebug -servers <server machine> [-port <IP port>] [-long]
553                [-addrs] [-cache] [-help]
554 Where: -long   print all info
555        -addrs  print only host interfaces
556        -cache  print only cache configuration
557
558
559 36.  If you are a site which utilizes MIT/Heimdal Kerberos principals to logon 
560 to Windows via a cross-realm relationship with a multi-domain Windows forest, 
561 you must enable Windows logon caching unless the workstation is Longhorn Beta 
562 1 or later.
563
564
565 37. VLDB and File Server Preferences can now be provided initial values using 
566 registry keys.  This is useful for managed machines in a Windows domain which 
567 are centrally located (e.g., in a computing lab.)  See registry.txt for 
568 details on the "Server Preferences" keys.
569
570
571 38. As of 1.3.81, timestamps on files stored in AFS are reported to Windows in 
572 UTC all year round.  Previously, in locales with daylight savings time, the 
573 time reported by AFS to Windows when DST is active was UTC+1.  This was done 
574 to preserve the relative local time for the user.  A file stored at 11:00am 
575 EST in January would be reported as having been stored at 11:00am EDT in June. 
576  Unfortunately, this has the negative side effect of changing the reported 
577 timestamp from 16:00UTC to 15:00UTC.  Since Windows treats all file times in 
578 UTC, data synchronization applications which rely on the timestamp would 
579 believe that all files stored in AFS had changed.  This will no longer be the 
580 case. 
581
582 It should be noted that Unix based operating systems (such as Solaris) do not 
583 appear to report file times to applications in UTC.  They do preserve the 
584 relative local time.  This may confuse some users who are used to being able 
585 to compare the timestamp in an Unix shell with the timestamp from the Windows 
586 explorer.  During DST, these two times will no longer agree even though they 
587 are in fact describing the same time.
588
589
590 39. If the installer refuses to install and complains about an RPC 
591 configuration error, check to ensure that the following registry entries are 
592 present and that they refer to the dll "rpcrt4.dll":
593
594    HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_np"
595    HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_ip_tcp"
596    HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncadg_ip_udp"
597    HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncadg_ip_http"
598
599
600 40. 1.3.83 adds a new command, "fs minidump".  This command can be used at any 
601 time to generate a mini dump file containing the current stack of the 
602 afsd_service.exe process.   This output can be very helpful when debugging the 
603 AFS Client Service when it is unresponsive to SMB/CIFS requests.
604
605
606 ------------------------------------------------------------------------
607
608 How to Debug Problems with OpenAFS for Windows:
609
610 OpenAFS for Windows provides a wide range of tools to assist you in debugging 
611 problems.  The techniques available to you are varied because of the wide 
612 range of issues that have been discovered over the years.
613
614 * pioctl debugging (IoctlDebug registry key)
615
616   pioctl (path-based ioctl) calls are used by various tools to 
617   communicate with the AFS Client Service.  Some of the operations performed
618   include:
619
620   - setting/querying tokens  (tokens.exe, aklog.exe, afscreds.exe)
621   - setting/querying ACLs 
622   - setting/querying cache parameters
623   - flushing files or volumes
624   - setting/querying server preferences
625   - querying path location
626   - checking the status of servers and volumes
627   - setting/querying the sysname list
628
629   pioctl calls are implemented by writing to a special UNC path that
630   is processed by the AFS Client Service.   If there is a failure to 
631   communicate with the AFS Client Service via SMB/CIFS, it will be 
632   impossible to perform any of the above operations.   
633
634   To assist in debugging these problems, the registry value:
635
636         [HKLM\SOFTWARE\OpenAFS\Client]
637         REG_DWORD:  IoctlDebug   = 0x01
638
639   should be set.  Then any of the commands that perform pioctl calls should
640   be executed from the command prompt.  With this key set the pioctl library
641   will generate debugging output to stderr.  The output will contain the
642   Win32 API calls executed along with their most important parameters and 
643   their return code.   The MSDN Library and the Microsoft KnowledgeBase can
644   be used as a reference to help you determine the configuration probem with
645   your system.
646
647 * afsd_service initialization log (%WinDir%\TEMP\afsd_init.log)
648
649   Every time the AFS Client Service starts it appends data about its progress
650   and configuration to a file.  This file provides information crucial to
651   determining why the service cannot start when there are problems.  When
652   the process terminates due to a panic condition it will write to this 
653   file the source code file and line number of the error.  In many cases 
654   the panic condition is due to a misconfiguration of the machine.  In other
655   cases it might be due to a programming error in the software.  
656   A quick review of the location in the source code will quickly reveal 
657   the reason for the termination.
658
659
660 * afsd_service debug logs (fs trace {-on, -off, -dump} -> 
661   %WinDir%\TEMP\afsd.log)
662
663   When attempting to debug the behavior of the SMB/CIFS Server and the
664   Cache Manager it is often useful to examine a log of the operations
665   being performed.  While running the AFS Client Service keeps an in memory
666   log of many of its actions.   The default number of actions preserved
667   at any one time is 5000.  This can be adjusted with the registry value:
668
669     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
670     REG_DWORD  TraceBufferSize 
671
672   A restart of the service is necessary when adjusting this value.   
673   Execute "fs trace -on" to clear to the log and "fs trace -dump" to
674   output the contents of the log to the file.
675
676
677 * Microsoft MiniDumps (fs minidump -> %WinDir%\TEMP\afsd.dmp)
678
679   If the AFS Client Service become unresponsive to any form of communication
680   there may be a serious error that can only be debugged by someone with 
681   access to the source code and a debugger.   The "fs minidump" command can
682   be used to force the generation of a MiniDump file containing the state
683   of all of the threads in the AFS Client Service process.
684
685
686 * Integrated Logon debugging (TraceOption registry key)
687
688   If you are having trouble with the Integrated Logon operations 
689   it is often useful to be able to obtain a log of what it is attempting
690   to do.   The registry value:
691
692     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
693     REG_DWORD   TraceOption = 0x01
694
695   will instruct the Integrated Logon Network Provider and Event Handlers
696   to log information to the Windows Event Log: Application under the name
697   "AFS Logon".
698
699
700 * RX (AFS RPC) debugging (rxdebug)
701
702   The rxdebug.exe tool can be used to query a variety of information 
703   about the AFS services installed on a given machine.  The port for
704   the AFS Cache Manager is 7001.  
705
706
707 * Cache Manager debugging (cmdebug)
708
709   The cmdebug.exe tool can be used to query the state of the AFS Cache
710   Manager on a given machine.
711
712
713 * Persistent Cache consistency check
714
715   The persistent cache is stored in a Hidden System file at 
716   %WinDir%\TEMP\AFSCache.  If there is a problem with the persistent 
717   cache that prevent the AFS Client Service from being able to start
718   a validation check on the file can be performed.
719
720     afsd_service.exe --validate-cache <cache-path>
721   
722
723 ------------------------------------------------------------------------
724
725 Reporting Bugs:
726
727 Bug reports should be sent to openafs-bugs@openafs.org.  Please include as 
728 much information as possible about the issue.  If you are reporting a crash, 
729 please install the debugging symbols by re-running the installer.  If a dump 
730 file is available for the problem, %WINDIR%\TEMP\afsd.dmp, include it along 
731 with the AFS Client Trace file  %WINDIR%\TEMP\afsd.log.  The AFS Client 
732 startup log is %WINDIR%\TEMP\afsd_init.log.  Send the last continuous block of 
733 log information from this file.
734
735 Configuring DrWatson to generate dump files for crashes:
736
737  * Run drwtsn32.exe to configure or to identify where the log and the crash dump 
738    files are created: 
739    - click Start > Run...  
740    - type drwtsn32 <enter>. 
741    - Select either a Crash Dump Type: Mini or Full. 
742    - Clear Dump Symbol Table
743    - Clear Append to Existing Log file. 
744    - Check Dump All Thread Contexts.
745    - Check Create Crash Dump File
746  * Next run the monitoring module of Dr. Watson: 
747    - click Start > Run...
748    - type drwatson <enter>. 
749    - Once a crash happens, Dr. Watson generates a dump file and a report in the 
750      log file, including the address of the crash and the stack dump.
751
752 Once you have the Dr. Watson's logfile and minidump, zip them and send them as 
753 attachments with your e-mail to openafs-bugs@openafs.org.
754
755 When reporting a error, please be sure to include the version of OpenAFS.
756
757
758 ------------------------------------------------------------------------
759
760 How to Contribute to the Development of OpenAFS for Windows:
761
762 Contributions to the development of OpenAFS for Windows are needed. 
763 Contributions may take many forms including cash donations, support contracts, 
764 donated developer time, and even donated tech writer time.
765
766 If you wish to be involved in OpenAFS for Windows development please join the 
767 openafs-win32-devel@openafs.org mailing list.
768
769   https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
770
771 User questions should be sent to the openafs-info@openafs.org mailing list.  
772
773   https://lists.openafs.org/mailman/listinfo/openafs-info
774
775 You must join the mailing lists if you wish to post to the list without 
776 incurring a moderation delay.
777