d3f0871f4e32e22249592c331e11c232b4c8ad54
[openafs.git] / doc / txt / winnotes / afs-install-notes.txt
1 OpenAFS for Windows 1.3.65 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 constructed 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 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.
20
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 
24 or higher.
25
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.
30
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 
38 system.  
39
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.
43
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".
49
50 With the MLA installed, UNC paths of the form \\AFS\cellname\path may be used.
51
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. 
59  
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 
63 installers.  
64
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.  
71
72 Unfortunately, at the current time it is not possible to create read-write 
73 mount points in the fake root.afs cell.  This is a limitation which will be 
74 addressed in a future release.
75
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).
79
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 
83 luck.
84
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".
92
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.
96
97 If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain 
98 tokens.  Otherwise, Kerberos 4 is used.
99
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.
107
108 7. The AFS Systray tool (afscreds.exe) supports several new command line 
109 options: 
110
111     -A = autoinit 
112     -M = renew drive maps 
113     -N = ip address change detection 
114     -Z = unmap drives
115
116 autoinit will result in automated attempts to acquire AFS tokens when 
117 afscreds.exe is started.  When used in combination with ip address change 
118 detection, afscreds.exe will attempt to acquire AFS tokens whenever a new IP 
119 address is added to the system.
120
121 The renew drive maps option is used to ensure that the user drive maps 
122 constructs via the AFS tools (not NET USE) are re-constructed at afscreds.exe 
123 start time.
124
125 By default afscreds.exe is configured by the OpenAFS.org installers to use -A 
126 -N -M as startup options.  Currently, there is no UI to change this selection 
127 after install time although these options may be set via the registry either 
128 per machine or per user.
129
130 8. Some attempts in the 1.3.65 release have been made to restrict the behavior 
131 of users with regards to their ability to alter the state of the AFS Client 
132 Service.  For example, the following fs.exe commands are now restricted to 
133 Administrator:
134
135     - checkservers with a non-zero timer value
136     - setcachesize
137     - newcell
138     - sysname with a new sysname list
139     - exportafs
140     - setcell
141     - setserverprefs
142     - storebehind
143     - setcrypt
144     - cscpolicy
145     - trace
146
147 setting the default sysname for a machine should be done via the registry and 
148 not via "fs sysname".
149
150 Some of the AFS Client Configuration Control Panel options are also restricted 
151 to use by the "Administrator" account.
152
153 9. As of 1.3.65, the AFS Client should support UNC paths everywhere.
154
155 10. The AFS Client ships with its own version of aklog.exe which should be 
156 used in preference to those obtained by third party sources.
157
158 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
159              [[-p | -path] pathname]
160              [-noprdb] [-force]
161              [-5 | -4]
162
163    -d gives debugging information.
164    krb_realm is the kerberos realm of a cell.
165    pathname is the name of a directory to which you wish to authenticate.
166    -noprdb means don't try to determine AFS ID.
167    -5 or -4 selects whether to use Kerberos V or Kerberos IV.
168       (default is Kerberos V)
169    No commandline arguments means authenticate to the local cell.
170
171 11. The AFS Server functionality provided with OpenAFS 1.3.65 does work but 
172 should be considered experimental.  It has not been thoroughly tested.
173
174 12. The OpenAFS for Windows installers now include Symbol information which 
175 should be installed if you are experiencing problems and need to send crash 
176 reports.
177
178 13. OpenAFS for Windows does not support files larger than 2GB.
179
180 14. There are documented problems running the AFS Client on Hyperthreaded 
181 Pentium 4 machines.  At the current time it is recommended that hyper- 
182 threading be disabled in the machine configuration.
183
184 15. OpenAFS for Windows currently requires the use of TCP based RPC. If the 
185 machine is restricted to Local RPC only, you will be unable to store tokens.
186
187 16. OpenAFS for Windows does not automatically open ports in the Windows 
188 Internet Connection Firewall.  You must manually open port 7001 to allow for 
189 incoming callback messages to be received by AFS file servers.
190
191 17. The OpenAFS for Windows installer by default activates a weak form of 
192 encrypted data transfer between the AFS client and the AFS servers.  This
193 is often referred to as "crypt" mode.
194
195 ------------------------------------------------------------------------
196
197 Reporting Bugs:
198
199 Bug reports should be sent to openafs-bugs@openafs.org.  Please include as 
200 much information as possible about the issue.  If you are reporting a crash, 
201 please install the debugging symbols by re-running the installer.  If a dump 
202 file is available for the problem include it along with the AFS Client Trace 
203 file  %WINDIR%\TEMP\afsd.log.  The AFS Client startup log is 
204 %WINDIR%\TEMP\afsd_init.log.  Send the last continuous block of log 
205 information from this file.
206
207 ------------------------------------------------------------------------
208
209 How to Contribute to the Development of OpenAFS for Windows:
210
211 Contributions to the development of OpenAFS for Windows are needed. 
212 Contributions may take many forms including cash donations, support contracts, 
213 donated developer time, and even donated tech writer time.
214
215 If you wish to be involved in OpenAFS for Windows development please join the 
216 openafs-win32-devel@openafs.org mailing list.
217
218   https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
219
220 User questions should be sent to the openafs-info@openafs.org mailing list.  
221
222   https://lists.openafs.org/mailman/listinfo/openafs-info
223
224 You must join mailing lists if you wish to post to the list without incurring 
225 a moderation delay.
226