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

   1 OpenAFS for Windows 1.3.66 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 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.
  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. As of 1.3.66, OpenAFS supports
 107 Authenticated SMB connections which removes the need for High Security mode.
 108 DO NOT USE IT!!!!!
 109
 110 7. The AFS Systray tool (afscreds.exe) supports several new command line
 111 options:
 112
 113     -A = autoinit
 114     -M = renew drive maps
 115     -N = ip address change detection
 116     -Z = unmap drives
 117
 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.
 122
 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
 125 start time.
 126
 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.
 131
 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
 135 Administrator:
 136
 137     - checkservers with a non-zero timer value
 138     - setcachesize
 139     - newcell
 140     - sysname with a new sysname list
 141     - exportafs
 142     - setcell
 143     - setserverprefs
 144     - storebehind
 145     - setcrypt
 146     - cscpolicy
 147     - trace
 148
 149 setting the default sysname for a machine should be done via the registry and
 150 not via "fs sysname".
 151
 152 Some of the AFS Client Configuration Control Panel options are also restricted
 153 to use by the "Administrator" account.
 154
 155 9. As of 1.3.65, the AFS Client should support UNC paths everywhere.
 156
 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.
 159
 160 Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
 161              [[-p | -path] pathname]
 162              [-noprdb] [-force]
 163              [-5 | -4]
 164
 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.
 172
 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.
 175
 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
 178 reports.
 179
 180 13. OpenAFS for Windows does not support files larger than 2GB.
 181
 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.
 187
 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.
 192
 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.
 196
 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.
 200
 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
 207 no longer be used.
 208
 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
 221 for each host.
 222
 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.
 228
 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.
 232
 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.
 238
 239 21.
 240
 241 ------------------------------------------------------------------------
 242
 243 Reporting Bugs:
 244
 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.
 252
 253 ------------------------------------------------------------------------
 254
 255 How to Contribute to the Development of OpenAFS for Windows:
 256
 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.
 260
 261 If you wish to be involved in OpenAFS for Windows development please join the
 262 openafs-win32-devel@openafs.org mailing list.
 263
 264   https://lists.openafs.org/mailman/listinfo/openafs-win32-devel
 265
 266 User questions should be sent to the openafs-info@openafs.org mailing list.
 267
 268   https://lists.openafs.org/mailman/listinfo/openafs-info
 269
 270 You must join mailing lists if you wish to post to the list without incurring
 271 a moderation delay.
 272