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