doc/txt/winnotes/afs-install-notes.txt

   1 OpenAFS for Windows 1.3.70 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 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.  This requires that all servers
  24 be running OpenAFS release 1.2.8 or higher.  Transarc servers do not support
  25 Kerberos 5 tickets as tokens.
  26
  27 When using a Microsoft Windows Active Directory as your KDC for the AFS cell
  28 extremely large tickets may be issued.  If this is your situation you either
  29 must modify your 1.2.x servers to support tokens larger than a few hundred
  30 bytes; or install the 1.3.64 or higher release on your servers.
  31
  32 2. The AFS Client Service does not provide robust behavior in an environment
  33 with a plug-n-play network environment.  Changes to the number of network
  34 adapters or the assigned IP addresses will cause the client to panic.  The
  35 recommended work around for this problem is to install on the machine the
  36 Microsoft Loopback Adapter.  When the MLA is installed with a static IP
  37 address the AFS Client Service will bind only to the loopback and not be
  38 affected by changes to state of other network adapters installed on the
  39 system.
  40
  41 Starting in the 1.3.65 release the installers provided by OpenAFS.org will
  42 install the Microsoft Loopback Adapter for you with a name of "AFS" and a
  43 pre-assigned IP address in the 10.x.x.x range.
  44
  45 One of the benefits of using the MLA is that the NETBIOS names used for the
  46 AFS Client's SMB server do not have to be published on any adapter other than
  47 the MLA.  This means that the names no longer need to be unique.  When the MLA
  48 is in use, the NETBIOS name associated with the AFS Client Service is simply
  49 "AFS".  When the MLA is not in use the NETBIOS name is "MACHINE-AFS".
  50
  51 With the MLA installed, UNC paths of the form \\AFS\cellname\path may be used.
  52
  53 3. When the AFS Client Service starts it must be able to contact the root.afs
  54 volume of the default cell.  If the root.afs volume is not accessible when the
  55 client service is started, the service will panic.  Since many users now use
  56 laptops or otherwise operate in disconnected environments in which a VPN may
  57 be needed to access the cell's servers, it is often the case that the root.afs
  58 volume for the default cell will not be reachable and the client service
  59 cannot successfully start.
  60
  61 In the 1.3.65 release there is support for a fake root.afs volume which is
  62 dynamically constructed when the afs client service starts. This is called
  63 Freelance mode.  Freelance mode is turned on by default in the OpenAFS.org
  64 installers.
  65
  66 A couple of notes about Freelance mode.  First, since the fake root.afs volume
  67 is constructed on the fly, when it is first used the only mount points will
  68 be for the default afs cell.  Do not be concerned.  Any attempt to access a
  69 valid cell name will automatically result in a new read-only mount point
  70 being created in the fake root.afs volume.  These mount points are preserved
  71 between service starts in the HKLM\SOFTWARE\OpenAFS\Client\Freelance registry
  72 key.
  73
  74 As of 1.3.70, Freelance mode supports read-write mount points in the fake
  75 root.afs volume.  In addition, if the mount point list is empty, mount points
  76 for "cellname" (ro) and ".cellname" (rw) will be automatically generated.
  77
  78 4. The OpenAFS for Windows client will make use of AFSDB DNS records to
  79 discover cell information when it is not located in the local CellServDB file
  80 (\Program Files\OpenAFS\Client\CellServDB).
  81
  82 5. OpenAFS for Windows 1.3.65 only supports Windows 2000, Windows XP, and
  83 Windows 2003.  Windows NT 4.0 and the entire Windows 9x/Me line are not
  84 supported.  If OpenAFS for Windows runs on those platforms it is by sheer
  85 luck.
  86
  87 6. OpenAFS for Windows installs a Network Provider for use in supporting an
  88 Integrated Logon (Single Sign-on) functionality. Integrated Logon can be used
  89 when the Windows username and password match the username and password
  90 associated with the default cell's Kerberos realm.  For example, if the
  91 windows username is "jaltman" and the default cell is "athena.mit.edu", then
  92 Integrated Logon can be successfully used if the windows password matches the
  93 password used for the Kerberos principal "jaltman@ATHENA.MIT.EDU".
  94
  95 Integrated Logon is required if you desire the ability to store roaming user
  96 profiles within the AFS file system.  OpenAFS does not provide tools for
  97 synchronizing the Windows and Kerberos user accounts and passwords.
  98
  99 If KFW is installed, the Integrated Logon will use Kerberos 5 to obtain
 100 tokens.  Otherwise, Kerberos 4 is used.
 101
 102 There is a High Security mode for use with Integrated Logon when multiple
 103 users will share a single machine.  There are known problems with this mode.
 104 In particular, if you are using this mode it is crucial that new AFS tokens
 105 not be obtained after the logon session starts except via the AFS Systray tool
 106 as started by the AFS Network Provider.  If the AFS Systray tool is stopped
 107 you must log off to obtain new tokens.  Do not use external tools such as
 108 "aklog.exe" if High Security mode is turned on. As of 1.3.70, OpenAFS supports
 109 Authenticated SMB connections which removes the need for High Security mode.
 110 DO NOT USE IT!!!!!
 111
 112 7. The AFS Systray tool (afscreds.exe) supports several new command line
 113 options:
 114
 115     -A = autoinit
 116     -M = renew drive maps
 117     -N = ip address change detection
 118     -Z = unmap drives
 119
 120 autoinit will result in automated attempts to acquire AFS tokens when
 121 afscreds.exe is started.  afscreds.exe will attempt to utilize tickets stored
 122 in the MSLSA credentials cache; any existing CCAPI credentials cache; and
 123 finally display an Obtain Tokens dialog to the user.  When used in combination
 124 with ip address change detection, afscreds.exe will attempt to acquire AFS
 125 tokens whenever a new IP address is added to the system.
 126
 127 The renew drive maps option is used to ensure that the user drive maps
 128 constructed via the AFS tools (not NET USE) are re-constructed at afscreds.exe
 129 start time.
 130
 131 By default afscreds.exe is configured by the OpenAFS.org installers to use -A
 132 -N -M -Q as startup options.  Currently, there is no UI to change this selection
 133 after install time although these options may be set via the registry either
 134 per machine or per user.  See AfscredsShortcutParams in registry.txt.
 135
 136
 137 8. Some attempts in the 1.3.65 release have been made to restrict the behavior
 138 of users with regards to their ability to alter the state of the AFS Client
 139 Service.  For example, the following fs.exe commands are now restricted to
 140 Administrator:
 141
 142     - checkservers with a non-zero timer value
 143     - setcachesize
 144     - newcell
 145     - sysname with a new sysname list
 146     - exportafs
 147     - setcell
 148     - setserverprefs
 149     - storebehind
 150     - setcrypt
 151     - cscpolicy
 152     - trace
 153
 154 setting the default sysname for a machine should be done via the registry and
 155 not via "fs sysname".
 156
 157 Some of the AFS Client Configuration Control Panel options are also restricted
 158 to use by the "Administrator" account.
 159
 160 9. As of 1.3.65, the AFS Client should support UNC paths everywhere.
 161
 162 10. The AFS Client ships with its own version of aklog.exe which should be
 163 used in preference to those obtained by third party sources.
 164
 165 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
 166              [[-p | -path] pathname]
 167              [-noprdb] [-force]
 168              [-5 | -4]
 169
 170    -d gives debugging information.
 171    krb_realm is the kerberos realm of a cell.
 172    pathname is the name of a directory to which you wish to authenticate.
 173    -noprdb means don't try to determine AFS ID.
 174    -5 or -4 selects whether to use Kerberos V or Kerberos IV.
 175       (default is Kerberos V)
 176    No commandline arguments means authenticate to the local cell.
 177
 178 11. The AFS Server functionality provided with OpenAFS 1.3.65 does work but
 179 should be considered experimental.  It has not been thoroughly tested.
 180
 181 12. The OpenAFS for Windows installers now include Symbol information which
 182 should be installed if you are experiencing problems and need to send crash
 183 reports.
 184
 185 13. OpenAFS for Windows does not support files larger than 2GB.
 186
 187 14. There are known problems running the AFS Client on Hyperthreaded
 188 Pentium 4 machines.  As of 1.3.70, a registry entry may be created to specify
 189 that the AFS Client Service should only use a single processor.  If you have
 190 a hyperthreaded system it is strongly advised that this registry value be set.
 191 See "registry.txt" for details on the MaxCPUs value.
 192
 193 15. OpenAFS for Windows currently requires the use of TCP based RPC. If the
 194 machine is restricted to Local RPC only, you will be unable to store tokens.
 195 As of 1.3.70, Local RPC is used as the default RPC mechanism for setting
 196 tokens.  TCP RPC is still used for debugging and other functions.
 197
 198 16. As of 1.3.70, OpenAFS for Windows automatically open ports in the Windows
 199 Internet Connection Firewall.
 200
 201 17. The OpenAFS for Windows installer by default activates a weak form of
 202 encrypted data transfer between the AFS client and the AFS servers.  This
 203 is often referred to as "crypt" mode.
 204
 205 18. OpenAFS 1.3.70 adds support for authenticated SMB connections using
 206 either NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...).  In previous versions
 207 of OpenAFS the SMB connections were unauthenticated which left open the
 208 door for several security holes which could be used to obtain access to
 209 the use of other user's tokens on shared machines.  With the introduction
 210 of authenticated SMB connections the so called High Security mode should
 211 no longer be used.
 212
 213 When GSS SPNEGO results in a Kerberos 5 authentication, the Windows SMB
 214 client will attempt to retrieve service tickets for "cifs/afs@REALM" (if
 215 the loopback adapter is in use) or "cifs/machine-afs@REALM" (if the loopback
 216 adapter is not being used).  It is extremely important that this service
 217 principal not exist in the KDC database.   If the request for this ticket
 218 fails, a subsequent request for "cifs/HOST$@REALM" will be issued.  This
 219 service principal should exist in the KDC database.  The key associated
 220 with this service principal must match the key assigned to
 221 "host/machine@REALM".  If the local machine is part of a Windows Domain
 222 this will all be taken care of for you.  If the local machine is using
 223 a non-MS KDC for authentication, then your KDC administrator will have to
 224 add these service principals to the list of principals to be maintained
 225 for each host.
 226
 227 19. As of 1.3.70, INI files are no longer used for the storage of AFS
 228 configuration data.  No longer are there any AFS related files stored in the
 229 %WINDIR% directory.  The CellServDB file is no longer called "afsdsbmt.ini"
 230 and it is stored in the OpenAFS\Client directory.  The afs_freelance.ini
 231 and afsdsbmt.ini file data has been moved to the registry.
 232
 233 IMPORTANT: while the CellServDB file location and freelance mountpoint
 234 data will be automatically migrated; there is no mechanism for automatic
 235 migration of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.
 236
 237 20. As of 1.3.70, the OpenAFS Client is compatible with Windows XP SP2
 238 and Windows 2003 SP1.  The Internet Connection Firewall will be
 239 automatically adjusted to allow the receipt of incoming callback messages
 240 from the AFS file server.  In addition, the appropriate Back Connection
 241 entries are added to the registry to allow SMB authentication to be
 242 performed across the loopback connection.
 243
 244 21. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote
 245 Admin Protocol which provides browsing of server and share information.
 246 This significantly enhances the functionality of AFS volumes within the
 247 Explorer Shell.
 248
 249 22. OpenAFS will now automatically forget a user's tokens upon Logoff
 250 unless the user's profile was loaded from an AFS volume.  In this situation
 251 there is no mechanism to determine when the profile has been successfully
 252 written back to the network.  It is therefore unsafe to release the user's
 253 tokens.
 254
 255 23. Terminal Server installations.
 256 When installing under Terminal Server, you must execute the installer
 257 from within the Add/Remove Programs Control Panel.  Failure to do so
 258 will result in AFS not running properly.  The AFS Server should not
 259 be installed on a machine with Terminal Server installed.
 260
 261 ------------------------------------------------------------------------
 262
 263 Reporting Bugs:
 264
 265 Bug reports should be sent to openafs-bugs@openafs.org.  Please include as
 266 much information as possible about the issue.  If you are reporting a crash,
 267 please install the debugging symbols by re-running the installer.  If a dump
 268 file is available for the problem include it along with the AFS Client Trace
 269 file  %WINDIR%\TEMP\afsd.log.  The AFS Client startup log is
 270 %WINDIR%\TEMP\afsd_init.log.  Send the last continuous block of log
 271 information from this file.
 272
 273 ------------------------------------------------------------------------
 274
 275 How to Contribute to the Development of OpenAFS for Windows:
 276
 277 Contributions to the development of OpenAFS for Windows are needed.
 278 Contributions may take many forms including cash donations, support contracts,
 279 donated developer time, and even donated tech writer time.
 280
 281 If you wish to be involved in OpenAFS for Windows development please join the
 282 openafs-win32-devel@openafs.org mailing list.
 283
 284   https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
 285
 286 User questions should be sent to the openafs-info@openafs.org mailing list.
 287
 288   https://lists.openafs.org/mailman/listinfo/openafs-info
 289
 290 You must join mailing lists if you wish to post to the list without incurring
 291 a moderation delay.
 292