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