1 OpenAFS for Windows 1.3.78 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.
15 1. The Kerberos 4 infrastructure on which the 1.2 series is reliant is no
16 longer secure. Cross-realm Kerberos is very important in the AFS context and
17 most sites have or are migrating to Kerberos 5 environments. The 1.3 series
18 integrates with the MIT Kerberos for Windows 2.6.x product to provide Kerberos
19 5 functionality including the ability to auto-renew credentials and obtain
20 single sign-on capabilities with the Microsoft Windows Kerberos Logon Service.
22 As of 1.3.65, the OpenAFS client will directly use Kerberos 5 tickets as tokens if
23 KFW is installed. The client requires that all of the AFS Servers with which it
24 communicates support the use of Kerberos 5 tickets as tokens (aka 2b tokens).
25 This means that all of the AFS servers must be running OpenAFS release 1.2.8 or
26 higher. Transarc servers do not support Kerberos 5 tickets as tokens.
28 When using a Microsoft Windows Active Directory as the KDC which issues the
29 service ticket for the AFS cell there are two things to consider. First, the
30 Kerberos 5 tickets issued by Active Directory can be quite large when compared
31 to tickets issued by a traditional KDC due to the incorporation of
32 authorization data in the PAC. If this is your situation you either must
33 modify your 1.2.x servers to support tokens larger than a few hundred bytes;
34 or install the 1.3.64 or higher release on your servers. Second, Windows 2003
35 Active Directory will issue service tickets utilizing the DES-CBC-MD5 enctype.
36 OpenAFS releases older than 1.3.64 will not properly support this enctype.
39 2. The AFS Client Service does not provide robust behavior in an environment
40 with a plug-n-play network environment. Changes to the number of network
41 adapters or the assigned IP addresses will cause the service to panic. The
42 recommended work around for this problem is to install the Microsoft Loopback
43 Adapter on the machine. When the MLA is installed with a static IP address
44 the AFS Client Service will bind only to the loopback and not be affected by
45 changes to state of other network adapters installed on the system.
47 Starting in the 1.3.65 release the installers provided by OpenAFS.org will
48 install the Microsoft Loopback Adapter for you with a name of "AFS" and a
49 pre-assigned IP address in the 10.x.x.x range.
51 One of the benefits of using the MLA is that the NETBIOS names used for the
52 AFS Client's SMB server do not have to be published on any adapter other than
53 the MLA. This means that the names no longer need to be unique. When the MLA
54 is in use, the NETBIOS name associated with the AFS Client Service is simply
55 "AFS". When the MLA is not in use the NETBIOS name is "MACHINE-AFS".
57 When the MLA is installed, UNC paths of the form \\AFS\cellname\path may be used.
59 The MLA is installed with a binding to "Client for Microsoft Networks" but not
60 to "File and Printer Sharing for Microsoft Networks". If you fail to bind
61 "Client Microsoft Networks" you will not be able to access the AFS Client
62 Service when the machine is disconnect from the network. If you bind "File
63 and Printer Sharing ..." there will be a conflict between the name "AFS" and
64 the name of the machine on the published IP Address. This will result in a
65 failure to be able to access files in AFS. The "NET VIEW" command will return
66 a "System Error 52" message when this conflict exists. To correct the problem:
68 * stop the AFS Client Service
69 * bind the "Client for Microsoft Networks" to the MLA
70 * unbind "File and Printer Sharing for Microsoft Networks" from the MLA
71 * Disable and then Enable the MLA
72 * start the AFS Client Service
75 3. Traditionally, when the AFS Client Service starts it must be able to
76 access the "root.afs" volume of the default cell. The "root.afs" volume
77 contains a set of read-only and read-write mount points to the "root.cell"
78 volumes of various cells the administrator of the default cell believes
79 should be accessible. If the "root.afs" volume is
80 inaccessible when the client service is started, the service will panic.
81 Since many users now use laptops or otherwise operate in disconnected
82 environments in which a VPN may be needed to access the cell's servers, it is
83 often the case that the "root.afs" volume for the default cell is not
84 reachable and the AFS Client Service will not successfully start.
86 The OpenAFS Client Service now supports a fake "root.afs" volume which is
87 dynamically constructed when the service starts. This mode is called
88 Freelance mode. Freelance mode is turned on by default.
90 The contents of the fake "root.afs" volume are constructed dynamically as
91 cells are accessed. When the fake "root.afs" volume is constructed it will
92 only contain two mount points: a read-only and read-write mount point used
93 to access the "root.cell" volume of the default AFS cell. Any attempt to
94 access a valid cell name will automatically result in a new mount point
95 being created in the fake "root.afs" volume. If the cellname begins with
96 a "." the mount point will be read-write; otherwise the mount point will
97 be read-only. These mount points are preserved in the registry at key:
99 HKLM\SOFTWARE\OpenAFS\Client\Freelance
101 Additional mount points may be manually created using the "fs mkmount"
102 command. Mount points may be removed using the "fs rmmount" command.
104 >fs mkmount \\AFS\all\athena.mit.edu root.cell athena.mit.edu
105 >fs mkmount \\AFS\all\.athena.mit.edu root.cell athena.mit.edu -rw
106 >fs rmmount \\AFS\all\athena.mit.edu
107 >fs rmmount \\AFS\all\.athena.mit.edu
109 Beginning in 1.3.74, the Freelance fake root.afs volume will support
110 the creation of symlinks.
112 >symlink make \\afs\all\link \\afs\all\athena.mit.edu\user\j\a\jaltman
114 >symlink list \\afs\all\link
115 '\\afs\all\link' is a symlink to 'athena.mit.edu\user\j\a\jaltman'
117 >symlink rm \\afs\all\link
119 The symlinks are stored in the registry at:
121 HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks
124 4. The OpenAFS for Windows client will use AFSDB DNS records to
125 discover cell information when it is not located in the local CellServDB file
126 (\Program Files\OpenAFS\Client\CellServDB).
129 5. OpenAFS for Windows 1.3.72 only supports Windows 2000, Windows XP, and
130 Windows 2003. Windows NT 4.0 and the entire Windows 9x/Me line are no
131 longer supported. Older releases of OpenAFS are available for download
132 if those operating systems must be supported. The last version with support
133 for Win9x is 1.2.2b. The last version with support for Windows NT 4.0 is
137 6. OpenAFS for Windows installs a WinLogon Network Provider to provide
138 Integrated Logon (Single Sign-on) functionality. Integrated Logon can be used
139 when the Windows username and password match the username and password
140 associated with the default cell's Kerberos realm. For example, if the
141 windows username is "jaltman" and the default cell is "athena.mit.edu", then
142 Integrated Logon can be successfully used if the windows password matches the
143 password used for the Kerberos principal "jaltman@ATHENA.MIT.EDU".
145 Integrated Logon is required if you desire the ability to store roaming user
146 profiles within the AFS file system. OpenAFS does not provide tools for
147 synchronizing the Windows and Kerberos user accounts and passwords.
149 If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain
150 tokens. Otherwise, Kerberos 4 is used.
152 There is a High Security mode for use with Integrated Logon when multiple
153 users will share a single machine. There are known problems with this mode.
154 In particular, if you are using this mode it is crucial that new AFS tokens
155 not be obtained after the logon session starts except via the AFS Systray tool
156 as started by the AFS Network Provider. If the AFS Systray tool is stopped
157 you must log off to obtain new tokens. Do not use external tools such as
158 "aklog.exe" if High Security mode is turned on. As of 1.3.70, OpenAFS supports
159 Authenticated SMB connections which removes the need for High Security mode.
162 What Integrated Logon does not do:
163 (a) Integrated Logon does not have the ability to obtain Kerberos 5
164 tickets for use during the Windows Session. At the current time there
165 is no mechanism by which a Kerberos 5 CCAPI credentials cache can
166 be constructed during the logon process such that it will exist in
167 the user's logon session.
168 (b) Integrated Logon does not have the ability to cache the user's
169 username and password for the purpose of obtaining tokens if the
170 Kerberos KDC is inaccessible at logon time.
173 7. The AFS Systray tool (afscreds.exe) supports several command line
177 -E = force existing afscreds to exit
178 -I = install startup shortcut
179 -M = renew drive maps
180 -N = ip address change detection
181 -Q = quiet mode. do not display start service dialog
182 if afsd_service is not already running
183 -S = show tokens dialog on startup
184 -U = uninstall startup shortcut
185 -X = test and do map share
187 -: = magic parameter for high security mode
189 autoinit will result in automated attempts to acquire AFS tokens when
190 afscreds.exe is started. afscreds.exe will attempt to utilize tickets stored
191 in the MSLSA credentials cache; any existing CCAPI credentials cache; and
192 finally display an Obtain Tokens dialog to the user. When used in combination
193 with ip address change detection, afscreds.exe will attempt to acquire AFS
194 tokens whenever the IP address list changes and the Kerberos KDC is
197 The renew drive maps option is used to ensure that the user drive maps
198 constructed via the AFS tools (not NET USE) are re-constructed each time
199 afscreds.exe is started.
201 By default afscreds.exe is configured by the OpenAFS.org installers to use -A
202 -N -M -Q as startup options. Currently, there is no UI to change this selection
203 after install time although these options may be altered via the registry either
204 per machine or per user. See AfscredsShortcutParams in registry.txt.
207 8. As of 1.3.71, the OpenAFS for Windows client supports a local Windows
208 authorization group called "AFS Client Admins". This group is used in
209 place of the "Administrators" group to determine which users are allowed
210 to modify the AFS Client Service configuration via either afs_config.exe
211 or fs.exe. For example, the following fs.exe commands are now restricted
212 to members of the "AFS Client Admin" group:
214 - checkservers with a non-zero timer value
217 - sysname with a new sysname list
226 Setting the default sysname for a machine should be done via the registry and
227 not via "fs sysname".
229 The local "SYSTEM" account is always a member of the "AFS Client Admin" group.
231 The initial membership of the "AFS Client Admin" group when created by the
232 installer is equivalent to the local "Administrators" group.
235 9. The AFS Client should support UNC paths everywhere. Power users that make
236 extensive use of the command line shell, cmd.exe, might want to consider using
237 JP Software's 4NT command processor. Unlike cmd.exe, 4NT does fully support
238 UNC paths and can use a UNC path as the default device.
241 10. The AFS Client ships with its own version of aklog.exe which should be
242 used in preference to those obtained by third party sources. The OpenAFS
243 aklog.exe supports Kerberos 5 as well as the ability to auto-generate
244 pts IDs for user's obtaining tokens to foreign cells.
246 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
247 [[-p | -path] pathname]
251 -d gives debugging information.
252 krb_realm is the kerberos realm of a cell.
253 pathname is the name of a directory to which you wish to authenticate.
254 -noprdb means don't try to determine AFS ID.
255 -5 or -4 selects whether to use Kerberos V or Kerberos IV.
256 (default is Kerberos V)
257 No commandline arguments means authenticate to the local cell.
260 11. The AFS Server functionality provided with OpenAFS 1.3.72 might work but
261 should be considered highly experimental. It has not been thoroughly tested.
262 Any data which would cause pain if lost should not be stored in an OpenAFS
265 A few notes on the usage of the AFS Client Service if it is going to be
266 used with the OpenAFS AFS Server:
268 (a) When the AFS Server is installed Freelance mode must be turned off.
270 (b) The AFS Server and related tools only support the built in kaserver
271 (Kerberos IV). If the AFS Server is being used, MIT Kerberos for Windows
275 12. The OpenAFS for Windows installers now include Symbol information which
276 should be installed if you are experiencing problems and need to send crash
277 reports. This is true in both the release and the debug versions of the
278 installers. The differences between the release and debug versions are
279 whether or not the binaries were compiled with optimization; whether the
280 debug symbols are installed by default; and whether additional debug
281 statements were compiled into the binaries.
284 13. OpenAFS for Windows does not support files larger than 2GB.
287 14. Local RPC is used as the default RPC mechanism for setting
288 tokens. TCP RPC is required to be installed and is used for debugging
292 15. OpenAFS for Windows automatically open ports in the Windows
293 Internet Connection Firewall.
296 16. The OpenAFS for Windows installer by default activates a weak form of
297 encrypted data transfer between the AFS client and the AFS servers. This
298 is often referred to as "fcrypt" mode.
301 17. OpenAFS 1.3.71 adds support for authenticated SMB connections using
302 either NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...). In previous versions
303 of OpenAFS the SMB connections were unauthenticated which left open the
304 door for several security holes which could be used to obtain access to
305 the use of other user's tokens on shared machines. With the introduction
306 of authenticated SMB connections the so called High Security mode should
309 When GSS SPNEGO results in a Kerberos 5 authentication, the Windows SMB
310 client will attempt to retrieve service tickets for "cifs/afs@REALM" (if
311 the loopback adapter is in use) or "cifs/machine-afs@REALM" (if the loopback
312 adapter is not being used). It is extremely important that this service
313 principal not exist in the KDC database. If the request for this ticket
314 fails, a subsequent request for "cifs/HOST$@REALM" will be issued. This
315 service principal should exist in the KDC database. The key associated
316 with this service principal must match the key assigned to
317 "host/machine@REALM". If the local machine is part of a Windows Domain
318 this will all be taken care of for you. If the local machine is using
319 a non-MS KDC for authentication, then your KDC administrator will have to
320 add these service principals to the list of principals to be maintained
324 18. As of 1.3.70, INI files are no longer used for the storage of AFS
325 configuration data. No longer are there any AFS related files stored in the
326 %WINDIR% directory. The CellServDB file is no longer called "afsdsbmt.ini"
327 and it is stored in the OpenAFS\Client directory. The afs_freelance.ini
328 and afsdsbmt.ini file data has been moved to the registry.
330 IMPORTANT: while the CellServDB file location and freelance mountpoint
331 data will be automatically migrated; there is no mechanism for automatic
332 migration of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.
335 19. As of 1.3.70, the OpenAFS Client is compatible with Windows XP SP2
336 and Windows 2003 SP1. The Internet Connection Firewall will be
337 automatically adjusted to allow the receipt of incoming callback messages
338 from the AFS file server. In addition, the appropriate Back Connection
339 entries are added to the registry to allow SMB authentication to be
340 performed across the loopback connection.
343 20. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote
344 Admin Protocol which provides browsing of server and share information.
345 This significantly enhances the interoperability of AFS volumes within the
346 Explorer Shell and Microsoft Office applications.
349 21. OpenAFS will now automatically forget a user's tokens upon Logoff
350 unless the user's profile was loaded from an AFS volume. In this situation
351 there is no mechanism to determine when the profile has been successfully
352 written back to the network. It is therefore unsafe to release the user's
353 tokens. Whether or not the profile has been loaded from the registry can
354 be determined for Local Accounts, Active Directory accounts and NT4
358 22. Terminal Server installations.
359 When installing under Terminal Server, you must execute the NSIS installer
360 (.exe) from within the Add/Remove Programs Control Panel. Failure to do so
361 will result in AFS not running properly. The AFS Server should not
362 be installed on a machine with Terminal Server installed.
365 23. AFS is a Unix native file system. As such the OpenAFS client attempts
366 to treat the files stored in AFS as they would be on Unix. File and directory
367 names beginning with a "." are automatically given the Hidden attribute so
368 they will not normally be displayed.
371 24. Some organizations which have AFS cell names and Kerberos realm names
372 which differ by more then just lower and upper case rely on a modification
373 to krb524d which maps a Kerberos 5 ticket from realm FOO to a Kerberos 4
374 ticket in realm BAR. This allows user@FOO to appear to be user@bar for
375 the purposes of accessing the AFS cell. As of OpenAFS 1.2.8, support was
376 added to allow the immediate use of Kerberos 5 tickets as AFS (2b) tokens.
377 This is the first building block necessary to break away from the
378 limitations of Kerberos 4 with AFS. By using Kerberos 5 directly we
379 avoid the security holes inherent in Kerberos 4 cross-realm. We also
380 gain access to cryptographically stronger algorithms for authentication
383 Another reason for using Kerberos 5 directly is because the krb524 service
384 runs on a port (4444) which has become increasingly blocked by ISPs. The
385 port was used to spread a worm which attacked Microsoft Windows in the
386 summer of 2003. When the port is blocked users find that they are unable
389 Replacing the Kerberos 4 ticket with a Kerberos 5 ticket is a win in all
390 situations except when the cell name does not match the realm name and
391 the principal names placed into the ACLs are not the principal names from
392 the Kerberos 5 ticket. To support this transition, OpenAFS for Windows
393 in 1.3.72 adds a new registry value to force the use of krb524d. However,
394 the availability of this option should only be used by individuals until
395 such time as their organizations can provide a more permanent solution.
398 25. The Status Cache (AFS Config Control Panel: Advanced Page) is defined
399 to have a maximum number of entries. Each entry represents a single file
400 or directory entry accessed within the AFS file system. When the maximum
401 number of entries are allocated, entries will begin to be reused according
402 to a least recently used (LRU) algorithm. If the number of files or
403 directories being accessed repeatedly by your applications is greater then
404 the maximum number of entries, your host will begin to experience thrashing
405 of the Status Cache and all requests will result in network operations.
407 If you are experiencing poor performance you might want to increase the
408 maximum number of Status Cache entries. Each entry requires 164K. Only
409 those entries which are used are allocated.
412 26. "Netbios over TCP/IP" must be active on the machine in order for
413 communication with the AFS Client Service to succeed. If "Netbios over
414 TCP/IP" is disabled on the machine, then communication with the AFS Client
415 Service will be impossible.
418 27. The AFS Client Service and related binaries are digitally signed by
419 "Secure Endpoints Inc." beginning with the 1.3.7400 release of OpenAFS
420 for Windows. Starting in the 1.3.7500 release, the AFS Client Service
421 will perform a run-time verification check to ensure that all AFS related
422 DLLs loaded by the service match the same file version number and were
423 signed by the same entity. This check has been added to prevent the
424 stability problems caused by more then one version of AFS being installed
425 on a machine at the same time. Many hours of support time have been wasted
426 tracking down problems caused by the mixture of files from different
429 The registry.txt file documents the "VerifyServiceSignature" registry
430 value which can be used to disable the signature check. The file version
431 check cannot be disabled.
434 28. The maximum cache size is approximately 1.3GB. This is the largest
435 contiguous block of memory in the 2GB process address space which can be
436 used for the memory mapped file. Due to fragmentation of the process
437 spaced caused by the digital signature verification code, any attempt to
438 specify a cache size greater then 700MB will result in the automatic
439 disabling of the signature check.
442 29. OpenAFS for Windows implements an SMB server which is used as a
443 gateway to the AFS filesystem. Because of the use of SMB, Windows
444 stores all files into AFS using the OEM code pages such as CP437 (United
445 States) or CP850 (Western Europe). These code pages are incompatible
446 with the ISO Latin-1 character set typically used as a default on Unix
447 systems in both the United States and Western Europe. Filenames stored
448 by OpenAFS for Windows are therefore unreadable on Unix systems if they
449 include any of the following characters:
451 [Ç] 128 08/00 200 80 C cedilla
452 [ü] 129 08/01 201 81 u diaeresis
453 [é] 130 08/02 202 82 e acute
454 [â] 131 08/03 203 83 a circumflex
455 [ä] 132 08/04 204 84 a diaeresis
456 [à] 133 08/05 205 85 a grave
457 [å] 134 08/06 206 86 a ring
458 [ç] 135 08/07 207 87 c cedilla
459 [ê] 136 08/08 210 88 e circumflex
460 [ë] 137 08/09 211 89 e diaeresis
461 [è] 138 08/10 212 8A e grave
462 [ï] 139 08/11 213 8B i diaeresis
463 [î] 140 08/12 214 8C i circumflex
464 [ì] 141 08/13 215 8D i grave
465 [Ä] 142 08/14 216 8E A diaeresis
466 [Å] 143 08/15 217 8F A ring
467 [É] 144 09/00 220 90 E acute
468 [æ] 145 09/01 221 91 ae diphthong
469 [Æ] 146 09/02 222 92 AE diphthong
470 [ô] 147 09/03 223 93 o circumflex
471 [ö] 148 09/04 224 94 o diaeresis
472 [ò] 149 09/05 225 95 o grave
473 [û] 150 09/06 226 96 u circumflex
474 [ù] 151 09/07 227 97 u grave
475 [ÿ] 152 09/08 230 98 y diaeresis
476 [Ö] 153 09/09 231 99 O diaeresis
477 [Ü] 154 09/10 232 9A U diaeresis
478 [ø] 155 09/11 233 9B o slash
479 [£] 156 09/12 234 9C Pound sterling sign
480 [Ø] 157 09/13 235 9D O slash
481 [×] 158 09/14 236 9E Multiplication sign
482 [] 159 09/15 237 9F Florin sign
484 As of 1.3.75, a new registry value, HKLM\SOFTWARE\OpenAFS\Client
485 "StoreAnsiFilenames" can be set to instruct OpenAFS for Windows to store
486 filenames using the ANSI Code Page instead of the OEM Code Page. The ANSI
487 Code Page is a compatible superset of Latin-1. This setting is not the
488 default setting because making this change would prevent OpenAFS for Windows
489 from being able to access filenames containing the above characters which
490 were created without this setting.
493 30. There is a known issue with storing Windows Roaming Profiles when
494 the profile contains either directories or files with names which cannot
495 be represented in the local OEM character set. In this case, attempts
496 to write the profile back to AFS will fail. OpenAFS for Windows does
497 not currently support UNICODE. To avoid this problem some sites run
498 logoff scripts (assigned by group policy) which rename all files to use
499 only the supported characters for the locale.
503 ------------------------------------------------------------------------
507 Bug reports should be sent to openafs-bugs@openafs.org. Please include as
508 much information as possible about the issue. If you are reporting a crash,
509 please install the debugging symbols by re-running the installer. If a dump
510 file is available for the problem include it along with the AFS Client Trace
511 file %WINDIR%\TEMP\afsd.log. The AFS Client startup log is
512 %WINDIR%\TEMP\afsd_init.log. Send the last continuous block of log
513 information from this file.
515 Configuring DrWatson to generate dump files for crashes:
517 * Run drwtsn32.exe to configure or to identify where the log and the crash dump
519 - click Start > Run...
520 - type drwtsn32 <enter>.
521 - Select either a Crash Dump Type: Mini or Full.
522 - Clear Dump Symbol Table
523 - Clear Append to Existing Log file.
524 - Check Dump All Thread Contexts.
525 - Check Create Crash Dump File
526 * Next run the monitoring module of Dr. Watson:
527 - click Start > Run...
528 - type drwatson <enter>.
529 - Once a crash happens, Dr. Watson generates a dump file and a report in the
530 log file, including the address of the crash and the stack dump.
532 Once you have the Dr. Watson's logfile and minidump, zip them and send them as
533 attachments with your e-mail to openafs-bugs@openafs.org.
535 When reporting a error, please be sure to include the version of OpenAFS.
538 ------------------------------------------------------------------------
540 How to Contribute to the Development of OpenAFS for Windows:
542 Contributions to the development of OpenAFS for Windows are needed.
543 Contributions may take many forms including cash donations, support contracts,
544 donated developer time, and even donated tech writer time.
546 If you wish to be involved in OpenAFS for Windows development please join the
547 openafs-win32-devel@openafs.org mailing list.
549 https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
551 User questions should be sent to the openafs-info@openafs.org mailing list.
553 https://lists.openafs.org/mailman/listinfo/openafs-info
555 You must join mailing lists if you wish to post to the list without incurring