1 OpenAFS for Windows 1.3.66 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 constructed 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 1. The Kerberos 4 infrastructure on which the 1.2 series is reliant is no
15 longer secure. Cross-realm Kerberos is very important in the AFS context and
16 most sites have or are migrating to Kerberos 5 environments. The 1.3 series
17 integrates with the MIT Kerberos for Windows 2.6.x product to provide Kerberos
18 5 functionality including the ability to auto-renew credentials and obtain
19 single sign-on capabilities with the Microsoft Windows Kerberos Logon Service.
21 The 1.3.65 OpenAFS client will directly use Kerberos 5 tickets as tokens if
22 KFW is installed. It requires that all of the AFS Servers which it
23 communicates support Kerberos 5 tickets. For OpenAFS this is any release 1.2.8
26 When using a Microsoft Windows Active Directory as your KDC for the AFS cell
27 extremely large tickets may be issued. If this is your situation you either
28 must modify your 1.2.x servers to support tokens larger than a few hundred
29 bytes; or install the 1.3.64 or higher release on your servers.
31 2. The AFS Client Service does not provide robust behavior in an environment
32 with a plug-n-play network environment. Changes to the number of network
33 adapters or the assigned IP addresses will cause the client to panic. The
34 recommended work around for this problem is to install on the machine the
35 Microsoft Loopback Adapter. When the MLA is installed with a static IP
36 address the AFS Client Service will bind only to the loopback and not be
37 affected by changes to state of other network adapters installed on the
40 Starting in the 1.3.65 release the installers provided by OpenAFS.org will
41 install the Microsoft Loopback Adapter for you with a name of "AFS" and a
42 pre-assigned IP address in the 10.x.x.x range.
44 One of the benefits of using the MLA is that the NETBIOS names used for the
45 AFS Client's SMB server do not have to be published on any adapter other than
46 the MLA. This means that the names no longer need to be unique. When the MLA
47 is in use, the NETBIOS name associated with the AFS Client Service is simply
48 "AFS". When the MLA is not in use the NETBIOS name is "MACHINE-AFS".
50 With the MLA installed, UNC paths of the form \\AFS\cellname\path may be used.
52 3. When the AFS Client Service starts it must be able to contact the root.afs
53 volume of the default cell. If the root.afs volume is not accessible when the
54 client service is started, the service will panic. Since many users now use
55 laptops or otherwise operate in disconnected environments in which a VPN may
56 be needed to access the cell's servers, it is often the case that the root.afs
57 volume for the default cell will not be reachable and the client service
58 cannot successfully start.
60 In the 1.3.65 release there is support for a fake root.afs volume which is
61 dynamically constructed when the afs client service starts. This is called
62 Freelance mode. Freelance mode is turned on by default in the OpenAFS.org
65 A couple of notes about Freelance mode. First, since the fake root.afs volume
66 is constructed on the fly, when it is first used there will be no entries in
67 the volume. Do not be concerned. Any attempt to access a valid cell name will
68 automatically result in a new read-only mount point being created in the fake
69 root.afs volume. These mount points are preserved between service starts in
70 the %WINDIR%\afs_freelance.ini file.
72 As of 1.3.66, Freelance mode supports read-write mount points in the fake
73 root.afs volume. In addition, if the mount point list is empty, mount points
74 for "cellname" (ro) and ".cellname" (rw) will be automatically generated.
76 4. The OpenAFS for Windows client will make use of AFSDB DNS records to
77 discover cell information when it is not located in the local CellServDB file
78 (%WINDIR%\afsdcell.ini).
80 5. OpenAFS for Windows 1.3.65 only supports Windows 2000, Windows XP, and
81 Windows 2003. Windows NT 4.0 and the entire Windows 9x/Me line are not
82 supported. If OpenAFS for Windows runs on those platforms it is by sheer
85 6. OpenAFS for Windows installs a Network Provider for use in supporting an
86 Integrated Logon (Single Sign-on) functionality. Integrated Logon can be used
87 when the Windows username and password match the username and password
88 associated with the default cell's Kerberos realm. For example, if the
89 windows username is "jaltman" and the default cell is "athena.mit.edu", then
90 Integrated Logon can be successfully used if the windows password matches the
91 password used for the Kerberos principal "jaltman@ATHENA.MIT.EDU".
93 Integrated Logon is required if you desire the ability to store roaming user
94 profiles within the AFS file system. OpenAFS does not provide tools for
95 synchronizing the Windows and Kerberos user accounts and passwords.
97 If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain
98 tokens. Otherwise, Kerberos 4 is used.
100 There is a High Security mode for use with Integrated Logon when multiple
101 users will share a single machine. There are known problems with this mode.
102 In particular, if you are using this mode it is crucial that new AFS tokens
103 not be obtained after the logon session starts except via the AFS Systray tool
104 as started by the AFS Network Provider. If the AFS Systray tool is stopped
105 you must log off to obtain new tokens. Do not use external tools such as
106 "aklog.exe" if High Security mode is turned on. As of 1.3.66, OpenAFS supports
107 Authenticated SMB connections which removes the need for High Security mode.
110 7. The AFS Systray tool (afscreds.exe) supports several new command line
114 -M = renew drive maps
115 -N = ip address change detection
118 autoinit will result in automated attempts to acquire AFS tokens when
119 afscreds.exe is started. When used in combination with ip address change
120 detection, afscreds.exe will attempt to acquire AFS tokens whenever a new IP
121 address is added to the system.
123 The renew drive maps option is used to ensure that the user drive maps
124 constructs via the AFS tools (not NET USE) are re-constructed at afscreds.exe
127 By default afscreds.exe is configured by the OpenAFS.org installers to use -A
128 -N -M as startup options. Currently, there is no UI to change this selection
129 after install time although these options may be set via the registry either
130 per machine or per user.
132 8. Some attempts in the 1.3.65 release have been made to restrict the behavior
133 of users with regards to their ability to alter the state of the AFS Client
134 Service. For example, the following fs.exe commands are now restricted to
137 - checkservers with a non-zero timer value
140 - sysname with a new sysname list
149 setting the default sysname for a machine should be done via the registry and
150 not via "fs sysname".
152 Some of the AFS Client Configuration Control Panel options are also restricted
153 to use by the "Administrator" account.
155 9. As of 1.3.65, the AFS Client should support UNC paths everywhere.
157 10. The AFS Client ships with its own version of aklog.exe which should be
158 used in preference to those obtained by third party sources.
160 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
161 [[-p | -path] pathname]
165 -d gives debugging information.
166 krb_realm is the kerberos realm of a cell.
167 pathname is the name of a directory to which you wish to authenticate.
168 -noprdb means don't try to determine AFS ID.
169 -5 or -4 selects whether to use Kerberos V or Kerberos IV.
170 (default is Kerberos V)
171 No commandline arguments means authenticate to the local cell.
173 11. The AFS Server functionality provided with OpenAFS 1.3.65 does work but
174 should be considered experimental. It has not been thoroughly tested.
176 12. The OpenAFS for Windows installers now include Symbol information which
177 should be installed if you are experiencing problems and need to send crash
180 13. OpenAFS for Windows does not support files larger than 2GB.
182 14. There are documented problems running the AFS Client on Hyperthreaded
183 Pentium 4 machines. As of 1.3.66, a registry entry may be created to specify
184 that the AFS Client Service should only use a single processor. If you have
185 a hyperthreaded system it is strongly advised that this registry value be set.
186 See "registry.txt" for details on the MaxCPUs value.
188 15. OpenAFS for Windows currently requires the use of TCP based RPC. If the
189 machine is restricted to Local RPC only, you will be unable to store tokens.
190 As of 1.3.66, Local RPC is used as the default RPC mechanism for setting
191 tokens. TCP RPC is still used for debugging and other functions.
193 16. OpenAFS for Windows does not automatically open ports in the Windows
194 Internet Connection Firewall. You must manually open port 7001 to allow for
195 incoming callback messages to be received by AFS file servers.
197 17. The OpenAFS for Windows installer by default activates a weak form of
198 encrypted data transfer between the AFS client and the AFS servers. This
199 is often referred to as "crypt" mode.
201 18. OpenAFS 1.3.66 adds support for authenticated SMB connections using
202 either NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...). In previous versions
203 of OpenAFS the SMB connections were unauthenticated which left open the
204 door for several security holes which could be used to obtain access to
205 the use of other user's tokens on shared machines. With the introduction
206 of authenticated SMB connections the so called High Security mode should
209 When GSS SPNEGO results in a Kerberos 5 authentication, the Windows SMB
210 client will attempt to retrieve service tickets for "cifs/afs@REALM" (if
211 the loopback adapter is in use) or "cifs/machine-afs@REALM" (if the loopback
212 adapter is not being used). It is extremely important that this service
213 principal not exist in the KDC database. If the request for this ticket
214 fails, a subsequent request for "cifs/HOST$@REALM" will be issued. This
215 service principal should exist in the KDC database. The key associated
216 with this service principal must match the key assigned to
217 "host/machine@REALM". If the local machine is part of a Windows Domain
218 this will all be taken care of for you. If the local machine is using
219 a non-MS KDC for authentication, then your KDC administrator will have to
220 add these service principals to the list of principals to be maintained
223 19. As of 1.3.66, the use of INI files for the storage of AFS configuration
224 data is no more. No longer are there any AFS related files stored in the
225 %WINDIR% directory. The CellServDB file is no longer called "afsdsbmt.ini"
226 and it is stored in the OpenAFS\Client directory. The afs_freelance.ini
227 and afsdsbmt.ini file data has been moved to the registry.
229 IMPORTANT: while the CellServDB file location and freelance mountpoint
230 data will be automatically migrated; there is no mechanism for automatic
231 migration of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.
233 20. As of 1.3.66, the OpenAFS Client is compatible with Windows XP SP2.
234 The Internet Connection Firewall will be automatically adjusted to allow
235 the receipt of incoming callback messages from the AFS file server. In
236 addition, the appropriate Back Connection entries are added to the registry
237 to allow SMB authentication to be performed across the loopback connection.
241 ------------------------------------------------------------------------
245 Bug reports should be sent to openafs-bugs@openafs.org. Please include as
246 much information as possible about the issue. If you are reporting a crash,
247 please install the debugging symbols by re-running the installer. If a dump
248 file is available for the problem include it along with the AFS Client Trace
249 file %WINDIR%\TEMP\afsd.log. The AFS Client startup log is
250 %WINDIR%\TEMP\afsd_init.log. Send the last continuous block of log
251 information from this file.
253 ------------------------------------------------------------------------
255 How to Contribute to the Development of OpenAFS for Windows:
257 Contributions to the development of OpenAFS for Windows are needed.
258 Contributions may take many forms including cash donations, support contracts,
259 donated developer time, and even donated tech writer time.
261 If you wish to be involved in OpenAFS for Windows development please join the
262 openafs-win32-devel@openafs.org mailing list.
264 https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
266 User questions should be sent to the openafs-info@openafs.org mailing list.
268 https://lists.openafs.org/mailman/listinfo/openafs-info
270 You must join mailing lists if you wish to post to the list without incurring