cifs-pattern-match-20040921
[openafs.git] / doc / txt / winnotes / afs-install-notes.txt
1 OpenAFS for Windows 1.3.71 Installation Notes
2 ---------------------------------------------
3
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.
9
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.  
13
14
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.
21
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.
27
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.
37
38
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.  
46
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.
50
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".
56
57 When the MLA is installed, UNC paths of the form \\AFS\cellname\path may be used.
58
59
60 3. Traditionally, when the AFS Client Service starts it must be able to 
61 access the "root.afs" volume of the default cell.  The "root.afs" volume
62 contains a set of read-only and read-write mount points to the "root.cell"
63 volumes of various cells the administrator of the default cell believes
64 should be accessible.  If the "root.afs" volume is 
65 inaccessible when the client service is started, the service will panic.  
66 Since many users now use laptops or otherwise operate in disconnected 
67 environments in which a VPN may be needed to access the cell's servers, it is 
68 often the case that the "root.afs" volume for the default cell is not 
69 reachable and the AFS Client Service will not successfully start. 
70  
71 The OpenAFS Client Service now supports a fake "root.afs" volume which is 
72 dynamically constructed when the service starts.  This mode is called 
73 Freelance mode.  Freelance mode is turned on by default.
74
75 The contents of the
76 fake "root.afs" volume are constructed dynamically as cells are accessed.
77 When the fake "root.afs" volume is constructed it will only contain two
78 mount points: a read-only and read-write mount point used to access the
79 "root.cell" volume of the default AFS cell.  Any attempt to access a 
80 valid cell name will automatically result in a new mount point 
81 being created in the fake "root.afs" volume.  If the cellname begins with
82 a "." the mount point will be read-write; otherwise the mount point will
83 be read-only.  These mount points are preserved in the registry at key:
84   HKLM\SOFTWARE\OpenAFS\Client\Freelance
85
86 Additional mount points may be manually created using the "fs mkmount"
87 command.  Mount points may be removed using the "fs rmmount" command.
88
89     fs mkmount \\AFS\all\athena.mit.edu root.cell athena.mit.edu
90     fs mkmount \\AFS\all\.athena.mit.edu root.cell athena.mit.edu -rw
91     fs rmmount \\AFS\all\athena.mit.edu
92     fs rmmount \\AFS\all\.athena.mit.edu
93      
94
95 4. The OpenAFS for Windows client will use AFSDB DNS records to 
96 discover cell information when it is not located in the local CellServDB file 
97 (\Program Files\OpenAFS\Client\CellServDB).
98
99
100 5. OpenAFS for Windows 1.3.71 only supports Windows 2000, Windows XP, and 
101 Windows 2003.  Windows NT 4.0 and the entire Windows 9x/Me line are no
102 longer supported.  Older releases of OpenAFS are available for download
103 if those operating systems must be supported.  The last version with support
104 for Win9x is 1.2.2b.  The last version with support for Windows NT 4.0 is
105 1.2.10.
106
107
108 6. OpenAFS for Windows installs a WinLogon Network Provider to provide
109 Integrated Logon (Single Sign-on) functionality. Integrated Logon can be used 
110 when the Windows username and password match the username and password 
111 associated with the default cell's Kerberos realm.  For example, if the 
112 windows username is "jaltman" and the default cell is "athena.mit.edu", then 
113 Integrated Logon can be successfully used if the windows password matches the 
114 password used for the Kerberos principal "jaltman@ATHENA.MIT.EDU".
115
116 Integrated Logon is required if you desire the ability to store roaming user 
117 profiles within the AFS file system.  OpenAFS does not provide tools for 
118 synchronizing the Windows and Kerberos user accounts and passwords.
119
120 If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain 
121 tokens.  Otherwise, Kerberos 4 is used.
122
123 There is a High Security mode for use with Integrated Logon when multiple 
124 users will share a single machine.  There are known problems with this mode.  
125 In particular, if you are using this mode it is crucial that new AFS tokens 
126 not be obtained after the logon session starts except via the AFS Systray tool 
127 as started by the AFS Network Provider.  If the AFS Systray tool is stopped 
128 you must log off to obtain new tokens.  Do not use external tools such as 
129 "aklog.exe" if High Security mode is turned on. As of 1.3.70, OpenAFS supports 
130 Authenticated SMB connections which removes the need for High Security mode. 
131 DO NOT USE IT!!!!! 
132
133 What Integrated Logon does not do:
134  (a) Integrated Logon does not have the ability to obtain Kerberos 5
135      tickets for use during the Windows Session.  At the current time there
136      is no mechanism by which a Kerberos 5 CCAPI credentials cache can
137      be constructed during the logon process such that it will exist in 
138      the user's logon session.
139  (b) Integrated Logon does not have the ability to cache the user's 
140      username and password for the purpose of obtaining tokens if the
141      Kerberos KDC is inaccessible at logon time.
142
143
144 7. The AFS Systray tool (afscreds.exe) supports several new command line 
145 options: 
146
147     -A = autoinit 
148     -M = renew drive maps 
149     -N = ip address change detection 
150     -Z = unmap drives
151
152 autoinit will result in automated attempts to acquire AFS tokens when 
153 afscreds.exe is started.  afscreds.exe will attempt to utilize tickets stored
154 in the MSLSA credentials cache; any existing CCAPI credentials cache; and
155 finally display an Obtain Tokens dialog to the user.  When used in combination 
156 with ip address change detection, afscreds.exe will attempt to acquire AFS 
157 tokens whenever the IP address list changes and the Kerberos KDC is 
158 accessible.
159
160 The renew drive maps option is used to ensure that the user drive maps 
161 constructed via the AFS tools (not NET USE) are re-constructed each time
162 afscreds.exe is started.
163
164 By default afscreds.exe is configured by the OpenAFS.org installers to use -A 
165 -N -M -Q as startup options.  Currently, there is no UI to change this selection 
166 after install time although these options may be altered via the registry either 
167 per machine or per user.  See AfscredsShortcutParams in registry.txt.
168
169
170 8. Some attempts have been made to restrict the ability  
171 of users to alter the state of the AFS Client 
172 Service.  For example, the following fs.exe commands are now restricted to 
173 Administrator:
174
175     - checkservers with a non-zero timer value
176     - setcachesize
177     - newcell
178     - sysname with a new sysname list
179     - exportafs
180     - setcell
181     - setserverprefs
182     - storebehind
183     - setcrypt
184     - cscpolicy
185     - trace
186
187 setting the default sysname for a machine should be done via the registry and 
188 not via "fs sysname".
189
190 Some of the AFS Client Configuration Control Panel options are also restricted 
191 to use by the "Administrator" account.
192
193
194 9. The AFS Client should support UNC paths everywhere.  Power users that make
195 extensive use of the command line shell, cmd.exe, might want to consider using 
196 JP Software's 4NT command processor.  Unlike cmd.exe, 4NT does fully support
197 UNC paths and can use a UNC path as the default device.
198
199
200 10. The AFS Client ships with its own version of aklog.exe which should be 
201 used in preference to those obtained by third party sources.  The OpenAFS
202 aklog.exe supports Kerberos 5 as well as the ability to auto-generate
203 pts IDs for user's obtaining tokens to foreign cells.
204
205 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
206              [[-p | -path] pathname]
207              [-noprdb] [-force]
208              [-5 | -4]
209
210    -d gives debugging information.
211    krb_realm is the kerberos realm of a cell.
212    pathname is the name of a directory to which you wish to authenticate.
213    -noprdb means don't try to determine AFS ID.
214    -5 or -4 selects whether to use Kerberos V or Kerberos IV.
215       (default is Kerberos V)
216    No commandline arguments means authenticate to the local cell.
217
218
219 11. The AFS Server functionality provided with OpenAFS 1.3.71 might work but 
220 should be considered highly experimental.  It has not been thoroughly tested.
221 Any data which would cause pain if lost should not be stored in an OpenAFS 
222 Server on Windows.
223
224 A few notes on the usage of the AFS Client Service if it is going to be 
225 used with the OpenAFS AFS Server:
226
227 (a) When the AFS Server is installed Freelance mode must be turned off.  
228
229 (b) The AFS Server and related tools only support the built in kaserver
230 (Kerberos IV).  If the AFS Server is being used, MIT Kerberos for Windows
231 should not be used.
232
233
234 12. The OpenAFS for Windows installers now include Symbol information which 
235 should be installed if you are experiencing problems and need to send crash 
236 reports.  This is true in both the release and the debug versions of the 
237 installers.  The differences between the release and debug versions are 
238 whether or not the binaries were compiled with optimization; whether the
239 debug symbols are installed by default; and whether additional debug 
240 statements were compiled into the binaries.
241
242
243 13. OpenAFS for Windows does not support files larger than 2GB.  
244
245
246 14. There are reported problems running the AFS Client on Hyperthreaded 
247 Pentium 4 machines.  A registry entry may be created to specify
248 that the AFS Client Service should only use a single processor.  If you have
249 a hyperthreaded system and you are experiencing crashes, it is advised that
250 you create the "MaxCPUs" registry value and set it to "1".
251 See "registry.txt" for details. 
252
253
254 15. Local RPC is used as the default RPC mechanism for setting 
255 tokens.  TCP RPC is required to be installed and is used for debugging 
256 and other functions.
257
258
259 16. OpenAFS for Windows automatically open ports in the Windows 
260 Internet Connection Firewall.
261
262
263 17. The OpenAFS for Windows installer by default activates a weak form of 
264 encrypted data transfer between the AFS client and the AFS servers.  This
265 is often referred to as "fcrypt" mode.
266
267
268 18. OpenAFS 1.3.71 adds support for authenticated SMB connections using 
269 either NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...).  In previous versions
270 of OpenAFS the SMB connections were unauthenticated which left open the
271 door for several security holes which could be used to obtain access to
272 the use of other user's tokens on shared machines.  With the introduction
273 of authenticated SMB connections the so called High Security mode should
274 no longer be used.  
275
276 When GSS SPNEGO results in a Kerberos 5 authentication, the Windows SMB
277 client will attempt to retrieve service tickets for "cifs/afs@REALM" (if 
278 the loopback adapter is in use) or "cifs/machine-afs@REALM" (if the loopback
279 adapter is not being used).  It is extremely important that this service 
280 principal not exist in the KDC database.   If the request for this ticket
281 fails, a subsequent request for "cifs/HOST$@REALM" will be issued.  This 
282 service principal should exist in the KDC database.  The key associated 
283 with this service principal must match the key assigned to 
284 "host/machine@REALM".  If the local machine is part of a Windows Domain
285 this will all be taken care of for you.  If the local machine is using
286 a non-MS KDC for authentication, then your KDC administrator will have to
287 add these service principals to the list of principals to be maintained
288 for each host.
289
290
291 19. As of 1.3.70, INI files are no longer used for the storage of AFS 
292 configuration data.  No longer are there any AFS related files stored in the
293 %WINDIR% directory.  The CellServDB file is no longer called "afsdsbmt.ini"
294 and it is stored in the OpenAFS\Client directory.  The afs_freelance.ini
295 and afsdsbmt.ini file data has been moved to the registry.  
296
297 IMPORTANT: while the CellServDB file location and freelance mountpoint
298 data will be automatically migrated; there is no mechanism for automatic
299 migration of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.
300
301
302 20. As of 1.3.70, the OpenAFS Client is compatible with Windows XP SP2
303 and Windows 2003 SP1.  The Internet Connection Firewall will be 
304 automatically adjusted to allow the receipt of incoming callback messages 
305 from the AFS file server.  In addition, the appropriate Back Connection 
306 entries are added to the registry to allow SMB authentication to be 
307 performed across the loopback connection.
308
309
310 21. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote
311 Admin Protocol which provides browsing of server and share information.
312 This significantly enhances the interoperability of AFS volumes within the
313 Explorer Shell and Microsoft Office applications.
314
315
316 22. OpenAFS will now automatically forget a user's tokens upon Logoff
317 unless the user's profile was loaded from an AFS volume.  In this situation
318 there is no mechanism to determine when the profile has been successfully
319 written back to the network.  It is therefore unsafe to release the user's
320 tokens.
321                                                    
322
323 23. Terminal Server installations.
324 When installing under Terminal Server, you must execute the NSIS installer
325 (.exe) from within the Add/Remove Programs Control Panel.  Failure to do so 
326 will result in AFS not running properly.  The AFS Server should not 
327 be installed on a machine with Terminal Server installed.
328
329
330 24. AFS is a Unix native file system.  As such the OpenAFS client attempts
331 to treat the files stored in AFS as they would be on Unix.  File and directory
332 names beginning with a "." are automatically given the Hidden attribute so
333 they will not normally be displayed.
334
335
336 25. As of 1.3.71, the OpenAFS for Windows client supports a local Windows
337 authorization group called "AFS Client Admins".  This group is used in
338 place of the "Administrators" group to determine which users are allowed
339 to modify the AFS Client Service configuration via either afs_config.exe
340 or fs.exe.  During installation this group is created and the current
341 contents of the Administrators group is copied.
342
343
344 ------------------------------------------------------------------------
345
346 Reporting Bugs:
347
348 Bug reports should be sent to openafs-bugs@openafs.org.  Please include as 
349 much information as possible about the issue.  If you are reporting a crash, 
350 please install the debugging symbols by re-running the installer.  If a dump 
351 file is available for the problem include it along with the AFS Client Trace 
352 file  %WINDIR%\TEMP\afsd.log.  The AFS Client startup log is 
353 %WINDIR%\TEMP\afsd_init.log.  Send the last continuous block of log 
354 information from this file.
355
356 ------------------------------------------------------------------------
357
358 How to Contribute to the Development of OpenAFS for Windows:
359
360 Contributions to the development of OpenAFS for Windows are needed. 
361 Contributions may take many forms including cash donations, support contracts, 
362 donated developer time, and even donated tech writer time.
363
364 If you wish to be involved in OpenAFS for Windows development please join the 
365 openafs-win32-devel@openafs.org mailing list.
366
367   https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
368
369 User questions should be sent to the openafs-info@openafs.org mailing list.  
370
371   https://lists.openafs.org/mailman/listinfo/openafs-info
372
373 You must join mailing lists if you wish to post to the list without incurring 
374 a moderation delay.
375