OpenAFS for Windows 1.4.0
Release Notes
The Andrew File System (AFS) is a location-independent file system that uses a local cache to increase its performance. An AFS client accesses files anonymously or via a Kerberos authentication. The global AFS is partitioned into cells. The AFS cell is a collection of AFS volumes that are administered by a common entity. AFS cells can be administered by a department even when the Kerberos realm used for local authentication is managed by a much larger organization. AFS clients and servers take advantage of Kerberos cross realm authentication to enable authenticated access by entities located outside the local realm. Authorization is enforced by the use of directory level access control lists which can consist of individual or group identities.
The AFS volume is a tree of files and sub-directories. AFS volumes are created by administrators and are joined to an AFS cell via the use of a mount point. Once a volume is created, users can create files and directories as well as mount points and symlinks within the volume without regard for the physical location of the volume. Administrators can move the volume to another server as necessary without the need to notify users. In fact, the volume move can occur while files in the volume are in use.
AFS volumes can be replicated to read-only copies. When accessing files from a read-only replica, clients will read all of the data from a single replica. If that replica becomes unavailable, the clients will failover to any replica that is reachable. Users of the data are unaware of where the replicas are stored or which one is being accessed. The contents of the replicas can be updated at any time by releasing the current contents of the source volume.
OpenAFS for Windows (OAFW) provides AFS client access Microsoft Windows operating systems. It strives to maintain transparency such that the user is unaware of the distinction between the use of AFS and Microsoft Windows file shares. OAFW can be part of a single sign-on solution by allowing credentials for a Kerberos principal to be obtained at logon and for that principal to be used to obtain AFS tokens for one or more cells. Although OAFW is implemented as a locally installed SMB to AFS gateway, OAFW maintains the portability of file paths by its use of the \\AFS UNC server name.
OpenAFS is the product of an open source development effort begun in July 2001. OpenAFS is maintained and developed by a group of volunteers with the support of the user community. If you use OpenAFS as part of your computing infrastructure please contribute to its continued growth.
4. How to Debug Problems with OpenAFS for Windows:
6. How to Contribute to the Development of OpenAFS for
Windows
It can be installed either as a new installation or an upgrade from previous versions of OpenAFS for Windows or IBM AFS for Windows. Installers are provided in two forms:
1. an executable (.exe) that is built using the Nullsoft Scriptable Installation System, or
2. a Windows Installer package (.msi) that is built using WiX and can be customized for organizations via the use of MSI Transforms (see MSI Deployment Guide)
· Microsoft Windows 2000 Workstation
· Microsoft Windows 2000 Server
· Microsoft Windows XP Home
· Microsoft Windows XP Professional
· Microsoft Windows 2003 Server
· Microsoft Windows 2003 R2 Server
· Microsoft Windows 95
· Microsoft Windows 98
· Microsoft Windows 98 OSR2
· Microsoft Windows ME
· Microsoft NT
· Microsoft Windows Vista (as of Beta 1 bugs in Windows prevent its use)
· All 64-bit versions of Microsoft Windows on Itanium and x86-64 chipsets.
Older releases of OpenAFS are available for download if those operating systems must be supported. The last version of OpenAFS with support for Win9x is 1.2.2b. The last version with support for Windows NT 4.0 is 1.2.10.
Up to 60mb required for the OpenAFS binaries plus 100MB for the default AFSCache file. (The size of the AFSCache file may be adjusted via the Registry after installation.)
MIT Kerberos for Windows 2.6.x if Kerberos 5 authentication support is desired.
The Kerberos 4 infrastructure on which the OpenAFS 1.2 series is reliant is no longer secure. Cross-realm Kerberos is very important in the AFS context and most sites have or are migrating to Kerberos 5 environments. The OpenAFS 1.4 series integrates with MIT Kerberos for Windows 2.6.5 to support Kerberos 5 authentication including automatic renewal of AFS tokens and single sign-on via the Microsoft Windows Kerberos Logon Service.
When KFW is installed, the OpenAFS 1.4 client will obtain Kerberos 5 tickets and use them as tokens without modification. The OpenAFS 1.4 client requires that all of the AFS Servers with which it communicates support the use of Kerberos 5 tickets as tokens. If Kerberos 5 based tokens are presented to an AFS server that does not understand them, the server will be unable to communicate with the client when tokens are present. Kerberos 5 based tokens are supported by OpenAFS release 1.2.8 or later. IBM Transarc servers do not support Kerberos 5.
There are two things to consider when using a Microsoft
Windows Active Directory as the Kerberos realm that issues the AFS service
ticket. First, the Kerberos 5 tickets
issued by Active Directory can be quite large when compared to tickets issued
by a traditional KDC due to the incorporation of authorization data in the
Some organizations which have AFS cell names and Kerberos realm names which differ by more then just lower and upper case rely on a modification to krb524d which maps a Kerberos 5 ticket from realm FOO to a Kerberos 4 ticket in realm BAR. This allows user@FOO to appear to be user@bar for the purposes of accessing the AFS cell. As of OpenAFS 1.2.8, support was added to allow the immediate use of Kerberos 5 tickets as AFS (2b) tokens. This is the first building block necessary to break away from the limitations of Kerberos 4 with AFS. By using Kerberos 5 directly we avoid the security holes inherent in Kerberos 4 cross-realm. We also gain access to cryptographically stronger algorithms for authentication and encryption.
Another reason for using Kerberos 5 directly is because the krb524 service runs on a port (4444) which has become increasingly blocked by ISPs. The port was used to spread a worm which attacked Microsoft Windows in the summer of 2003. When the port is blocked users find that they are unable to authenticate.
Replacing the Kerberos 4 ticket with a Kerberos 5 ticket is a win in all situations except when the cell name does not match the realm name and the principal names placed into the ACL’s are not the principal names from the Kerberos 5 ticket. To support this transition, OpenAFS for Windows 1.4 adds a new registry value, Use524, to force the use of krb524d. However, the availability of this option should only be used by individuals until such time as their organizations can provide a more permanent solution.
By itself the OpenAFS Client Service does not provide robust behavior in a plug-n-play network environment. Changes to the number of network adapters or their assigned IP addresses will cause the service to terminate unexpectedly. To avoid this behavior OpenAFS for Windows installs a single instance of the Microsoft Loopback Adapter (MLA) on the machine. With the MLA installed, the OpenAFS Client Service will not be affected by the configuration changes of other network adapters installed on the system.
The MLA is installed with a name of "AFS" and a pre-assigned IP address in the 10.x.x.x range. The MLA is bound to the “Client for Microsoft Networks” service and not bound to the “File and Printer Sharing for Microsoft Networks”. If the MLA is unbound to "Client Microsoft Networks", the OpenAFS Client Service will become inaccessible when the machine is disconnected from the network. If the MLA is bound to "File and Printer Sharing ..." there will be a service type collision between the name "AFS" and the name of the machine on the MLA's IP Address that will result in the OpenAFS client service becoming inaccessible and the "NET VIEW \\AFS" command will return a "System Error 52" message. To correct the problem:
· stop the AFS Client Service
· bind the "Client for Microsoft Networks" to the MLA
· unbind "File and Printer Sharing for Microsoft Networks" from the MLA
· Disable and then re-enable the MLA
· start the AFS Client Service
When the MLA is not installed the unique NETBIOS name published by OpenAFS SMB server is "MACHINE-AFS". One of the benefits of using the MLA is that the NETBIOS name does not have to be published on any adapter other than the MLA. Therefore the chosen name is no longer required to be unique. Instead the NETBIOS name associated with the AFS Client Service is simply "AFS" and portable UNC paths of the form \\AFS\cellname\path can now be used on all machines.
Traditionally, when the OpenAFS Client Service starts it must be able to access the "root.afs" volume of the default cell. The "root.afs" volume contains the set of mount points to the "root.cell" volumes of various cells the administrator of the default cell believes should be accessible. If the "root.afs" volume is inaccessible when the client service is started, the service will terminate unexpectedly. Since many users now use laptops or otherwise operate in disconnected environments in which a VPN may be required to access the cell's servers, it is often the case that the "root.afs" volume for the default cell is not reachable and the OpenAFS Client Service will not successfully start.
To allow the OpenAFS Client Service to operate in these environments, a fake "root.afs" volume is dynamically constructed from mount points and symlinks stored in the local registry. This method of operation is referred to as Freelance mode.
The content of the fake “root.afs” volume is dynamically modified as cells are accessed. When the fake "root.afs" volume is initially constructed it will only contain two mount points: a regular path and read-write path mount point used to access the "root.cell" volume of the default AFS cell. Any attempt to access a valid cell name will result in a new mount point being created in the fake "root.afs" volume. If the cellname begins with a "." the mount point will be a read-write path; otherwise the mount point will be a regular path. These mount points are preserved in the registry at key:
HKLM\SOFTWARE\OpenAFS\Client\Freelance
Additional mount points may be manually created using the "fs mkmount" command. Mount points may be removed using the "fs rmmount" command.
>fs mkmount \\AFS\athena.mit.edu root.cell athena.mit.edu
>fs mkmount \\AFS\.athena.mit.edu root.cell athena.mit.edu -rw
>fs rmmount \\AFS\athena.mit.edu
>fs rmmount \\AFS\.athena.mit.edu
Symlinks may also be created within the Freelance “root.afs” volume.
>symlink make \\afs\link \\afs\athena.mit.edu\user\j\a\jaltman
>symlink list \\afs\link
'\\afs\link' is a symlink to 'athena.mit.edu\user\j\a\jaltman'
>symlink rm \\afs\link
The symlinks are stored in the registry at:
HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks
The OpenAFS for Windows client will use DNS AFSDB records to discover the location of AFS Volume Database servers when entries are not present in the client's CellServDB file (\%PROGRAMFILES%\OpenAFS\Client\CellServDB).
OpenAFS for Windows installs a WinLogon Network Provider to provide Single Sign-on functionality (aka Integrated Logon.) Integrated Logon can be used when the Windows username and password match the username and password associated with the default cell's Kerberos realm. For example, if the Windows username is "jaltman" and the default cell is "athena.mit.edu", then Integrated Logon can be successfully used if the windows password matches the password assigned to the Kerberos principal "jaltman@ATHENA.MIT.EDU". The realm “ATHENA.MIT.EDU” is obtained by performing a domain name to realm mapping on the hostname of one of the cell's Volume Database servers.
Integrated Logon is required if you desire the ability to store roaming user profiles within the AFS file system. OpenAFS does not provide tools for synchronizing the Windows and Kerberos user accounts and passwords.
When KFW is configured, Integrated Logon will use it to obtain tokens. The Kerberos 5 tickets obtained during the process of generating AFS tokens are preserved and stored into the default ccache within the user logon session.
Integrated Logon does not have the ability to cache the user's username and password for the purpose of obtaining tokens if the Kerberos KDC is inaccessible at logon time.
Integrated Login supports the ability to obtain tokens for multiple cells. For further information on how to configure this feature read the TheseCells value in Appendix A.
The AFS System Tray tool (afscreds.exe) supports several command line options:
-A = autoinit
-E = force existing afscreds to exit
-I = install startup shortcut
-M = renew drive maps
-N = IP address change detection
-Q = quiet mode. do not display start service dialog
if afsd_service is not already running
-S = show tokens dialog on startup
-U = uninstall startup shortcut
-X = test and do map share
-Z = unmap drives
autoinit will result in automated attempts to acquire AFS tokens when afscreds.exe is started. afscreds.exe will attempt to utilize tickets stored in the MSLSA credentials cache; any existing CCAPI credentials cache; and finally display an Obtain Tokens dialog to the user. When used in combination with IP address change detection, afscreds.exe will attempt to acquire AFS tokens whenever the IP address list changes and the Kerberos KDC is accessible.
The renew drive maps option is used to ensure that the user drive maps constructed via the OpenAFS tools (not NET USE) are re-constructed each time afscreds.exe is started.
By default afscreds.exe is configured by the OpenAFS.org installers to use “-A -N -M -Q” as startup options. Currently, there is no user interface to change this selection after install time although these options may be altered via the registry on either per machine or per user basis. See AfscredsShortcutParams in Appendix A.
The OpenAFS for Windows 1.4 client supports a local Windows authorization group named "AFS Client Admins". This group is used in place of the "Administrators" group to determine which users are allowed to modify the AFS Client Service configuration via the AFS Control Panel (afs_config.exe) or fs.exe command line tool. The following fs.exe commands are now restricted to members of the "AFS Client Admins" group:
· checkservers with a non-zero timer value
· setcachesize
· newcell
· sysname with a new sysname list
· exportafs
· setcell
· setserverprefs
· storebehind
· setcrypt
· cscpolicy
· trace
The creation or removal of mount points and symlinks in the Freelance “root.afs” volume are also restricted to members of the “AFS Client Admins” group.
The initial membership of the "AFS Client Admins" group when created by the installer is equivalent to the local "Administrators" group. If a user is added to the "Administrators" group after the creation of the "AFS Client Admin" group, that user will not be an AFS Client Administrator. Only users that are members of the "AFS Client Admins" group are AFS Client Administrators. The local "SYSTEM" account is an implicit member of the "AFS Client Admins" group.
Setting the default sysname for a machine should be done via the registry and not via "fs sysname".
The OpenAFS 1.4 client supports UNC paths everywhere. UNC paths provide a canonical name for resources stored within AFS. UNC paths should be used instead of drive letter mappings whenever possible. This is especially true when specifying the location of roaming profiles and redirected folders.
Power users that make extensive use of the command line shell, cmd.exe, should consider using JP Software's 4NT or Take Command command processors. Unlike cmd.exe, the JPSoftware shells fully support UNC paths as the current directory. With the release of version 4NT 7.0 and Take Command 7.0, JPSoftware is adding special recognition of OpenAFS. AFS paths can be entered in UNIX notation (e.g., /afs/openafs.org/software), space utilization reports the output of the volume status for the specified path, and many AFS specific functions and variables have been added to the command language.
JPSoftware's web site is http://www.jpsoft.com.
The OpenAFS 1.4 Client ships with its own version of aklog.exe which should be used in preference to those obtained by third party sources. The OpenAFS aklog.exe supports Kerberos 5 as well as the ability to auto-generate pts IDs for user's obtaining tokens for access to foreign cells.
Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
[[-p | -path] pathname]
[-noprdb] [-force]
[-5 [-m]| -4]
-d = output debugging information.
cell = zero or more cells for which tokens will be obtained
krb_realm = the kerberos realm of the cell.
pathname = the directory for which authentication is required
-noprdb = don't try to determine AFS ID.
-5 or -4 = use Kerberos V (default) or Kerberos IV tickets
-m = use krb524d to convert Kerberos V tickets to Kerberos IV
The AFS Server functionality provided with OpenAFS 1.4 might work but should be considered highly experimental. It has not been thoroughly tested. Any data which would cause pain if lost should not be stored in an OpenAFS Server on Windows.
A few notes on the usage of the AFS Client Service if it is going to be used with the OpenAFS AFS Server:
· When installed on the same machine as the AFS Server, Freelance mode must be turned off. Otherwise, you will be unable to manipulate the contents of the root.afs volume for the hosted cell.
· The AFS Server and related tools only support the built in kaserver (Kerberos IV). If the AFS Server is being used, MIT Kerberos for Windows should not be installed or must be disabled.
The OpenAFS for Windows installers now include Debugging Symbol files which should be installed if you are experiencing problems and need to send crash reports. This is true for both the release and the debug versions of the installers. The difference between the release and debug versions are:
· whether or not the binaries were compiled with opt