OpenAFS for Windows 1.5.33
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 on October 31 2000. 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
1.
Installer Options
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)
2.
System Requirements
2.1 Supported Operating
Systems
· Microsoft Windows 2000 Workstation
· Microsoft Windows 2000 Server
· Microsoft Windows XP Home
· Microsoft Windows XP Professional
· Microsoft Windows XP 64
· Microsoft Windows 2003 Server (32-bit and 64-bit Intel)
· Microsoft Windows 2003 R2 Server (32-bit and 64-bit Intel)
· Microsoft
Windows
· Microsoft Windows 2008 Server (32-bit and 64-bit Intel)
2.1.1
Unsupported Operating Systems
· Microsoft Windows 95
· Microsoft Windows 98
· Microsoft Windows 98 OSR2
· Microsoft Windows ME
· Microsoft NT
Older releases of OpenAFS are available for download if unsupported operating systems must be used. 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.
2.2 Disk Space
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.)
2.3 Additional Software Packages
MIT Kerberos for Windows 2.6.x or 3.x.x if Kerberos v5 authentication support is desired. The recommended release is version 3.2.2.
3.
Operational Notes
3.1. Requirements for
Kerberos v5 Authentication
The Kerberos v4 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 v5 environments. The OpenAFS 1.4 series (and later) integrates with MIT Kerberos for Windows 2.6.5 and above to support Kerberos v5 authentication including automatic renewal of AFS tokens and single sign-on via the Microsoft Windows Kerberos Logon Service.
The recommended version of MIT Kerberos for Windows is 3.2.2. KFW 3.2.2 includes Network Identity Manager 1.3.1 which integrates with the AFS Provider installed as part of OpenAFS for Windows.
When KFW is installed, the OpenAFS for Windows client will obtain Kerberos v5 tickets and use them as tokens without modification. The OpenAFS client requires that all of the AFS Servers with which it communicates support the use of Kerberos v5 tickets as tokens. If Kerberos v5 based tokens are presented to an AFS server that does not support them, the server will be unable to communicate with the client when tokens are present. Kerberos v5 based tokens are supported by OpenAFS release 1.2.8 or later. IBM Transarc servers do not support Kerberos v5.
3.1.1.
Active Directory
Microsoft Windows Active Directory can be used as a Kerberos v5 KDC in conjunction with OpenAFS. There are two things to consider when using an Active Directory as the Kerberos realm that issues the AFS service ticket. First, the Kerberos v5 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 (the Microsoft PAC). If the issued tickets are larger than 344 bytes, the OpenAFS 1.2 servers will be unable to process them and will issue a RXKADBADTICKET error. OpenAFS 1.4 (and beyond) servers can support the largest tickets that Active Directory can issue. Second, the Kerberos v5 tickets issued by Windows 2003 Active Directory are encrypted with the DES-CBC-MD5 encryption type (enctype). OpenAFS 1.2 servers only support the DES-CBC-CRC enctype. As a result, OpenAFS 1.2 servers cannot process the resulting Kerberos v5 tokens. Windows 2000 Active Directory issues tickets with the DES-CBC-CRC enctype.
Microsoft has documented in Knowledge Base article 832572
a new NO_AUTH_REQUIRED flag that can be set on the account mapped to the AFS
service principal. When this flag is
set, the PAC authorization data will not be included in the ticket. Setting this flag is recommended for all
accounts that are associated with non-Windows services and that do not
understand the authorization data stored in the
Note that an Active Directory computer object cannot be used for the afs service principal.
3.1.2.
Using the krb524 service
Some organizations have AFS cell names and Kerberos realm names which differ by more then just lower and upper case and rely on a modification to krb524d which maps a Kerberos v5 ticket from realm FOO to a Kerberos v4 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 v5 tickets as AFS (2b) tokens. This is the first building block necessary to break away from the limitations of Kerberos v4 with AFS. By using Kerberos v5 directly we avoid the security holes inherent in Kerberos v4 cross-realm. We also gain access to cryptographically stronger algorithms for authentication and encryption.
Another reason for using Kerberos v5 directly is because the krb524 service runs on a port (4444/udp) which has increasingly been 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 v4 ticket with a Kerberos v5 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 v5 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.
Note that the OpenAFS 1.4.x servers permit the use of a secondary realm name that can be treated as equivalent to the cell name for authentication.
3.1.3.
Network Identity Manager Provider
As of release 1.5.9, OpenAFS for Windows includes a Network Identity Manager Provider for obtaining AFS tokens. This plug-in is a contribution from Secure Endpoints Inc. Network Identity Manager is a multiple identity credential management tool that ships with MIT Kerberos for Windows version 3.0 and above. The OpenAFS plug-in requires MIT Kerberos for Windows version 3.1 or above. Version 3.2.2 is recommended for the best user experience.
The Network Identity Manager replaces the former KFW ticket manager, Leash”, and when combined with the OpenAFS Provider, it is intended to be used as a replacement for the AFS System Tray Tool (afscreds.exe). Unlike both Leash and the AFS System Tray Tool, Network Identity Manager with the OpenAFS Provider can easily manage AFS tokens for multiple cells from one or more Kerberos v5 identities.
The AFS configuration panel for each Kerberos v5 identity is used to configure which cells credentials should be obtained for and how they should be obtained. If the cell to realm mapping cannot be automatically determined, it can be explicitly specified. If the cell does not support Kerberos v5 tickets as tokens, then a krb524 service can be configured.
The OpenAFS Provider configuration panel can be used to check the status of the AFS Client Service and its version. An optional checkbox is provided that will prevent the AFS System Tray Tool from being started by Windows after login. A shortcut to the OpenAFS Control Panel is also provided.
3.2. Use of the Microsoft
Loopback Adapter
by the AFS Client Service
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.
3.3. Using Freelance (Dynamic
Root) Mode to Improve Mobility
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, Freelance mode dynamically constructs a fake "root.afs" volume from mount points and symlinks stored in the local registry.
The content of the fake “root.afs” volume is dynamically generated 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
3.4. Locating AFS Volume
Database Servers
via DNS
The OpenAFS for Windows client will use DNS AFSDB records to discover the location of AFS Volume Database servers when entries for the cell are not present in the client's CellServDB file (\%PROGRAMFILES%\OpenAFS\Client\CellServDB).
3.5. Obtaining AFS Tokens as
a Integrated Part of Windows Logon
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. Use of KFW for Integrated Logon can be disabled via the EnableKFW registry value. Use of the krb524 service can be configured via the Use524 registry value.
Integrated Logon will not transfer Kerberos v5 tickets into the user’s logon session credential cache. KFW 3.1 and above provides that functionality on its own.
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 Logon supports the ability to obtain tokens for multiple cells. For further information on how to configure this feature read about the TheseCells value.
Integrated
Logon can be configured based upon the domain of the Windows account used to
login to the machine. See A.2.1 Domain specific configuration keys for
the Network Provider.
3.6. AFS System Tray Command
Line Options
The AFS System Tray Tool
(afscreds.exe) has been deprecated in favor of Network Identity Manager. afscreds.exe will be removed from the OpenAFS
in a future release.
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.
3.7. The “AFS Client Admins”
Authorization Group
The OpenAFS for Windows 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
· minidump
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".
3.8. OpenAFS support for UNC
paths
The OpenAFS 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. JPSoftware added special recognition for OpenAFS to its command shells, 4NT 7.0 and Take Command 7.0. 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.
3.9. aklog.exe
The OpenAFS Client ships with its own version of aklog.exe which should be used in preference to those obtained by other sources. The OpenAFS aklog.exe supports Kerberos v5 as well as the ability to auto-generate AFS IDs within foreign PTS databases.
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
3.10. OpenAFS Servers on
Windows are Unsupported
The AFS Server functionality provided as part of the OpenAFS install package 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.
Known issues include lack of support for power management and dynamic network configuration. Salvager is also known to crash.
3.10.1.
OpenAFS Server Installation
When the OpenAFS Server is installed, the TransarcAFSServer service (bosctlsvc.exe) will be installed and configured. The TransarcAFSServer service will auto-start the traditional AFS bos server. The former AFS Server Configuration wizard makes assumptions that no longer hold true and it has therefore been disabled. However, following the instructions for installing the AFS Servers on UNIX it is possible to properly configure the AFS Servers on Microsoft Windows. The AFS Server binaries, configuration files, and log files are installed under %Program Files%\OpenAFS\Server. kaserver has been deprecated and its use is strongly discouraged. Instead, Active Directory or some other Kerberos v5 KDC should be used in its place.
3.10.2.
Using the AFS Client Service when the Server is installed
A few notes on the usage of the AFS Client Service if it is going to be used with the OpenAFS AFS Server:
· Freelance mode should be disabled when the AFS Client Service is installed on the same machine as the AFS Server,. Otherwise, you will be unable to manipulate the contents of the root.afs volume for the hosted cell without constructing an explicit mountpoint to the root.afs volume from another volume.
· The AFS Server and related tools only support the built in kaserver (Kerberos IV). If kaserver is being used, MIT Kerberos for Windows should not be installed or must be disabled via the EnableKFW registry value.
· The AFS Servers are not aware of power management events nor are they aware of network configuration changes. It is strongly advised that the AFS servers be installed only on systems that will not be shutdown or suspended unexpectedly. An inadvertent shutdown will corrupt volume data.
3.11. OpenAFS Debugging
Symbol files
The OpenAFS for Windows installers 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 optimization (release: yes, debug: no)
· whether or not the debug symbols are installed by default (release: no, debug: yes)
· whether
or not fs trace logging is turned on
by default (release: no, debug: yes)
· whether or not additional debug statements were compiled into the binaries (release: no, debug: yes)
3.12. Large File (64-bit) Support
As of release 1.5.3, OpenAFS for Windows supports files larger than 2GB. The maximum file size is now 16777216 terabytes when the AFS File Server supports large files. If the AFS File Server does not support 64-bit file sizes, then the maximum file size remains 2GB.
3.13. Encrypted AFS Network
Communication
The OpenAFS for Windows installer by default activates a weak form of encrypted data transfer between the AFS client and the AFS servers. This is often referred to as "fcrypt" mode. Encrypted data transfer can be turned on or off with the “fs crypt” command. Transitions between “crypt” and “non-crypt” modes are logged to the Windows Application Event Log.
3.14. Authenticated Access to
the OpenAFS Client Service
OpenAFS authenticates SMB connections using either NTLM or GSS SPNEGO (NTLM). In previous versions of OpenAFS, the SMB connections were unauthenticated which opened the door for several attacks which could be used to obtain access to another user's tokens on shared machines.
When GSS SPNEGO attempts a Kerberos v5 authentication, the Windows SMB client will attempt to retrieve service tickets for "cifs/afs@REALM" (if the loopback adapter is in use) or "cifs/machine-afs@REALM" (if the loopback adapter is not being used). It is extremely important that this service principal not exist in the KDC database as the Kerberos authentication must fail allowing automatic fallback to NTLM. When NTLM is used a special local authentication mode will be used that does not require access to the user's password. Instead, Windows will internally recognize the request as coming from a local logon session.
3.15. No More INI Files
Previous AFS clients for Windows stored configuration data in Windows .INI files. The OpenAFS client does not use Windows .INI files for the storage of configuration data. All settings are stored in the registry (see Appendix A). The CellServDB file is now stored in either the %ALLUSERSPROFILE%\Application Data\OpenAFS\Client directory or the %PROGRAMFILES%\OpenAFS\Client directory. The CellServDBDir registry value or the AFSCONF environment variable can be used to specify an alternative location.
For users converting from IBM AFS clients, during installation OpenAFS will relocate the contents of the “afsdcell.ini” file to the new CellServDB file. OpenAFS will also import the contents of the “afs_freelance.ini” file to the Windows registry. OpenAFS will not process the contents of the “afsddbmt.ini”.
3.16. Microsoft Windows
Internet Connection Firewall
The OpenAFS Client is compatible with the Internet Connection Firewall that debuted with Windows XP SP2 and Windows 2003 SP1. The Internet Connection Firewall will be automatically adjusted to allow the receipt of incoming callback messages from the AFS file server. In addition, the appropriate Back Connection registry entries are added to allow SMB authentication to be performed across the Microsoft Loopback Adapter.
3.17. Browsing AFS from the
Explorer Shell and Office
The OpenAFS Client Service implements the CIFS Remote Admin Protocol which allows Explorer to browse server and share information. This significantly enhances the interoperability of AFS volumes within the Explorer Shell and Microsoft Office applications.
3.18. Byte Range
Many applications on Windows (e.g. Microsoft Office) require the use of byte range locks applied to a file either to protect against simultaneous file access or as a signaling mechanism. OpenAFS for Windows release 1.5 (or greater) implements byte range locking within the CIFS-AFS gateway server. This support for byte range locking obtains AFS’ advisory file server locks to simulate Microsoft Windows mandatory locks. When an application opens a file, a lock will be obtained from AFS indicating that the file is in use. If the lock is a write lock, access to the file will be restricted to other applications running on the same machine as the first application to request the lock. Applications running on other machines will see the AFS full file lock and will be unable to access the file.
Most Windows applications and Windows itself opens files in shared read mode. When this is done, a read lock is applied to the file. This does not prevent shared read access across multiple machines but is used to ensure that no one writes to the file while it is in use.
As the CIFS-AFS gateway server attempts to implement Windows lock semantics on top of AFS lock semantics it is important to understand how AFS file locks work. In Windows there are no special privileges associated with obtaining file locks. If you can read or execute a file, then you can obtain shared and exclusive locks. In general, a Windows shared lock equates to an AFS read lock and a Windows exclusive lock equates to an AFS write lock. In AFS if you can write to a file, then you can obtain a write lock. However, in AFS if you can read a file it does not mean that you can obtain a read lock on it. The ability to obtain read locks is granted only if you have the lock (or ‘k’) privilege. This behavior is required in order to allow anonymous users to read files while preventing them from being able to deny access to the files to other users. OpenAFS 1.4.0 and earlier as well as all IBM AFS file servers have an implementation bug that prevents users with write privileges from being able to obtain locks without the lock privilege. When AFS serves data out of read-only volumes the file server will deny all requests for read and write locks because the contents of the volume cannot be changed by the client.
Since Microsoft Windows applications almost always attempt to obtain a temporary exclusive lock when accessing files the OpenAFS Client’s CIFS-AFS gateway implements the following semantics in order to reduce the inconvenience on end users.
- If the file is located on a read-only volume and the application requests a shared lock, the CIFS-AFS server will grant the lock request without asking the AFS file server.
- If the file is located on a read-only volume and the application opens the file with write access and requests an exclusive lock, the CIFS-AFS server will refuse the lock request and return a read only error.
- If the file is located on a read-only volume and the application opens the file with only read access and requests an exclusive lock, the CIFS-AFS server will fulfill the lock request with a read lock.
- If the file is located on a read-write volume and the application requests an exclusive lock, the CIFS-AFS server will request a write lock from the AFS file server. If granted by the file server, then the CIFS-AFS server will grant the lock request. If the request is denied due to an access denied error and the user has the lookup, read and lock privileges and the file was opened for read only access, then the CIFS-AFS server will request a read lock from the file server. If the request is denied due to an access denied error and the user has the lookup and read privileges but not the lock privilege, then the CIFS-AFS server will grant the request even though the AFS file server said ‘no’. If the user does not have at least those permissions, the CIFS-AFS server will deny the request.
- If the file is located on a read-write volume and the application requests a shared lock, the CIFS-AFS server will request a read lock from the AFS file server. If granted by the file server, then the CIFS-AFS server grants the lock request. If the request is denied due to an access denied error and the user has the lookup and read privileges but not the lock privilege, then the CIFS-AFS server will grant the request even though the AFS file server said ‘no’. If the user does not have at least those permissions, the CIFS-AFS server will deny the request.
- If multiple processes on the same machine attempt to access the same file simultaneously, the CIFS-AFS server will locally manage the granted locks and all processes will share a single lock on the AFS file server.
- If the CIFS-AFS server is unable to renew the AFS file server locks, then it will invalidate the associated file handles. This is the same behavior that an application will experience if it was using a Windows File Share and the connection was broken. Invalidating the file handles prevents subsequent data corruption from taking place.
If you wish to disable the acquisition of locks from the file server, this can be performed using the EnableServerLocks registry value.
3.19. Automatic Discarding of
AFS Tokens at Logoff
The OpenAFS Client will automatically forget a user's tokens upon Logoff unless the user's profile was loaded from an AFS volume. In this situation there is no mechanism to determine when the profile has been successfully written back to the network. It is therefore unsafe to release the user's tokens. Whether or not the profile has been loaded from the registry can be determined for Local Accounts, Active Directory accounts and NT4 accounts.
If there is a need to disable this functionality, the LogoffPreserveTokens registry value can be used. (see Appendix A.)
3.20. Windows Terminal Server
installations
When installing the NSIS (.exe) installer under Terminal Server, you must execute it from within the Add/Remove Programs Control Panel. Failure to do so will result in AFS not running properly. The AFS Server should not be installed on a machine with Terminal Server installed.
3.21. Hidden Dot Files
AFS is a UNIX native file system. The OpenAFS client attempts to treat the files stored in AFS as they would be on UNIX. File and directory names beginning with a "." are automatically given the Hidden attribute so they will not normally be displayed. This behavior can be altered via the HideDotFiles registry value.
3.22. Status Cache Limits
The Status Cache (AFS Configuration Control Panel: Advanced Page) is defined to have a maximum number of entries. Each entry represents a single file or directory entry accessed within the AFS file system. When the maximum number of entries are allocated, entries will begin to be reused according to a least recently used (LRU) algorithm. If the number of files or directories being accessed repeatedly by your applications is greater then the maximum number of entries, your host will begin to experience thrashing of the Status Cache and all requests will result in network operations.
If you are experiencing poor performance try increasing the maximum number of Status Cache entries. Each entry requires approximately 1.2K. The default number of Status Cache entries is 10,000. This can be adjusted using the Stats registry value.
3.23. NETBIOS over TCP/IP
must be enabled
"Netbios over TCP/IP" must be active on the machine in order for communication with the AFS Client Service to succeed. If "Netbios over TCP/IP" is disabled on the machine, then communication with the AFS Client Service will be impossible. If you are using the Microsoft Loopback Adapter, configure the “Netbios over TCP/IP” setting for the adapter.
3.24. OpenAFS binaries are
digitally signed
The OpenAFS Client Service and related binaries distributed by OpenAFS.org are digitally signed by "Secure Endpoints Inc.". The OpenAFS Client Service will perform a run-time verification check to ensure that all OpenAFS related DLLs loaded by the service match the same file version number and were signed by the same entity. This check has been added to prevent the stability problems caused by more than one AFS installation present on a machine at the same time. Many hours of support time have been wasted tracking down problems caused by the mixture of files from different releases.
Appendix A documents the "VerifyServiceSignature" registry value which can be used to disable the signature check. The file version check cannot be disabled.
3.25. Maximum Size of the
AFSCache File
The maximum cache size on 32-bit Windows is approximately 1.3GB. This is the largest contiguous block of memory in the 2GB process address space which can be used for constructing a memory mapped file. Due to fragmentation of the process space caused by the loading of libraries required by the digital signature verification code, any attempt to specify a cache size greater then 700MB will result in the automatic disabling of the signature check. Significantly larger cache sizes can be used on 64-bit Windows.
3.26. Filename Character Sets
OpenAFS for Windows implements an SMB server which is used
as a gateway to the AFS filesystem. Because of limitations of the SMB
implementation, Windows stores all files into AFS using OEM code pages such as
CP437 (United States) or CP850 (Western Europe). These code pages are
incompatible with the ISO Latin-1 character set typically used as the default
on UNIX systems in both the
|
[Ç] 128 08/00 200
80 C cedilla
[ü] 129 08/01 201 81 u diaeresis
[é] 130 08/02 202 82 e acute
[â] 131 08/03 203 83 a circumflex
[ä] 132 08/04 204 84 a diaeresis
[à] 133 08/05 205 85 a grave
[å] 134 08/06 206 86 a ring
[ç] 135 08/07 207 87 c cedilla
[ê] 136 08/08 210 88 e circumflex
[ë] 137 08/09 211 89 e diaeresis
[è] 138 08/10 212 8A e grave
[ï] 139 08/11 213 8B i diaeresis
[î] 140 08/12 214 8C i circumflex
[ì] 141 08/13 215 8D i grave
[Ä] 142 08/14 216 8E A diaeresis
[Å] 143 08/15 217 8F A ring
[É] 144 09/00 220 90 E acute
[æ] 145 09/01 221 91 ae diphthong
[Æ] 146 09/02 222 92 AE diphthong
[ô] 147 09/03 223 93 o circumflex
[ö] 148 09/04 224 94 o diaeresis
[ò] 149 09/05 225 95 o grave
[û] 150
09/06 226 96 u circumflex
[ù] 151 09/07 227 97 u grave
[ÿ] 152
09/08 230 98 y diaeresis
[Ö] 153 09/09 231 99 O diaeresis [Ü] 154 09/10 232 9A U diaeresis [ø] 155 09/11 233 9B o slash [£] 156 09/12 234 9C Pound sterling sign [Ø] 157 09/13 235
9D O slash
[×] 158 09/14 236 9E Multiplication sign
[ƒ] 159 09/15 237 9F |
The OpenAFS Client provides an optional registry value, StoreAnsiFilenames, that can be set to instruct OpenAFS to store filenames using the ANSI Code Page instead of the OEM Code Page. The ANSI Code Page is a compatible superset of Latin-1. This setting is not the default setting because making this change would prevent OpenAFS for Windows from being able to access filenames containing the above characters which were created without this setting.
3.27. Known Character Set
Issues with Roaming Profiles
There is a known issue with storing Windows Roaming Profiles when the profile contains either directories or files with names which cannot be represented in the local OEM character set. In this case, attempts to write the profile back to AFS will fail during the character set conversion. The OpenAFS Client’s CIFS gateway does not support UNICODE. To avoid this problem some sites run custom logoff scripts (assigned by group policy) which rename all files to use only the supported characters for the locale.
3.28. The AFSCache File
The AFS Cache file is stored by default at %TEMP%\AFSCache in a persistent file marked with the Hidden and System attributes. The persistent nature of the data stored in the cache file improves the performance of OpenAFS by reducing the number of times data must be read from the AFS file servers.
The performance of the AFS Client Service is significantly affected by the access times associated with the AFSCache paging file. When given the choice, the AFSCache file should be placed on a fast disk, preferably NTFS, the file should not be compressed and should consist of as few fragments as possible. Significant performance gains can be achieved by defragmenting the AFSCache file with Sysinternal's Contig utility while the AFS Client Service is stopped.
3.29. Restricting OpenAFS
Client Service Start and Stop
A new command line tool, afsdacl.exe, can be used to restrict the ability to start and stop the OpenAFS Client Service.
afsdacl : Set or reset the DACL to allow starting or stopping
the afsd service by any ordinary user.
Usage : afsdacl [-set | -reset] [-show]
-set : Sets the DACL
-reset : Reset the DACL
-show : Show current DACL (SDSF)
3.30. The @sys Name List
The default @sys name list in the OpenAFS Client is set to "x86_win32 i386_w2k i386_nt40" for 32-bit x86 systems. The default is "amd64_win64" for amd 64-bit versions of Windows.