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.

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 Vista (32-bit and 64-bit Intel)

·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.The maximum cache size for 32-bit Windows is approximately 1.2GB.On 64-bit Windows there is no practical limit
on the cache size.

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.For 64-bit Windows installations,
the 64-bit version of Kerberos for Windows is required.For 32-bit Windows installations, the 32-bit
version of Kerberos for Windows is required.

3. Operational Notes

Starting with the
1.5.50 release of OpenAFS for Windows, each of the AFS Client Service, the AFS
Explorer Shell Extension, and the command-line tools are Unicode enabled.No longer is OpenAFS restricted to accessing
file system objects whose names can be represented in the locale specific OEM
code page.This has significant benefits
for end users.Most importantly it
permits non-Western languages to now be used for file system object names in
AFS from Microsoft Windows operating systems.Now that Unicode names are supported, Roaming User Profiles
and Folder Redirection
will no longer fail when a user attempts to store an object with a name that
cannot be represented in the OEM code page.

Unicode names are
stored in AFS using UTF-8 encoding.UTF-8
is supported as a locale on MacOS X, Linux, Solaris, and most other operating
systems.This permits non-Western object
names to be exchanged between Microsoft Windows and other operating systems.The OpenAFS for Windows client also
implements Unicode Normalization
as part of the name lookup algorithm.This is necessary because Unicode does not provide a unique
representation for each input string.The use of normalization permits a file system object name created on
MacOS X to be matched with the same string entered on Microsoft Windows even
though the operating system’s choice of representation may be different.

It is important to
note that AFS file servers are not character set agnostic.All file system object names are stored as
octet strings without any character set tagging.If a file system object is created using OEM
Code Page 858 and then interpreted as UTF-8 it is likely that the object name
will appear to be gibberish.OpenAFS for
Windows goes to great lengths to ensure that the object name is converted to a
form that will permit the user to rename the object using Unicode.Accessing UTF-8 names on UNIX systems that
have the locale set to one of the ISO Latin character sets will result in the
UTF-8 strings appearing to be gibberish.

Neither UNIX AFS
nor Microsoft Windows 2000 systems can perform Unicode Normalization for string
comparisons.Although it is possible to
store and read Unicode object names, it is possible that a user may not be able
to open an object by typing the name of the object at the keyboard.GUI point and click operations should permit
any object to be accessed.

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 PAC.This flag cannot be used if AFS service
tickets are obtained via cross-realm using an Active Directory user principal.

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:

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.

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.

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.

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.

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. ByteRange
Locking

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.

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.

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 United States
and Western Europe. Filenames stored by
OpenAFS for Windows are therefore unreadable on UNIX systems if they include
any of the following characters:

[Ç] 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 Florin
sign

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.

3.31. Symlinks to AFS UNC paths

In OpenAFS, symlinks to AFS UNC paths, \\AFS[\all]\..., are
treated the same as symlinks to /afs/... However, please use /afs/... as
the Windows UNC form will not work on UNIX client.

3.32. Cache Manager Debugging

The OpenAFS Client implements the Cache Manager Debugging
RPC Interface. The CM debugger can be queried with cmdebug.exe.

3.33. Windows Logon Caching vs. Kerberos
Logons

If you are a site which utilizes MIT/Heimdal Kerberos
principals to logon to Windows via a cross-realm relationship with a
multi-domain Windows forest, you must enable Windows logon caching unless the
workstation is Windows Vista.

3.34. Initial Server Preferences

VLDB and File Server Preferences can now be provided initial
values using registry keys. This is useful for managed machines in a
Windows domain which are centrally located (e.g., in a computing lab.)
See Appendix A for details on the
"Server Preferences" keys.

3.35. File Timestamps

The OpenAFS Client reports timestamps on files stored in AFS
in UTC all year round. In locales with daylight savings time, previous
versions of AFS for Windows reported the time when DST is active as
UTC+1. This was done to preserve the relative local time for the user.
A file stored at 11:00am EST in January would be reported as having been stored
at 11:00am EDT in June. Unfortunately, this has the negative side effect
of changing the reported timestamp from 16:00UTC to 15:00UTC. Since
Windows treats all file times in UTC, data synchronization applications which
rely on the timestamp would believe that all files stored in AFS had changed.

It should be noted that UNIX based operating systems (such
as Solaris) do not appear to report file times to applications in UTC. They
do preserve the relative local time. This may confuse some users who are
used to being able to compare the timestamp in an UNIX shell with the timestamp
from the Windows explorer. During DST, these two times will no longer
agree even though they are in fact representing the same moment in time.

3.36. Windows RPC client support must be
installed

If the installer refuses to install and complains about an
RPC configuration error, check to ensure that the following registry entries
are present and that they refer to the dll "rpcrt4.dll":

HKLM
"SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_np"

HKLM
"SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_ip_tcp"

HKLM
"SOFTWARE\Microsoft\RPC\ClientProtocols" "ncadg_ip_udp"

HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols"
"ncacn_http"

3.37. Generating Minidumps of the OpenAFS
Client Service

OpenAFS 1.4 added a new command, "fs
minidump". This command can be used at any time to generate a mini
dump file containing the current stack of the afsd_service.exe process.
This output can be very helpful when debugging the AFS Client Service when it
is unresponsive to SMB/CIFS requests.

The OpenAFS Client implements Universally Unique Identifiers
(UUIDs). They are used to provide the AFS file server with a method of
identifying the client that is independent of IP address. This permits
the AFS file server to track mobile clients or those behind Network Address
Translators when they move from address to address or port to port. Tracking
the client improves client performance by permitting callback state to be
maintained across location changes. The UUID is generated when the AFSCache
file is created and is maintained as long as the contents of the AFSCache file
are valid. The UUID is stored in the AFSCache file.

When cloning machines that have Windows AFS client installed
it is necessary to generate a new UUID for each client. This will be done
automatically if the Windows Machine SID is re-generated using Microsoft
SysPrep. If the SID is not being re-generated either the AFSCache file should
be deleted or the command fs uuid -generate must be executed after the
the clone is created. Multiple AFS clients reporting the same UUID will not
only result in horrible AFS client performance and cache inconsistencies, but
they will also put a tremendous strain on the AFS file servers.

For lab environments that wish to erase all cached data on
each restart, the NonPersistentCaching option will
disable the use of the persistent cache file. As a side effect, a new UUID will
be generated for the AFS client service on each restart.

When a Windows system is cloned, the Microsoft Loopback
Adapter will be disabled in the cloned system.Administrators must re-install the Microsoft Loopback Adapter within the
cloned environment.This can be
automated by using the OpenAFS “instloop.exe
–i” command.Instloop.exe can be extracted from the MSI
installer by performing an administrative install via msiexec.exe /a.

Microsoft Office makes heavy use of asynchronous
input/output methods for reading and writing to file streams. This can result
in hundreds of requests being simultaneously queued for service by the CIFS
client with a fixed timeout period. As the AFS CIFS server is local to
the machine the Windows CIFS client believes that it can respond almost
instantaneously to write requests as the actual writing to the AFS file server
is performed by a background daemon thread. When the actual network
bandwidth to the AFS file server is slow and the file size is large it is
possible for the CIFS client to time out the connection. When this
happens a “delayed write error” will be reported to the user and the
application may crash. The only workaround at the current time is to save
first to a local disk and subsequently copy the file to AFS as copying a file
with the explorer shell does not use asynchronous i/o.

The CIFS session timeout defaults to 45 seconds and can be
increased by modifying the registry.

Beginning with the 1.5.33 release, the performance
characteristics of SMB Write Data operations can be adjusted.In prior releases all writes were performed
using a restricted asynchronous store model in which only one asynchronous
store operation per file can be performed at a time.The reason for this restriction is limit the
amount of data the cache manager will accept without it having been written to
the file server.If too much unwritten
data is accepted, the file close operation will block until all of the
unwritten data is output and this could trigger a CIFS client disconnect.

Prior to 1.5.33 the size of the asynchronous store was
always equal to the chunk size which was often too large for low bandwidth
connections.The asynchronous store size
now defaults to 32KB and is configurable using the SMBAsyncStoreSize registry
value.Asynchronous store operations can
also be disabled using the EnableSMBAsyncStore
registry value in which case all writes received by the cache manager block
until the Rx StoreData operation completes.

It says that services mounting drive letters are no longer
supported by Microsoft and may act unpredictably. The experience other
users have had is that if the connection to the OpenAFS CIFS/SMB server is
terminated by the Windows CIFS client, the drive mapping may not be
re-established until the machine is rebooted.

OpenAFS supports UNC paths and whenever possible
applications should be modified to use of \\AFS\<cellname>\<path>
instead of drive letters.

Although 64-bit Windows platforms support both 64-bit and
32-bit applications, the OpenAFS Service installed on the machine must be
64-bit. The 64-bit installer contains only 64-bit executables. In
order to support 32-bit applications that link against OpenAFS libraries it is
required that a separate 32-bit OpenAFS Tools set be installed.For example, the 32-bit version of Kerberos
for Windows can be used with the 32-bit OpenAFS Tools to manage AFS tokens.

OpenAFS on 64-bit Windows benefits from the lifting of the
2GB process memory restriction that is present in 32-bit Windows.
Without this restriction the AFS Cache File can become arbitrarily large
limited only by available disk space.

OpenAFS for Windows works with Microsoft Windows Vista
from both the command prompt and the Explorer Shell.When performing an upgrade from earlier
versions of Microsoft Windows the Microsoft Loopback Adapter (MSLA) will be
uninstalled.OpenAFS should be
re-installed after the Microsoft Vista installation to restore the MSLA configuration.

Due to a feature change in Windows Vista’s Plug-n-Play
network stack, during a standby/hibernate operation the MSLA is disabled just
as any other hardware device would be.This causes the OpenAFS Client’s network binding to be lost.As a result, it takes anywhere from 30 to 90
seconds after the operating system is resumed for access to the OpenAFS Client
and the AFS file space to become available.Until the network bindings have been re-established, ticket managers and
other tools will report that the AFS Client Service may not have been started.

Windows Vista implements User Account Control
(UAC), a new security feature that implements least user privilege.With UAC, applications only run with the
minimum required privileges.Even
Administrator accounts run applications without the “Administrator” access
control credentials.One side effect of
this is that existing applications that mix user and system configuration capabilities
must be re-written to separate those functions that require “Administrator”
privileges into a separate process space.Future updates to OpenAFS will incorporate the necessary privilege
separation, until that time some functions such as the Start and Stop Service
features of the AFS System Tray tool and the AFS Control Panel will not work
unless they are “Run as Administrator”.When a Vista user account that is a
member of the “Administrators” group is used to access the AFS Control Panel
(afs_config.exe), the process must be “Run as Administrator”.Otherwise, attempts to modify the OpenAFS
configuration will appear to succeed but in reality will have failed due to Vista’s system file and registry virtualization feature.

3.43. New AFS Share
Name Syntax Provides Direct Access to Volumes

Starting with the
1.5.21 release of OpenAFS for Windows, the following syntax can be used to
access any volume in any cell without requiring the creation of a mount point.

\\AFS\<cell><mount
point type><volume>\

Where
<cell> can be either a full cell name or an unambiguous prefix, the
<mount point type> is ‘#’ for a normal mount point or ‘%’ to force the
use of a read-write volume, and <volume> is either a volume name or its
ID number.

The OpenAFS for
Windows version of “fs examine” provide two additional lines of output when
compared to the UNIX implementation.These
lines include the owner and group information for the file as well as the
volume status.The Windows output will
also indicate the type of object {File, Directory, Mountpoint, Symlink, …} that
was examined.

Beginning with the 1.5.31 release, the fs
commands examine, flush, whereis, and whichcell
provide a new command-line parameter, -literal.When specified, if the evaluated object is a
symlink or a mountpoint the resulting output will describe the specified object
and not the object that is the target of the symlink or mountpoint.

Prior to the 1.5.31 release, out of quota
errors were reported to the calling application as an out of space error.As of 1.5.31, an out of space error will
indicate that the partition on which the volume is located is in fact out of
space.Whereas an out of quota error
indicates that the user does not have permission to allocate additional space.

4. How to Debug Problems with OpenAFS for
Windows

OpenAFS
for Windows provides a wide range of tools to assist you in debugging
problems. The techniques available to you are varied because of the wide
range of issues that have been discovered over the years.

pioctl
(path-based ioctl) calls are used by various tools to communicate with the AFS
Client Service. Some of the operations performed include:

·setting/querying
tokens (tokens.exe, aklog.exe, afscreds.exe)

·setting/querying
ACLs

·setting/querying
cache parameters

·flushing
files or volumes

·setting/querying
server preferences

·querying
path location

·checking
the status of servers and volumes

·setting/querying
the sysname list

pioctl
calls are implemented by writing to a special UNC path that is processed by the
AFS Client Service. If there is a failure to communicate with the
AFS Client Service via SMB/CIFS, it will be impossible to perform any of the
above operations.

To
assist in debugging these problems, the registry value:

[HKLM\SOFTWARE\OpenAFS\Client]

REG_DWORD: IoctlDebug = 0x01

should
be set. Then any of the commands that perform pioctl calls should be
executed from the command prompt. With this key set the pioctl library
will generate debugging output to stderr. The output will contain the
Win32 API calls executed along with their most important parameters and their
return code. The MSDN Library and the Microsoft KnowledgeBase can
be used as a reference to help you determine the configuration probem with your
system.

4.2. afsd_service initialization log (%WinDir%\TEMP\afsd_init.log)

Every
time the AFS Client Service starts it appends data about its progress and
configuration to a file. This file provides information crucial to
determining why the service cannot start when there are problems. When
the process terminates due to a panic condition it will write to this file the
source code file and line number of the error. In many cases the panic
condition is due to a misconfiguration of the machine. In other cases it
might be due to a programming error in the software. A quick review of
the location in the source code will quickly reveal the reason for the
termination.

The
MaxLogSize registry value
determines the maximum size of the %WINDIR%\TEMP\afsd_init.log file. If
the file is larger than this value when OpenAFS Client Service starts, the file
will be reset to 0 bytes. If value is set to 0, the file will be allowed
to grow indefinitely.

When
attempting to debug the behavior of the SMB/CIFS Server and the Cache Manager
it is often useful to examine a log of the operations being performed.
While running the AFS Client Service keeps an in memory log of many of its
actions. The default number of actions preserved at any one time is
5000. This can be adjusted with the registry value:

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

REG_DWORD TraceBufferSize

A
restart of the service is necessary when adjusting this value.
Execute "fs trace -on" to clear to the log and "fs trace
-dump" to output the contents of the log to the file.

An
alternatve option to the use of "fs trace -dump" to capture internal
OpenAFS Client Service events is to use a tool such as Sysinternal's Debug Viewer to
capture real-time debugging output. When the OpenAFS Client Service
starts and Bit 2 of the TraceOption value
in the registry is set, all trace log events are output using the Windows Debug
Monitor interface (OutputDebugString).

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

REG_DWORD
TraceOption = 0x04

Use
“fs trace –on” and “fs trace –off” to toggle the generation of log messages.

Sysinternal’s Process Monitor
can be use to monitor the file operations requested by applications and their
success or failure.

In
Process Monitor, set a filter to include only events on file paths that refer
to the AFS name space. Be sure to include both the UNC path as well as any
drive letters mapped to AFS.

Turn
on the Clock Time and Show Milliseconds options in both tools to
make it easier to synchronize the application requests and the resulting OpenAFS
Client Service operations. The captured data can be stored to files
for inclusion in bug reports.

Sysinternal's
Process Explorer is
a replacement for the Windows Task Manager and so much more. Process
Explorer can be configured to use the DbgHelp.dll from "Microsoft Debugging Tools for Windows"
as well as the debug symbols shipped as an optional component of the OpenAFS
for Windows installer. (Options->Configure Symbols) Once
configured the "Threads" tab of the process properties dialog will
permit the viewing of a fully documented stack for each displayed thread.
Hint: If there is a deadlock in the cache manager, two or more of the threads
will be stuck in a call to osi_TWait().

If
the AFS Client Service become unresponsive to any form of communication there
may be a serious error that can only be debugged by someone with access to the
source code and a debugger. The "fs minidump" command can
be used to force the generation of a MiniDump file containing the state of all
of the threads in the AFS Client Service process. The most accurate
MiniDump files will be produced after installing "Microsoft Debugging Tools for Windows".

The
MiniDumpType
registry value can be used to adjust the scope of the process information
included within the dump file. By default the MiniDump only contains the
stacks of all threads and the values of all global variables. A much more
useful MiniDump is one that contains the contents of the heap. Be warned,
a MiniDump with heap will be as large as the cache file. In addition, it
will include all of the data stored within the cache. If there are
privacy concerns, do not produce a MiniDump with heap.

4.6. Single Sign-on (Integrated Logon)
debugging

If
you are having trouble with the Integrated Logon operations it is often useful
to be able to obtain a log of what it is attempting to do. Setting
Bit 0 of the TraceOption registry value:

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

REG_DWORD TraceOption = 0x01

will
instruct the Integrated Logon Network Provider and Event Handlers to log
information to the Windows Event Log: Application under the name “AFS
Logon".

4.7. RX (AFS RPC) debugging (rxdebug)

The
rxdebug.exe tool can be used to query a variety of information about the AFS
services installed on a given machine. The port for the AFS Cache Manager
is 7001.

Usage:
rxdebug -servers <server machine> [-port <IP port>] [-nodally]

[-allconnections] [-rxstats] [-onlyserver] [-onlyclient]

[-onlyport <show only <port>>]

[-onlyhost <show only <host>>]

[-onlyauth <show only <auth level>>] [-version]

[-noconns] [-peers] [-help]

Where:
-nodally don't show dallying
conns

-allconnections don't filter out uninteresting connections

-rxstats show Rx statistics

-onlyserver only show server conns

-onlyclient only show client conns

-version show AFS version id

-noconns show no connections

-peers show peers

4.8. Cache Manager debugging (cmdebug)

The
cmdebug.exe tool can be used to query the state of the AFS Cache Manager on a
given machine.

4.9. Persistent Cache consistency check

The
persistent cache is stored in a Hidden System file at
%WinDir%\TEMP\AFSCache. If there is a problem with the persistent cache
that prevent the AFS Client Service from being able to start a validation check
on the file can be performed.

If
you are having trouble obtaining tokens with the Network Identity Manager AFS
credential provider, it is recommended that you verify your ability to obtain
tokens using the command-line tools klog.exe
(if you are using kaserver) or kinit.exe
and aklog.exe (if you are using
Kerberos v5.)The aklog.exe –d option will be quite helpful in diagnosing
Kerberos v5 related problems.

5. Reporting Bugs

Bug
reports should be sent to openafs-bugs@openafs.org.
Please include as much information as possible about the issue. If you
are reporting a crash, please install the debugging symbols by re-running the
installer. If a dump file is available for the problem,
%WINDIR%\TEMP\afsd.dmp, include it along with the AFS Client Trace file
%WINDIR%\TEMP\afsd.log. The AFS Client startup log is
%WINDIR%\TEMP\afsd_init.log. Send the last continuous block of log
information from this file.

Configuring
DrWatson to generate dump files for crashes:

·Run
drwtsn32.exe to configure or to identify where the log and the crash dump files
are created:

·click
Start > Run...

·type
drwtsn32 <enter>.

·Select
either a Crash Dump Type: Mini or Full.

·Clear
Dump Symbol Table

·Clear
Append to Existing Log file.

·Check
Dump All Thread Contexts.

·Check
Create Crash Dump File

·Next
run the monitoring module of Dr. Watson:

·click
Start > Run...

·type
drwatson <enter>.

·Once
a crash happens, Dr. Watson generates a dump file and a report in the log file,
including the address of the crash and the stack dump.

Once
you have the Dr. Watson's logfile and minidump, zip them and attach them to
your e-mail.

When
reporting a error, please be sure to include the version of OpenAFS.

6.
How to Contribute to the Development of OpenAFS for Windows

Contributions
to the development of OpenAFS for Windows are continuously needed.
Contributions may take many forms including cash donations, support contracts,
donated developer time, and even donated tech writer time.

6.1. The USENIX OpenAFS Fund

USENIX, a 501c3
non-profit corporation, has formed the USENIX OpenAFS Fund in order to accept
tax deductible donations on behalf of the OpenAFS Elders. The donated funds
will be allocated by the OpenAFS Elders to fund OpenAFS development,
documentation, project management, and maintaining openafs.org.

Donations
can be made by sending a check, drawn on a U.S. bank, made out to the USENIX
OpenAFS Fund or by making a donation online.

6.2.
Secure Endpoints Inc.

Secure Endpoints Inc. provides
development and support services for OpenAFS for Windows and MIT Kerberos for Windows.
Donations provided to Secure Endpoints Inc. for the development of
OpenAFS are used to cover the OpenAFS gatekeeper responsibilities; providing
support to the OpenAFS community via the OpenAFS mailing lists; and furthering
development of desired features that are either too small to be financed by
development contracts.

Secure
Endpoints Inc. accepts software development agreements from organizations who
wish to fund a well-defined set of bug fixes or new features.

Secure
Endpoints Inc. provides contract based support for the OpenAFS for Windows and
the MIT Kerberos for Windows products.

6.3. Direct contributions of code and/or
documentation

Organizations
that use OpenAFS in house and have development staffs are encouraged to
contribute any code modifications they make to OpenAFS.org via openafs-bugs@openafs.org. Contributions of
documentation are highly desired.

You
must join the mailing lists if you wish to post to the list without incurring a
moderation delay.

7.
MSI Deployment Guide

7.1. Introduction

A
MSI installer option is available for those who wish to use Windows Installer
for installing OpenAFS and for organizations that wish to deploy OpenAFS
through Group Policy. The first version of OpenAFS for Windows available
as an MSI was 1.3.65.

This
document provides a guide for authoring transforms used to customize the MSI
package for a particular organization. Although many settings can be
deployed via transforms, in an Active Directory environment it is advisable to
deploy registry settings and configuration files through
group policy and/or startup scripts so that machines where OpenAFS for Windows
is already installed will pick up these customizations.

7.1.1
Requirements

The
information in this document applies to MSI packages distributed with OpenAFS
for Windows releases from 1.3.65 and onwards or MSI packages built from
corresponding source releases. Not all releases support all the
configuration options documented here.

Authoring
a "Windows Installer" transform requires additional software for
editing the MSI database tables and generating the transform from the modified
MSI package. ORCA.EXE and MSITRAN.EXE which are included in the Windows
Platform SDK ("Windows Installer" SDK) can be used for this purpose.

For
reference, the schema for the MSI package is based on SCHEMA.MSI distributed
with the Platform SDK.

The
remainder of this document assumes some familiarity with authoring
transforms. While the MSDN documentation for Windows Installer is a bit
dense, the guide on MSI transforms found at the second link above is
recommended reading. MSDN also includes a step-by-step example for
creating a transform at:

7.1.2
Authoring a Transform

Transforms
describe a set of modifications to be performed on an existing MSI for the purpose
of customizing it. This is ordinarily done by making a copy of the MSI to
be customized, modifying the copy and then using the old and the new MSI to
generate a transform. For example:

1.copy
openafs.msi openafs-modified.msi

2.(edit
the openafs-modified.msi to include the necessary changes)

3.msitran
-g openafs.msi openafs-modified.msi openafs-transform.mst

4.(generates
openafs-transform.mst, which is the transform)

Transforms
have an extension of .mst. 'msitran' is a tool distributed as part of the
"Windows Installer" SDK (part of the Windows Platform SDK).

You
can test a transform by:

1.copy
openafs.msi openafs-test.msi

2.msitran
-a openafs-transform.mst openafs-test.msi

and
then checking the resulting openafs-test.msi to see if all changes you have
made above to openafs-modified.msi is present in openafs-test.msi.
'msitran' will complain if some modification in the transform can not be
successfully applied.

As
mentioned above, you can use a tool like ORCA.EXE to edit the MSI databases
directly when editing openafs-modified.msi. More details are given below.

7.2. Configuration Options

The
logic necessary to implement many of the settings described in Appendix A are present in the
MSI. Most of these can be controlled by setting the corresponding
properties to the desired value. Some settings may require modifying
existing registry entries (though not recommended) or adding new resources
(like files or registry keys). Instructions for performing these tasks
are below.

7.2.1
Configurable Properties

Most
configurable properties correspond to registry keys or values. Due to the
logic invoked based on the existence of these registry keys or values, they are
only set if the associated property is defined to have a non null value.
If the associated property is not defined in the MSI, the registry key or value
will not be touched. By default, the MSI does not contain these
properties and hence will not set the registry keys. You will need to add
properties as needed to the MSI.

When
one of the configurable properties is set, the installer will use the property
value to set the corresponding setting in the HKEY_LOCAL_MACHINE registry
hive. The HKEY_CURRENT_USER hive is not touched by the installer.

For
each property, the associated registry setting is referenced by the same text
used in Appendix A.

Strings
are quoted using single quotes (e.g. 'a string'). An empty string is denoted as
''. Note that you can't author null values into the 'Property' table.

Numeric
values should be authored as decimal strings.

7.2.1.1 Setting Properties

In
order to set a property,

1.Open the MSI in ORCA.EXE

2.Select the 'Property' table from the list of tables on the left.

3.Find the property in the list of properties on the right, double click
the value and type the new value.

4.If the property does not exist in the property list, right click the
list and select 'Add Row', type the property name and the desired value.

STOREANSIFILENAMES

USEDNS

7.2.1.2.2 AFSCreds.exe Properties

These
properties are combined to add a command line option to the shortcut that will
be created in the Start:Programs:OpenAFS and Start:Programs:Startup folders
(see CREDSSTARTUP). The method of specifying the option was chosen for
easy integration with the Windows Installer user interface. Although
other methods can be used to specify options to AFSCREDS.EXE, it is advised
that they be avoided as transforms including such options may not apply to
future releases of OpenAFS.

CREDSSTARTUP

Valid values : '1' or '0'

Controls whether AFSCreds.exe starts up automatically when
the user logs on. When CREDSSTARTUP is '1' a shortcut is added to the
'Startup' folder in the 'Program menu' which starts AFSCREDS.EXE with the
options that are determined by the other CREDS* properties.

CREDSAUTOINIT

Valid values : '-a' or ''

Enables automatic initialization.

CREDSIPCHDET

Valid values : '-n' or ''

Enables IP address change detection.

CREDSQUIET

Valid values : '-q' or ''

Enables quiet mode.

CREDSRENEWDRMAP

Valid values : '-m' or '’

Enables renewing drive map at startup.

CREDSSHOW

7.2.2
Existing Registry Entries

You
can change existing registry values subject to the restrictions mentioned in
the Windows Platform SDK. Pay special attention to component key paths
and try to only change the 'Value' column in the 'Registry' table. If you
want to add additional registry keys please refer to section 3 (Additional
resources).

7.2.3
Replacing Configuration Files

The
OpenAFS configuration files (CellServDB) can be replaced by your own
configuration files. These files are contained in separate MSI components
so that you can disable them individually.

The
recommended method for replacing these files is to first disable the components
containing the configuration files that you want to replace, and then add new
components for the replacement files. This is outlined below (assuming
you are using ORCA.EXE to author the transform).

Note
that transforms are not a good way to add a new file as an embedded
stream. The method outlined here places the file in the same directory as
the MSI for deployment.

The
walkthrough below is to add a custom 'CellServDB' file.

1.Disable the component that contains the configuration file that you want
to replace.

1.1.Locate
and select the 'Component' table in the 'Tables' list.

1.2.In
the Component table, locate the component you need to change ( Ctrl-F invokes
the 'Find' dialog). The component names are listed below in section 7.2.3.1. For this example,
the component name is 'elf_CellServDB'.

1.3.Go to
the 'Condition' column of the component.

1.4.Enter
a condition that evaluates to false. I.e. 'DONOTINSTALL'. (Note that an
undefined property always evaluates to false).

Note
that you can also use this step to disable other configuration files without
providing replacements.

2.Add a new component containing the new configuration file.

2.1.Select
the 'Component' table in the 'Tables' list.

2.2.Select
'Tables'->'Add Row' (Ctrl-R).

2.3.Enter
the following :

Component

cmf_my_CellServDB

ComponentID

{7019836F-BB2C-4AF6-9463-0D6EC9035CF1}

Directory_

dirClient

Attributes

144

Condition

KeyPath

fil_my_CellServDB

Note
that the ComponentId is an uppercase GUID. You can generate one using
GUIDGEN.EXE or UUIDGEN.EXE, both of which are included in the Platform SDK.

The
Attributes value of 144 is a sum of msidbComponentAttributesPermanent (16) and
msidbComponentAttributesNeverOverwrite (128). This ensures that local
modifications are not overwritten or lost during an installation or
uninstallation. These are the same settings used on the default
configuration files.

'fil_my_CellServDB' is a key into the 'File' table which we will fill later.

3.Add a new feature to hold the new component.

3.1.Select
the 'Feature' table.

3.2.Add a
new row (Ctrl-R or 'Tables'->'Add Row') with the following values:

Feature

fea_my_CellServDB

Feature_Parent

feaClient

Title

Description

Display

0

Level

30

Directory_

Attributes

8

It
is important to create the new feature under the 'feaClient' feature, which
will ensure that the configuration file will be installed when the client
binaries are installed.

Setting
'Display' to 0 will hide this feature from the feature selection dialog during
an interactive installation. A value of 30 for 'Level' allows this
feature to be installed by default (on a 'Typical' installation).

The
'Attributes' value is msidbFeatureAttributesDisallowAdvertise (8), which is set
on all features in the OpenAFS MSI. The OpenAFS MSI is not designed for
an advertised installation.

4.Join the component and the feature.

4.1.Select
the 'FeatureComponents' table.

4.2.Add a
new row with the following values:

Feature

fea_my_CellServDB

Component

cmf_my_CellServDB

5.Add an entry to the 'File' table.

5.1.Select
the 'File' table.

5.2.Add a
new row with the following values:

File

fil_my_CellServDB

Component_

cmf_my_CellServDB

FileName

CellServDB

FileSize

(enter file size here)

Attributes

8192

Sequence

1000

(leave other fields blank)

The
'Attributes' value is msidbFileAttributesNonCompressed (8192). This is
because we will be placing this file in the same directory as the MSI instead
of embedding the file in it. Transforms do not support updating compressed
sources or adding new cabinet streams.

Finally,
the 'Sequence' value of 1000 will be used later to distinguish the file as
being in a separate source location than the other files in the MSI.

6.Set a media source for the file.

6.1.Select
the 'Media' table.

6.2.Add a
row with the following values :

DiskId

2

LastSequence

1000

(leave other fields blank)

The
sequence number of 1000 designates this as the media source for the newly added
file.

The
example adds a read-only mountpoint to the athena.mit.edu cell's root.afs
volume as well as a read-write mountpoint. Aliases are also provided
using symlinks.

7.3 Additional Resources

If
you want to add registry keys or files you need to create new components and
features for those. Refer to the Windows Platform SDK for details.

It
is beyond the scope of this document to provide a comprehensive overview of how
to add new resources through a transform. Please refer to the
"Windows Installer" documentation for details. The relevant
section is at :

A
sample walkthrough of adding a new configuration file is in section 2.3.

Add
new features under the 'feaClient' or 'feaServer' as appropriate and set the
'Level' column for those features to equal the 'Level' for their parent
features for consistency. Note that none of the features in the OpenAFS
for Windows MSI package are designed to be installed to run from 'source' or
'advertised'. It is recommended that you set
'msidbFeatureAttributesFavorLocal' (0), 'msidbFeatureAttributesFollowParent'
(2) and 'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
features.

If
you are creating new components, retain the same component GUID when creating
new transforms against new releases of the OpenAFS MSI package.

After
making the adjustments to the MSI database using ORCA.EXE you can generate a
transform with MSITRAN.EXE as follows :

(Modified
MSI package is 'openafs-en_US_new.msi' and the original MSI package is
'openafs-en_US.msi'. Generates transform 'openafs-transform.mst')

See
the Platform SDK documentation for information on command line options for
MSITRAN.EXE.

7.4. Upgrades

The
MSI package is designed to uninstall previous versions of OpenAFS for Windows
during installation. Note that it doesn't directly upgrade an existing
installation. This is intentional and ensures that development releases
which do not have strictly increasing version numbers are properly upgraded.

Versions
of OpenAFS that are upgraded by the MSI package are:

1)OpenAFS MSI package
Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}
Up to current release

Note
that versions of the OpenAFS NSIS package prior to 1.3.65 had a bug where it
couldn't be uninstalled properly in unattended mode. Therefore the MSI
package will not try to uninstall an OpenAFS NSIS package if running
unattended. This means that group policy based deployments will fail on
machines that have the OpenAFS NSIS package installed.

If
you have used a different MSI package to install OpenAFS and wish to upgrade it
you can author rows into the 'Upgrade' table as described in the Platform SDK.

When
performing an upgrade with msiexec.exe execute the MSI with the repair options
"vomus".

Appendix
A: Registry Values

A.1. Service parameters

The
service parameters primarily affect the behavior of the AFS client service
(afsd_service.exe).

Value: LANadapter

Type: DWORD
Default: -1
Variable: LANadapter

LAN adapter number to use. This is the lana number
of the LAN adapter that the SMB server should bind to. If unspecified or
set to -1, a LAN adapter with named 'AFS' or a loopback adapter will be
selected. If neither are present, then all available adapters will be
bound to. When binding to a non-loopback adapter, the NetBIOS name
hostname%-AFS' will be used (where %hostname% is the NetBIOS name of the host
truncated to 11 characters). Otherwise, the NetBIOS name will be 'AFS'.

Cache
configuration.

Value: Cells

Cache configuration.

Value:
LogoffPreserveTokens

If enabled (set to 1), the Logoff Event handler will not
attempt to delete the user's tokens if the user's profile is stored
outside of AFS.

Value: RootVolume

Type: REG_SZ
Default: "root.afs"
Variable: cm_rootVolumeName

Root volume name.

Value: MountRoot

Type: REG_SZ
Default: "/afs"
Variable: cm_mountRoot

Name of root mount point. In symlinks, if a path
starts with cm_mountRoot, it is assumed that the path is absolute (as opposed
to relative) and is adjusted accordingly. Eg: if a path is specified as
/afs/athena.mit.edu/foo/bar/baz and cm_mountRoot is "/afs", then
the path is interpreted as \\afs\all\athena.mit.edu\foo\bar\baz. If a
path does not start with with cm_mountRoot, the path is assumed to be
relative and suffixed to the reference directory (i.e. directory where the
symlink exists)

Value: CachePath

Location of on-disk cache file. The default is the
SYSTEM account's TEMP directory. The attributes assigned to the file
are HIDDEN and SYSTEM.

Value: NonPersistentCaching

Type: DWORD [0..1]
Default: 0
Variable: buf_CacheType

When this registry value is set to a non-zero value, the
CachePath value is ignored and the cache data is stored in the windows paging
file. This disables the use of persistent caching and the ability to
maintain a single UUID for the AFS client service across restarts.

Value: ValidateCache

Type: DWORD [0..2]
Default: 1
Variable: buf_CacheType

This value determines if and when persistent cache
validation is performed.

0 - Validation is disabled
1 - Validation is performed at startup
2 - Validation is performed at shutdown

Value: TrapOnPanic

Type: DWORD {1,0}
Default: 0
Variable: traceOnPanic

Issues a breakpoint in the event of a panic.
(breakpoint: _asm int 3).

Value: NetbiosName

Type: REG_EXPAND_SZ
Default: "AFS"
Variable: cm_NetbiosName

Specifies the NetBIOS name to be used when binding to a
Loopback adapter. To provide the old behavior specify a value of
"%COMPUTERNAME%-AFS".

Value: IsGateway

Type: DWORD {1,0}
Default: 0
Variable: isGateway

Select whether or not this AFS client should act as a
gateway. If set and the NetBIOS name hostname-AFS is bound to a
physical NIC, other machines in the subnet can access AFS via SMB connections
to hostname-AFS.

When IsGateway is non-zero, the LAN adapter detection
code will avoid binding to a loopback adapter. This will ensure that
the NetBIOS name will be of the form hostname-AFS instead of the value set by
the "NetbiosName" registry value.

Value: ReportSessionStartups

Type: DWORD {1,0}
Default: 0
Variable: reportSessionStartups

If enabled, all SMB sessions created are recorded in the
Application event log. This also enables other events such as drive
mappings or various error types to be logged.

Value: MaxLogSize

Type: DWORD {0 .. MAXDWORD}
Default: 100K

This entry determines the maximum size of the
%WINDIR%\TEMP\afsd_init.log file. If the file is larger than this value
when afsd_service.exe starts the file will be reset to 0 bytes. If this
value is 0, it means the file should be allowed to grow indefinitely.

Value: FlushOnHibernate

Type: DWORD {0,1}
Default: 1

If set, flushes all volumes before the machine goes on
hibernate or stand-by.

This value controls how frequently the AFS cache manager
checks offline volumes to see if they have come back online.At the same time volumes which were
determined to be busy have their state reset to online.

This value specifies which port number should be used
for receiving callbacks from the file server.The standard AFS Callback port is 7001.Alternative values can be useful if the
client is behind a NAT and a permanent port mapping for the client is being
configured.

The AFS Cache Manager will pre-fetch the entire contents
of any file whose name matches ends with one of the specified
extensions.This option is intended
for use primarily with executables and dynamic link libraries that should be
fully cached prior to a machine losing its connection with the file server.

Determines whether or not cached data from .readonly
volumes is considered valid even if a callback cannot be registered with a
file server.This option is meant to
be used by organizations for whom .readonly volume content very rarely
changes (if ever.)

Determines whether or not the AFS Cache Manager will give
up all callbacks prior to the service being suspended or shutdown.Doing so will have significant performance
benefits for the file servers.However, file servers older than 1.4.6 can become unstable if the
GiveUpAllCallBacks RPC is executed.

Value: <Drive Letter:> for example
"G:"

Specifies the submount name to be mapped by
afsd_service.exe at startup to the provided drive letter.

This option is deprecated.

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client]

Value: CellServDBDir

Type: REG_SZ
Default: <not defined>

Specifies the directory containing the CellServDB
file. When this value is not specified, the ProgramData directory is searched
and if the CellServDB file is not found, the AFS Client install directory is
used.

Value:
VerifyServiceSignature

Type: REG_DWORD
Default: 0x1

This value can be used to disable the runtime
verification of the digital signatures applied to afsd_service.exe and the
OpenAFS DLLs it loads. This test is performed to verify
that the DLLs which are loaded by afsd_service.exe are from the
same distribution as afsd_service.exe. This is to prevent random errors
caused when DLLs from one distribution of AFS are loaded by another
one. This is not a security test. The reason for disabling this
test is to free up additional memory which can be used for a large cache
size.

Value: IoctlDebug

Type: REG_DWORD
Default: 0x0

This value can be used to debug the cause of pioctl()
failures. Set a non-zero value and the pioctl() library will output
status information to stdout. Executing command line tools such as
tokens.exe, fs.exe, etc can then be used to determine why the pioctl() call
is failing.

Value: MiniDumpType

Type: REG_DWORD
Default: 0x0 (MiniDumpNormal)

This value is used to specify the type of minidump
generated by afsd_service.exe either when the process crashes or when a user
initiated is dump file is generated with the "fs.exe minidump"
command.

Valid values are dependent on the version of DbgHelp.dll
installed on the machine. The best version to use is not the version
that comes with the operating system but the version that is included in the
most recent release of "Microsoft Debugging
Tools for Windows". See the Microsoft Developer
Library for further information.

Value:
EnableSMBAsyncStore

Type: REG_DWORD
Default: 0x1

This value can be used to disable the use of SMB
Asynchronous Store operations.

Value: SMBAsyncStoreSize

Type: REG_DWORD
Default: 32

This value determines the size of SMB Asynchronous Store
operations. This value can be used to increase the write performance on
higher speed networks by increasing the value.The value must be a multiple of the cache
buffer block size and cannot be larger than the cache manager chunk size.The specified value will be adjusted to enforce
its compliance with these restrictions.

This value can be used to force the AFS Client Service
to store filenames using the Windows system's ANSI character set instead of the
OEM Code Page character set which has traditionally been used by SMB file
systems.

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client\CSCPolicy]

Value: "smb/cifs share name"

This key is used to map SMB/CIFS shares to Client Side
Caching (off-line access) policies. For each share one of the following
policies may be used: "manual", "programs",
"documents", "disable".

These values used to be stored in afsdsbmt.ini

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client\Freelance]

Value: "numeric value"

Type: REG_SZ
Default: <none>

This key is used to store dot terminated mount point
strings for use in constructing the fake root.afs volume when Freelance
(dynamic roots) mode is activated.

"athena.mit.edu#athena.mit.edu:root.cell."

".athena.mit.edu%athena.mit.edu:root.cell."

These values used to be stored in afs_freelance.ini

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks]

Value: "numeric value"

Type: REG_SZ
Default: <none>

This key is used to store a dot terminated symlink
strings for use in constructing the fake root.afs volume when Freelance
(dynamic roots) mode is activated.

"linkname:destination-path."

"athena:athena.mit.edu."

"home:athena.mit.edu\user\j\a\jaltman."

"filename:path\file."

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client\Realms]

The
Realms key is used to provide initialization data to be used when new
identities are added to the Network Identity Manager.The AFS Provider will search for a subkey that
matches the realm of the identity.If
such a key exists, its values will be used to populate the AFS configuration
for the identity.

In
addition to the optional values, this key contains one subkey for each cell
that is to be added to the AFS Provider configuration.

Value: AFSEnabled

Type: REG_DWORD
Default: 0x01

This key is used to specify whether the new identity
should be configured to obtain AFS credentials.In general, it is only specified when
disabling the acquisition of AFS credentials is desired.The default is to obtain AFS credentials.

This key is
used to specify the token acquisition method to be used.When unspecified, the AFS provider will
automatically try Kerberos v5 and then Kerberos v5 (if available).As of this writing valid method names
include “Auto”, “Kerberos5”, “Kerberos524”, “Kerberos4”.

Note:
Kerberos524 and Kerberos4 cannot be used with 64-bit Kerberos for Windows.

This key is
used to specify the realm to be used when acquiring AFS tokens.If not specified, the realm will be
determined by performing a domain to realm mapping on the domain of a random
volume location database server for the cell.

This key is
used to store mappings of UNIX style AFS paths to submount names which can be
referenced as UNC paths. For example the submount string
“/athena.mit.edu/user/j/a/jaltman" can be associated with the submount
name "jaltman.home". This can then be referenced as the UNC
path \\AFS\jaltman.home.

These values
used to be stored in afsdsbmt.ini

NOTE: Submounts
should no longer be used with OpenAFS. Use the Windows Explorer to create
drive mappings to AFS UNC paths instead of using the AFS Submount mechanism.

Value: "hostname or ip address"

Type: REG_DWORD
Default: <none>

This key is used to specify a default set of VLDB server
preferences. For each entry the value name will be either the IP address of a
server or a fully qualified domain name. The value will be the
ranking. The ranking will be adjusted by a random value between 0 and
256 prior to the preference being set.

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client\Server Preferences\File]

Value: "hostname or ip address"

Type: REG_DWORD
Default: <none>

This key is used to specify a default set of File server
preferences. For each entry the value name will be either the IP address of a
server or a fully qualified domain name. The value will be the ranking.
The ranking will be adjusted by a random value between 0 and 256 prior to the
preference being set.

Value: AuthentProviderPath

Value: Class

Type: DWORD
NSIS: 0x02

Specifies the class of network provider

Value: DependOnGroup

Type: REG_MULTI_SZ
NSIS: PNP_TDI

Specifies the service groups upon which the AFS Client
Service depends. Windows should not attempt to start the AFS Client Service
until all of the services within these groups have successfully started.

Value: DependOnService

Type: REG_MULTI_SZ
NSIS: Tcpip NETBIOS RpcSs

Specifies a list of services upon which the AFS Client
Service depends. Windows should not attempt to start the AFS Client
Service until all of the specified services have successfully started.

Value: Name

Type: REG_SZ
NSIS: "OpenAFSDaemon"

Specifies the display name of the AFS Client Service

Value: ProviderPath

Type: REG_SZ
NSIS: %WINDIR%\SYSTEM32\afslogon.dll

Specifies the DLL to use for the network provider

A.2.1 Domain specific configuration keys for
the Network Provider

The
network provider can be configured to have different behavior depending on the
domain that the user logs into. These settings are only relevant when
using integrated login. A domain refers to an Active Directory (AD)
domain, a trusted Kerberos (non-AD) realm or the local machine (i.e. local
account logins). The domain name that is used for selecting the domain would
be the domain that is passed into the NPLogonNotify function of the network
provider.

Value: LogonScript

A logon script that will be scheduled to be run after
the profile load is complete. If using the REG_EXPAND_SZ type, you can
use any system environment variable as "%varname%" which would be
expanded at the time the network provider is run. Optionally using a
"%s" in the value would result in it being expanded into the AFS
SMB username for the session.

Value: LoginRetryInterval

Type: DWORD
Default: 30
NSIS/WiX: (not set)

If the OpenAFS client service has not started yet, the
network provider will wait for a maximum of "LoginRetryInterval"
seconds while retrying every "LoginSleepInterval" seconds to check
if the service is up.

Value: LoginSleepInterval

Type: DWORD
Default: 5
NSIS/WiX: (not set)

See description of LoginRetryInterval.

Value: Realm

Type: REG_SZ
NSIS: <not set>

When Kerberos v5 is being used, Realm specifies the
Kerberos v5 realm that should be appended to the first component of the
Domain logon username to construct the Kerberos v5 principal for which AFS
tokens should be obtained.

Value: TheseCells

Type: REG_MULTI_SZ
NSIS: <not set>

When Kerberos v5 is being used, TheseCells provides a
list of additional cells for which tokens should be obtained with the default
Kerberos v5 principal.

During
login to domain X, where X is the domain passed into NPLogonNotify as
lpAuthentInfo->LogonDomainName or the string 'LOCALHOST' if
lpAuthentInfo->LogonDomainName equals the name of the computer, the
following keys will be looked up.

If
the specific domain key does not exist, then the domains key will be
ignored. All the configuration information in this case will come from
the NP key.

If
the specific domain key exists, then for each of the values metioned in (2),
they will be looked up in the specific domain key, domains key and the NP key
successively until the value is found. The first instance of the value found
this way will be the effective for the login session. If no such instance
can be found, the default will be used. To re-iterate, a value in a more
specific key supercedes a value in a less specific key. The exceptions to
this rule are stated below.

A.2.1.3
Exceptions to A.2.1.2

To
retain backwards compatibility, the following exceptions are made to 2.1.2.

2.1.3.1 'FailLoginsSilently'

Historically,
the 'FailLoginsSilently' value was in
HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters key and not
in the NP key. Therefore, for backwards compatibility, the value in the
Parameters key will supercede all instances of this value in other keys.
In the absence of this value in the Parameters key, normal scope rules apply.

2.1.3.2 'LogonScript'

If
a 'LogonScript' is not specified in the specific domain key nor in the domains
key, the value in the NP key will only be checked if the effective
'LogonOptions' specify a high security integrated login. If a logon
script is specified in the specific domain key or the domains key, it will be
used regardless of the high security setting. Please be aware of this when
setting this value.

Regkey:
[HKLM\SOFTWARE\OpenAFS\Client]
[HKCU\SOFTWARE\OpenAFS\Client]

Value: ShowTrayIcon

This value is used to determine whether or not a
shortcut should be maintained in the user's Start
Menu->Programs->Startup folder.

This value used to be stored at
[HKLM\Software\TransarcCorporation\AFS Client\AfsCreds].

The current user value is checked first; if it does not
exist the local machine value is checked.

Value: EnableKFW

Type: DWORD {0, 1}
Default: 1
Function: KFW_is_available()

When MIT Kerberos for Windows can be loaded, Kerberos v5
will be used to obtain AFS credentials. By setting this value to 0, the
internal Kerberos v4 implementation will be used instead. The current
user value is checked first; if it does not exist the local machine value is
checked.

Kerberos v5 principal names are traditionally mapped to
Kerberos v4 names by the AFS servers before they can be looked up in the
Protection database. The mapping algorithm used permits collisions to
occur. Both of the Kerberos v5 names, "user.admin@REALM" and "user/admin@REALM" are
interpreted as the same user identity within the cell. To enable both
names to be sent to the server by AFSCreds or Integrated Logon, set this
value to 1.

Value:
Use524

Type: DWORD {0, 1}
Default: 0
Function: KFW_use_krb524()

When MIT Kerberos for Windows can be loaded, Kerberos v5
will be used to obtain AFS credentials. By setting this value to 1, the
Kerberos v5 tickets will be converted to Kerberos v4 tokens via a call to the
krb524 daemon. The current user value is checked first; if it does not
exist the local machine value is checked.

Value:
AfscredsShortcutParams

Type: REG_SZ
Default: "-A -M -N -Q"
Function: Shortcut_FixStartup

This value specifies the command line options which
should be set as part of the shortcut to afscreds.exe. afscreds.exe
rewrites the shortcut each time it exits so as to ensure that the shortcut
points to the latest version of the program. This value is used to
determine which values should be used for command line parameters. The
current user value is checked first; if it does not exist the local machine
value is checked.

The following subset of the command line options is
appropriate for use in this registry setting: