From: Jeffrey Altman Date: Mon, 26 Sep 2005 03:01:23 +0000 (+0000) Subject: STABLE14-windows-release-notes-20050925 X-Git-Tag: openafs-stable-1_4_0-rc5~11 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=178608a372c8fc0b5040ac9d1e9b36684458638e;p=packages%2Fo%2Fopenafs.git STABLE14-windows-release-notes-20050925 Add new OAFW Release Notes developed in WinWord 2003. Replaces the afs-install-notes.txt, msi-deployment.txt and registry.txt files. ==================== This delta was composed from multiple commits as part of the CVS->Git migration. The checkin message with each commit was inconsistent. The following are the additional commit messages. ==================== Add new release notes to stable tree (cherry picked from commit 2c599161dbb255edee27c4fc176a8011408f2b47) --- diff --git a/src/WINNT/doc/install/Documentation/en_US/README.txt b/src/WINNT/doc/install/Documentation/en_US/README.txt index dad01b9b1..47052eab3 100755 --- a/src/WINNT/doc/install/Documentation/en_US/README.txt +++ b/src/WINNT/doc/install/Documentation/en_US/README.txt @@ -8,55 +8,14 @@ directory or online at http://www.openafs.org/dl/license10.html All Rights Reserved *************************************************************** -IBM AFS for Windows, version 3.6 +OpenAFS for Windows, version 1.4.0 *************************************************************** -The README.txt file includes AFS for Windows product notes, which -can possibly identify specific limitations and restrictions -associated with this release of AFS for Windows. +OpenAFS for Windows Supplemental Documentation +The Supplemental Documentation component of OpenAFS for Windows is only available +online if the Supplemental Documentation option was chosen when OpenAFS for Windows +was installed on your system. -AFS Partitions No Longer Need to Reside On Empty NTFS Volumes - -On Windows NT machines, any NTFS volume can be designated as an AFS -partition. Previously, an NTFS volume containing any data other than -the Windows Recycler could not be designated as an AFS partition. - - - -Encryption Not Supported in Simplified Chinese Version of Windows 98 - -The Simplified Chinese version of Microsoft Windows 98 does not support -encryption, which is needed to transmit AFS passwords from AFS Light to -the AFS Light Gateway. In order for AFS Light users to obtain AFS tokens -when using the Simplified Chinese version of Microsoft Windows 98, -encryption in AFS must be disabled. -To disable encryption in AFS, add the following line to your Windows -autoexec.bat file: -set AFS_RPC_ENCRYPT=OFF -Note that disabling encryption introduces a potential security risk -because AFS passwords are transmitted to the AFS Light Gateway in an -unencrypted form when tokens are obtained. - - - -Windows NT with Service Pack 6 Is Now Supported - -The Client, Server, and Control Center components of AFS for Windows can -be installed on Microsoft Windows NT 4.0 with Service Pack 4, Service Pack 5, -or Service Pack 6. - - - -AFS for Windows Supplemental Documentation - -The Supplemental Documentation component of AFS for Windows is only available -online if the AFS Supplemental Documentation option was chosen when AFS for Windows -was installed on your system. (AFS Supplemental Documentation is not an option when -installing AFS Light.) Note that documentation is also available directly -from the AFS for Windows CD-ROM, in the CD:\Documentation directory, where CD -is the letter of your CD-ROM drive. - - -Refer to the AFS for Windows Release Notes for additional product information. +Refer to the OpenAFS for Windows Release Notes for additional product information. diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/frames.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/frames.htm new file mode 100644 index 000000000..0569689ce --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/frames.htm @@ -0,0 +1,130 @@ + + + + + + + + +OpenAFS for Windows 1.4.0 Release Notes + + + + + + + + + + + + + <body lang=EN-US style='tab-interval:36.0pt'> + <div class=Section1> + <p class=MsoNormal>This page uses frames, but your browser doesn't support + them.</p> + </div> + </body> + + + + diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo.htm new file mode 100644 index 000000000..5a79e0523 --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo.htm @@ -0,0 +1,164 @@ + + + + + + + + + + +OpenAFS for Windows Logo + + + + + + + +
+ +

+ +
+ + + + diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/filelist.xml b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/filelist.xml new file mode 100644 index 000000000..da16014a1 --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/filelist.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/image001.jpg b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/image001.jpg new file mode 100644 index 000000000..19d79943d Binary files /dev/null and b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/image001.jpg differ diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/image002.jpg b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/image002.jpg new file mode 100644 index 000000000..cd8ead730 Binary files /dev/null and b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/logo_files/image002.jpg differ diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm new file mode 100644 index 000000000..1b5128fdf --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes.htm @@ -0,0 +1,8312 @@ + + + + + + + + + +OpenAFS for Windows 1.4.0 Release Notes + + + + + + + + + + + + + + + + + +
+ +

OpenAFS for Windows 1.4.0
+Release Notes

+ +

The Andrew File System (AFS) is a location-independent +file system that uses a local cache to increase its performance.  An AFS client accesses files anonymously or +via a Kerberos authentication.  The +global AFS is partitioned into cells.  +The AFS cell is a collection of AFS volumes that are administered by a +common entity.   AFS cells can be +administered by a department even when the Kerberos realm used for local +authentication is managed by a much larger organization.  AFS clients and servers take advantage of +Kerberos cross realm authentication to enable authenticated access by entities +located outside the local realm.  +Authorization is enforced by the use of directory level access control +lists which can consist of individual or group identities. 

+ +

The AFS volume is a tree of files and +sub-directories.  AFS volumes are created +by administrators and are joined to an AFS cell via the use of a mount +point.   Once a volume is created, users +can create files and directories as well as mount points and symlinks within +the volume without regard for the physical location of the volume.  Administrators can move the volume to another +server as necessary without the need to notify users.   In fact, the volume move can occur while +files in the volume are in use. 

+ +

AFS volumes can be replicated to read-only copies.   When accessing files from a read-only replica, +clients will read all of the data from a single replica.   If that replica becomes unavailable, the +clients will failover to any replica that is reachable.  Users of the data are unaware of where the +replicas are stored or which one is being accessed.   The contents of the replicas can be updated +at any time by releasing the current +contents of the source volume.

+ +

OpenAFS for Windows (OAFW) provides AFS client access +Microsoft Windows operating systems.  It +strives to maintain transparency such that the user is unaware of the +distinction between the use of AFS and Microsoft Windows file shares.   OAFW can be part of a single sign-on +solution by allowing credentials for a Kerberos principal to be obtained at +logon and for that principal to be used to obtain AFS tokens for one or more +cells.   Although OAFW is implemented as +a locally installed SMB to AFS gateway, OAFW maintains the portability of file +paths by its use of the \\AFS UNC server name.

+ +

OpenAFS is the product of an open source development +effort begun in July 2001.  OpenAFS is +maintained and developed by a group of volunteers with the support of the user +community.   If you use OpenAFS as part +of your computing infrastructure please contribute to its continued growth.

+ +

1. +Installer Options. 1

+ +

2. +System Requirements. 2

+ +

3. +Operational Notes. 2

+ +

4. +How to Debug Problems with OpenAFS for Windows: 11

+ +

5. +Reporting Bugs: 13

+ +

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

+ +

7. +MSI Deployment Guide. 15

+ +

Appendix +A: Registry Values. 26

+ +

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 2003 Server

+ +

·       Microsoft +Windows 2003 R2 Server

+ +

2.1.1 Unsupported +Operating Systems

+ +

·       Microsoft +Windows 95

+ +

·       Microsoft +Windows 98

+ +

·       Microsoft +Windows 98 OSR2

+ +

·       Microsoft +Windows ME

+ +

·       Microsoft +NT

+ +

·       Microsoft +Windows Vista (as of Beta 1 bugs in Windows prevent its use)

+ +

·       All +64-bit versions of Microsoft Windows on Itanium and x86-64 chipsets.

+ +

Older releases of OpenAFS are available for download if +those operating systems must be supported.  +The last version of OpenAFS with support for Win9x is 1.2.2b.  The last version with support for Windows NT +4.0 is 1.2.10.

+ +

2.2 Disk Space

+ +

Up to 60mb required for the OpenAFS binaries plus 100MB for +the default AFSCache file.   (The size of +the AFSCache file may be adjusted via the Registry after installation.)

+ +

2.3 Additional +Software

+ +

MIT +Kerberos for Windows 2.6.x if Kerberos 5 authentication support is desired.

+ +

3. Operational Notes

+ +

3.1. Requirements +for Kerberos 5 Authentication

+ +

The Kerberos 4 infrastructure on which the OpenAFS 1.2 +series is reliant is no longer secure.  +Cross-realm Kerberos is very important in the AFS context and most sites +have or are migrating to Kerberos 5 environments.  The OpenAFS 1.4 series integrates with MIT +Kerberos for Windows 2.6.5 to support Kerberos 5 authentication including +automatic renewal of AFS tokens and single sign-on via the Microsoft Windows +Kerberos Logon Service.

+ +

When KFW is installed, the OpenAFS 1.4 client will obtain +Kerberos 5 tickets and use them as tokens without modification.  The OpenAFS 1.4 client requires that all of +the AFS Servers with which it communicates support the use of Kerberos 5 +tickets as tokens. If Kerberos 5 based tokens are presented to an AFS server +that does not understand them, the server will be unable to communicate with +the client when tokens are present. Kerberos 5 based tokens are supported by +OpenAFS release 1.2.8 or later.  IBM +Transarc servers do not support Kerberos 5.

+ +

3.1.1. Active +Directory

+ +

There are two things to consider when using a Microsoft +Windows Active Directory as the Kerberos realm that issues the AFS service +ticket.  First, the Kerberos 5 tickets +issued by Active Directory can be quite large when compared to tickets issued +by a traditional KDC due to the incorporation of authorization data in the PAC.  If the issued +tickets become larger than 344 bytes OpenAFS 1.2 servers will be unable to +process them.  OpenAFS 1.4 servers can +support the largest tickets that Active Directory can issue.  Second, the Kerberos 5 tickets issued by +Windows 2003 Active Directory are encrypted with the DES-CBC-MD5 enctype.  OpenAFS 1.2 servers only support the +DES-CBC-CRC enctype.

+ +

3.1.2. Using +the krb524 service

+ +

Some organizations which have AFS cell names and Kerberos +realm names which differ by more then just lower and upper case rely on a +modification to krb524d which maps a Kerberos 5 ticket from realm FOO to a +Kerberos 4 ticket in realm BAR.  This +allows user@FOO to appear to be user@bar for the purposes of accessing the AFS +cell.  As of OpenAFS 1.2.8, support was +added to allow the immediate use of Kerberos 5 tickets as AFS (2b) tokens. This +is the first building block necessary to break away from the limitations of +Kerberos 4 with AFS.  By using Kerberos 5 +directly we avoid the security holes inherent in Kerberos 4 cross-realm.  We also gain access to cryptographically +stronger algorithms for authentication and encryption.

+ +

Another reason for using Kerberos 5 directly is because the +krb524 service runs on a port (4444) which has become increasingly blocked by +ISPs.  The port was used to spread a worm +which attacked Microsoft Windows in the summer of 2003.  When the port is blocked users find that they +are unable to authenticate.

+ +

Replacing the Kerberos 4 ticket with a Kerberos 5 ticket is +a win in all situations except when the cell name does not match the realm name +and the principal names placed into the ACL’s are not the principal names from +the Kerberos 5 ticket.  To support this +transition, OpenAFS for Windows 1.4 adds a new registry value, Use524, +to force the use of krb524d.  However, +the availability of this option should only be used by individuals until such +time as their organizations can provide a more permanent solution.

+ +

3.2. Use of the +Microsoft Loopback Adapter

+ +

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, a fake "root.afs" volume is dynamically constructed +from mount points and symlinks stored in the local registry.  This method of operation is referred to as +Freelance mode.

+ +

The content of the fake “root.afs” volume is dynamically +modified as cells are accessed.  When the +fake "root.afs" volume is initially constructed it will only contain +two mount points: a regular path and read-write path mount point +used to access the "root.cell" volume of the default AFS cell.  Any attempt to access a valid cell name will +result in a new mount point being created in the fake "root.afs" +volume.  If the cellname begins with a +"." the mount point will be a read-write path; otherwise the +mount point will be a regular path.  +These mount points are preserved in the registry at key:

+ +

HKLM\SOFTWARE\OpenAFS\Client\Freelance

+ +

Additional mount points may be manually created using the +"fs mkmount" command.  Mount +points may be removed using the "fs rmmount" command.

+ +

>fs mkmount +\\AFS\athena.mit.edu root.cell athena.mit.edu

+ +

>fs mkmount +\\AFS\.athena.mit.edu root.cell athena.mit.edu -rw

+ +

>fs rmmount +\\AFS\athena.mit.edu

+ +

>fs rmmount +\\AFS\.athena.mit.edu

+ +

Symlinks may also be created within the Freelance “root.afs” +volume.

+ +

>symlink make \\afs\link +\\afs\athena.mit.edu\user\j\a\jaltman

+ +

      >symlink +list \\afs\link

+ +

      '\\afs\link' +is a symlink to 'athena.mit.edu\user\j\a\jaltman'

+ +

>symlink rm \\afs\link

+ +

The symlinks are stored in the registry at:

+ +

HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks 

+ +

3.4. Locating AFS +Volume Database Servers

+ +

The OpenAFS for Windows client will use DNS AFSDB records to +discover the location of AFS Volume Database servers when entries are not present +in the client's CellServDB file (\%PROGRAMFILES%\OpenAFS\Client\CellServDB).

+ +

3.5. Obtaining +AFS Tokens as a 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.  The Kerberos 5 tickets +obtained during the process of generating AFS tokens are preserved and stored +into the default ccache within the user logon session.

+ +

Integrated Logon does not have the ability to cache the +user's username and password for the purpose of obtaining tokens if the +Kerberos KDC is inaccessible at logon time.

+ +

Integrated Login supports the ability to obtain tokens for +multiple cells.  For further information +on how to configure this feature read the TheseCells value in Appendix +A.

+ +

3.6. AFS System +Tray Command Line Options

+ +

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 1.4 client supports a local Windows +authorization group named "AFS Client Admins".  This group is used in place of the +"Administrators" group to determine which users are allowed to modify +the AFS Client Service configuration via the AFS Control Panel (afs_config.exe) +or fs.exe command line tool.  The +following fs.exe commands are now restricted to members of the "AFS Client +Admins" group:

+ +

·       checkservers +with a non-zero timer value

+ +

·       setcachesize

+ +

·       newcell

+ +

·       sysname +with a new sysname list

+ +

·       exportafs

+ +

·       setcell

+ +

·       setserverprefs

+ +

·       storebehind

+ +

·       setcrypt

+ +

·       cscpolicy

+ +

·       trace

+ +

The creation or removal of mount points and symlinks in the +Freelance “root.afs” volume are also restricted to members of the “AFS Client +Admins” group.

+ +

The initial membership of the "AFS Client Admins" +group when created by the installer is equivalent to the local +"Administrators" group.  If a +user is added to the "Administrators" group after the creation of the +"AFS Client Admin" group, that user will not be an AFS Client +Administrator.  Only users that are +members of the "AFS Client Admins" group are AFS Client +Administrators.  The local +"SYSTEM" account is an implicit member of the "AFS Client +Admins" group.

+ +

Setting the default sysname for a machine should be done via +the registry +and not via "fs sysname".

+ +

3.8. OpenAFS +support for UNC paths

+ +

The OpenAFS 1.4 client supports UNC paths everywhere.  UNC paths provide a canonical name for +resources stored within AFS.  UNC paths +should be used instead of drive letter mappings whenever possible.   This is especially true when specifying the +location of roaming profiles and redirected folders.  

+ +

Power users that make extensive use of the command line +shell, cmd.exe, should consider using JP Software's 4NT or Take Command command +processors.  Unlike cmd.exe, the +JPSoftware shells fully support UNC paths as the current directory.  With the release of version 4NT 7.0 and Take +Command 7.0, JPSoftware is adding special recognition of OpenAFS.  AFS paths can be entered in UNIX notation +(e.g., /afs/openafs.org/software), +space utilization reports the output of the volume status for the specified +path, and many AFS specific functions and variables have been added to the +command language.

+ +

JPSoftware's web site is http://www.jpsoft.com.

+ +

3.9. OpenAFS +includes aklog.exe

+ +

The OpenAFS 1.4 Client ships with its own version of +aklog.exe which should be used in preference to those obtained by third party +sources.  The OpenAFS aklog.exe supports +Kerberos 5 as well as the ability to auto-generate pts IDs for user's obtaining +tokens  for access to foreign cells.

+ +

Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]

+ +

             +[[-p | -path] pathname]

+ +

             +[-noprdb] [-force]

+ +

             +[-5 [-m]| -4]

+ +

 

+ +

   -d = output +debugging information.

+ +

   cell = zero +or more cells for which tokens will be obtained

+ +

   krb_realm = +the kerberos realm of the cell.

+ +

   pathname = +the directory for which authentication is required

+ +

   -noprdb = +don't try to determine AFS ID.

+ +

   -5 or -4 = +use Kerberos V (default) or Kerberos IV tickets

+ +

   -m = use +krb524d to convert Kerberos V tickets to Kerberos IV

+ +

3.10. OpenAFS +Servers on Windows are Unsupported

+ +

The AFS Server functionality provided with OpenAFS 1.4 might +work but should be considered highly experimental.  It has not been thoroughly tested.  Any data which would cause pain if lost +should not be stored in an OpenAFS Server on Windows.

+ +

A few notes on the usage of the AFS Client Service if it is +going to be used with the OpenAFS AFS Server:

+ +

·       When +installed on the same machine as the AFS Server, Freelance mode must be turned +off.  Otherwise, you will be unable to +manipulate the contents of the root.afs volume for the hosted cell.

+ +

·       The +AFS Server and related tools only support the built in kaserver (Kerberos +IV).  If the AFS Server is being used, +MIT Kerberos for Windows should not be installed or must be disabled.

+ +

3.11. OpenAFS +Debugging Symbol files

+ +

The OpenAFS for Windows installers now include Debugging +Symbol files which should be installed if you are experiencing problems and +need to send crash reports.  This is true +for both the release and the debug versions of the installers.  The difference between the release and debug +versions are:

+ +

·       whether +or not the binaries were compiled with optimization

+ +

·       whether +the debug symbols are installed by default

+ +

·       whether +additional debug statements were compiled into the binaries

+ +

3.12. Maximum +File Size is 2GB

+ +

OpenAFS for Windows does not support files larger than +2GB.  The version of the SMB/CIFS +protocol implemented imposes this limitation.  +Upgrading the SMB/CIFS implementation or replacing it with an +Installable File System will allow larger files to be supported.

+ +

3.13. Encrypted +AFS File Access

+ +

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.

+ +

3.14. +Authenticated Access to the OpenAFS Client Service

+ +

OpenAFS 1.4 supports authenticated 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 5 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.   OpenAFS 1.4 does +not use Windows .INI files for the storage of configuration data.   All settings are now stored in the registry +(see Appendix +A).  The CellServDB file is now +stored in the %PROGRAMFILES%\OpenAFS\Client directory.   The CellServDBDir +registry value can be used to specify an alternative location.

+ +

OpenAFS 1.4 will relocate the contents of the “afsdcell.ini” +file to the new CellServDB file.  OpenAFS +1.4 will also import the contents of the “afs_freelance.ini” file to the +Windows registry.   OpenAFS 1.4 will not +process the contents of the “afsddbmt.ini”.

+ +

3.16. Microsoft +Windows Internet Connection Firewall

+ +

The OpenAFS 1.4 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 1.4 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. No Support +for Byte Range +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 does not currently support byte +range locks.   It is strongly recommended +that files not be edited within AFS if they might be accessed by multiple users +or multiple processes on a single machine.

+ +

3.19. Automatic +Discarding of AFS Tokens at Logoff

+ +

OpenAFS 1.4 will automatically forget a user's tokens upon +Logoff unless the user's profile was loaded from an AFS volume.  In this situation there is no mechanism to +determine when the profile has been successfully written back to the +network.  It is therefore unsafe to +release the user's tokens.  Whether or +not the profile has been loaded from the registry can be determined for Local +Accounts, Active Directory accounts and NT4 accounts.

+ +

If there is a need to disable this functionality, the LogoffPreserveTokens +registry value can be used. (see Appendix +A.)

+ +

3.20. 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.

+ +

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.  +In OpenAFS 1.4, the default number of Status Cache entries is 10,000.

+ +

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.

+ +

3.24. OpenAFS +binaries are digitally signed

+ +

The OpenAFS Client Service and related binaries distributed +by OpenAFS.org are digitally signed by "Secure Endpoints Inc.".  The OpenAFS Client Service will perform a +run-time verification check to ensure that all OpenAFS related DLLs loaded by +the service match the same file version number and were signed by the same +entity.  This check has been added to +prevent the stability problems caused by more than one AFS installation present +on a machine at the same time.  Many +hours of support time have been wasted tracking down problems caused by the +mixture of files from different releases.  +

+ +

Appendix +A documents the "VerifyServiceSignature" +registry value which can be used to disable the signature check.  The file version check cannot be disabled.

+ +

3.25. Maximum +Size of the AFSCache File

+ +

The maximum cache size 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.

+ +

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

+
+ +

 

+ +

OpenAFS 1.4 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.  OpenAFS for Windows does not currently +support UNICODE.  To avoid this problem +some sites run 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.

+ +

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 OpenAFS 1.4 is set to +"x86_win32 i386_w2k i386_nt40" for 32-bit x86 systems.  The default for itanium will be +"ia64_win64" and "amd64_win64" for amd 64-bit processors +when those platforms are supported.

+ +

3.31. Symlinks to +AFS UNC paths

+ +

In OpenAFS 1.4, 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.

+ +

3.32. Cache +Manager Debugging Now Supported

+ +

OpenAFS for Windows 1.4 implements the Cache Manager +Debugging RPC Interface.  The CM debugger +can be queried with cmdebug.exe.

+ +

Usage: cmdebug -servers <server machine> [-port +<IP port>] [-long]

+ +

               +[-addrs] [-cache] [-help]

+ +

Where: -long   +print all info

+ +

       +-addrs  print only host interfaces

+ +

       +-cache  print only cache +configuration

+ +

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 Beta 1 or later.

+ +

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

+ +

OpenAFS 1.4 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 adds 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.

+ +

3.38. AFS Client +Universally Unique Identifiers

+ +

The OpenAFS for Windows 1.4 client implements Universally +Unique Identifiers (UUIDs).  They are +used to provide the server with a method of identifying the client that is +independent of IP address.  The UUID is +generated when the AFSCache file is created and is maintained as long as the +contents of the AFSCache file are kept intact.  +The UUID is stored in the AFSCache file.   When cloning machines that have Windows AFS +client installed, the AFSCache files must be deleted as part of the cloning +process.

+ +

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.

+ +

4.1. pioctl +debugging (IoctlDebug +registry key)

+ +

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.

+ +

4.3. afsd_service +debug logs (fs trace {-on, -off, -dump} ->%WinDir%\TEMP\afsd.log)

+ +

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.

+ +

4.4. Using +SysInternal’s DbgView and FileMon Tools

+ +

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 DbgView 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 FileMon utility can be use to monitor the file +operations requested by applications and their success or failure.   Restrict FileMon to monitor Network Volumes +only in order to reduce the output to just the CIFS requests.   

+ +

Turn on the Clock Time +option 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.

+ +

4.5. Microsoft +MiniDumps
+(fs minidump -> %WinDir%\TEMP\afsd.dmp)

+ +

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.

+ +

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.

+ +

Usage: cmdebug -servers <server machine> [-port +<IP port>] [-long]

+ +

   [-refcounts] [-callbacks] [-addrs] [-cache] +[-help]

+ +

Where: -long       +print all info

+ +

       +-refcounts  print only cache +entries with positive reference counts

+ +

       +-callbacks  print only cache +entries with callbacks

+ +

       +-addrs      print only host +interfaces

+ +

       +-cache      print only cache +configuration

+ +

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.

+ +

  +afsd_service.exe --validate-cache <cache-path>

+ +

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.

+ +
+ + + + + +
+

USENIX OpenAFS Fund
+ USENIX Association
+2560 Ninth St., Suite 215 +
+Berkeley, CA 94710

+
+ +
+ +
+ + +

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. The MIT Kerberos Account

+ +

The MIT +Kerberos development team accepts unrestricted grants.  Grants are tax deductible and the full amount +of the grant will be used to fund the development of Kerberos 5 and/or Kerberos +for Windows.  OpenAFS for Windows is +dependent on MIT Kerberos for Windows for authentication and shares many of the +same requirements for credential +management.  Future releases of both +products will share a common identity management user interface.

+ +

6.4. 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.

+ +

6.5. +OpenAFS for Windows Mailing Lists

+ +

If you wish to participate in OpenAFS for Windows +development please join the openafs-win32-devel@openafs.org +mailing list.

+ +

https://lists.openafs.org/mailman/listinfo/openafs-win32-devel

+ +

User questions should be sent to the openafs-info@openafs.org +mailing list. 

+ +

https://lists.openafs.org/mailman/listinfo/openafs-info

+ +

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.

+ +

For general information about "Windows Installer", +refer to:

+ +

    http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp

+ +

For general information about authoring MSI transforms, +refer to:

+ +

    http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp

+ +

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:

+ +

    http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp

+ +

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.

+ +

7.2.1.2 OpenAFS for Windows Properties

+ + + + + + + + + + + +
+
(Service + parameters):
+

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

+
+
(Network + provider):
+

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

+
+
(OpenAFS + Client):
+

[HKLM\SOFTWARE\OpenAFS\Client]

+
+ +
7.2.1.2.1 Registry Properties
+ +

These properties are used to set the values of registry +entries associated with OpenAFS for Windows.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
AFSCACHEPATH
+

Registry key    : (Service + parameters)

+

Registry value : CachePath

+

Valid values    : string .

+
+
AFSCACHESIZE
+

Registry key    : (Service + parameters)

+

Registry value : CacheSize

+

Valid values    : + numeric

+
+
AFSCELLNAME
+

Registry key    : (Service + parameters)

+

Registry value : Cell

+

Valid values    : + string

+
+
FREELANCEMODE
+

Registry key    : (Service + parameters)

+

Registry value : FreelanceClient

+

Valid values    : '1' + or '0'

+
+
HIDEDOTFILES
+

Registry key    : (Service + parameters)

+

Registry value : HideDotFiles

+

Valid values    : '1' + or '0'

+
+
LOGONOPTIONS
+

Registry key    : (Network + provider)

+

Registry value : LogonOptions

+

Valid values    : '0', '1' + or '3'

+

See Appendix + A section + 2.1 (Domain specific configuration keys for Network Provider) for more + details.

+
+
MOUNTROOT
+

Registry key    : (Service + parameters)

+

Registry value : Mountroot

+

Valid values    : + string

+
+
NETBIOSNAME
+

Registry key    : (Service + parameters)

+

Registry value : NetbiosName

+

Valid values    : + string (at most 15 characters)

+
+
NOFINDLANABYNAME
+

Registry key    : (Service + parameters)

+

Registry value : NoFindLanaByName

+

Valid values    : '1' + or '0'

+
+
RXMAXMTU
+

Registry key    : (Service + parameters)

+

Registry value : RxMaxMTU

+

Valid values    : + numeric

+
+
SECURITYLEVEL
+

Registry key    : (Service + parameters)

+

Registry value : SecurityLevel

+

Valid values    : '1' + or '0'

+
+
SMBAUTHTYPE
+

Registry key    : (Service + parameters)

+

Registry value : SMBAuthType

+

Valid values    : + '0','1' or '2'

+
+
STOREANSIFILENAMES
+

Registry key    : (OpenAFS + Client)

+

Registry value : StoreAnsiFilenames

+

Valid values    : '0' or + '1'

+
+
USEDNS
+

Registry key    : (Service + parameters)

+

Registry value : UseDNS

+

Valid values    : '1' + or '0'

+
+ +
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
+

Valid values    : '-s' + or ''

+

Enables displaying the credential manager window when + AFSCREDS starts up.

+
+ +

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.

+ +

7.2.3.1 Components for Configuration Files

+ +

CellServDB: +'cpf_CellServDB' (ID {D5BA4C15-DBEC-4292-91FC-B54C30F24F2A})

+ +

7.2.4 +Adding Domain Specific Registry Keys

+ +

Following is an example for adding domain specific registry +keys.

+ +

    +Refer to Appendix +A section 2.1 for more information.

+ +

    Columns that are +unspecified should be left empty.

+ +

    We create a new +feature and component to hold the new registry keys.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

    + 'Feature' table:

+
+

            (new row)
+             Feature            : 'feaDomainKeys'
+             Feature Parent : 'feaClient'
+             Display           : 0
+             Level               : 30
+             Attributes        : 10

+
+

    'Component' + table:

+
+

            (new + row)
+             Component     : 'rcm_DomainKeys'
+             ComponentId  : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
+             Directory         : 'TARGETDIR'
+             Attributes        : 4
+             KeyPath          : 'reg_domkey0'

+
+

    + 'FeatureComponents' table:

+
+

            (new row)
+             Feature            : 'feaDomainKeys'
+             Component     : 'rcm_DomainKeys'

+
+

    'Registry' + table:

+
+

            (new row)
+             Registry          : 'reg_domkey0'
+             Root                : 2
+             Key                 : + 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
+             Component     : 'rcm_DomainKeys'

+
+

            (new row)
+             Registry          : 'reg_domkey1'
+             Root                : 2
+             Key                 : + 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
+             Name              : '*'
+             Component     : 'rcm_DomainKeys'

+
+

            (new row)
+             Registry          : 'reg_domkey2'
+             Root                : 2
+             Key                 : + 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
+             Name              : '*'
+             Component     : 'rcm_DomainKeys'

+
+

            (new row)
+             Registry          : 'reg_domkey3'
+             Root                : 2
+             Key                 : + 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
+             Name              : 'LogonOptions'
+             Value              : 1
+             Component     : 'rcm_DomainKeys'

+
+

            (new row)
+             Registry          : 'reg_domkey4'
+             Root                : 2
+             Key                 : SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
+             Name              : '*'
+             Component     : 'rcm_DomainKeys'

+
+

            (new row)
+             Registry          : 'reg_domkey5'
+             Root                : 2
+             Key                 : + 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
+             Name              : 'LogonOptions'
+             Value              : 0
+             Component     : 'rcm_DomainKeys'

+
+

            (new row)
+             Registry          : 'reg_domkey6'
+             Root                : 2
+             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
+             Name              : 'FailLoginsSilently'
+             Value              : 1
+             Component     : 'rcm_DomainKeys'
+
+

+
+ +

 

+ +

The example adds domain specific keys for 'ATHENA.MIT.EDU' +(enable integrated logon) and 'LOCALHOST' (disable integrated logon and fail +logins silently).

+ +

7.2.5 +Adding Site Specific Freelance Registry Keys

+ +

Following is an example for adding site specific Freelance +registry keys to pre-populate the Mountpoints and Symlinks in the fake root.afs +volume.

+ +

    Columns that are +unspecified should be left empty.

+ +

    We create a new +feature and component to hold the new registry keys.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

    + 'Feature' table:

+
+

            (new row)
+             Feature            : 'feaFreelanceKeys'
+             Feature Parent : 'feaClient'
+             Display           : 0
+             Level               : 30
+             Attributes        : 10

+
+

    'Component' + table:

+
+

            (new row)
+             Component     : 'rcm_FreelanceKeys'
+             ComponentId  : '{4E3B3CBF4-9AE7-40C3-7B09-C48CF842C583}'
+             Directory         : 'TARGETDIR'
+             Attributes        : 4
+             KeyPath          : 'reg_freekey0'

+
+

    + 'FeatureComponents' table:

+
+

            (new row)
+             Feature            : 'feaFreelanceKeys'
+             Component     : 'rcm_FreelanceKeys'

+
+

    'Registry' + table:

+
+

            (new row)
+             Registry          : 'reg_freekey0'
+             Root                : 2
+             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'
+             Component     : 'rcm_FreelanceKeys'

+
+

            (new row)
+             Registry          : 'reg_freekey1'
+             Root                : 2
+             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'
+             Name              : '0'
+             Value              : + 'athena.mit.edu#athena.mit.edu:root.cell.'
+             Component     : 'rcm_FreelanceKeys'

+
+

            (new row)
+             Registry          : 'reg_freekey2'
+             Root                : 2
+             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'
+             Name              : '1'
+             Value              : + '.athena.mit.edu%athena.mit.edu:root.cell.'
+             Component     : 'rcm_FreelanceKeys'

+
+

            (new row)
+             Registry          : 'reg_freekey3'
+             Root                : 2
+             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
+             Component     : 'rcm_FreelanceKeys'

+
+

            (new row)
+             Registry          : 'reg_freekey4'
+             Root                : 2
+             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
+             Name              : '0'
+             Value              : + 'athena:athena.mit.edu.'
+             Component     : 'rcm_FreelanceKeys'

+
+

            (new row)
+             Registry          : 'reg_freekey5'
+             Root                : 2
+             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
+             Name              : '1'
+             Value              : + '.athena:.athena.mit.edu.'
+             Component     : 'rcm_FreelanceKeys'

+
+ +

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 :

+ +

http://msdn.microsoft.com/library/en-us/msi/setup/using_transforms_to_add_resources.asp

+ +

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')

+ +

    > msitran.exe +-g openafs-en_US.msi openafs-en_US_new.msi 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

+ +

2)      MIT's +Transarc AFS MSI package
+Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}
+Up to version 3.6.2

+ +

3)      OpenAFS +NSIS package
+All versions

+ +

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).

+ +

Regkey:
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
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'.

+
+
Value: + CacheSize
+

Type: DWORD
+ Default: 98304 (CM_CONFIGDEFAULT_CACHESIZE)
+ Variable: cm_initParams.cacheSize

+

Size of the AFS cache in 1k blocks.

+
+
Value: ChunkSize
+

Type: DWORD
+ Default: 17 (CM_CONFIGDEFAULT_CHUNKSIZE)
+ Variable: cm_logChunkSize (cm_chunkSize = 1 << cm_logChunkSize)

+

Size of chunk for reading and writing. Actual chunk size + is 2^cm_logChunkSize.

+
+
Value: Daemons
+

Type: DWORD
+ Default: 2 (CM_CONFIGDEFAULT_DAEMONS)
+ Variable: numBkgD

+

Number of background daemons (number of threads of + cm_BkgDaemon). (see cm_BkgDaemon in cm_daemon.c)

+
+
Value: ServerThreads
+

Type: DWORD
+ Default: 25 (CM_CONFIGDEFAULT_SVTHREADS)
+ Variable: numSvThreads

+

Number of SMB server threads (number of threads of + smb_Server). (see smb_Server in smb.c).

+
+
Value: Stats
+

Type: DWORD
+ Default: 10000 (CM_CONFIGDEFAULT_STATS)
+ Variable: cm_initParams.nStatCaches

+

Cache configuration.

+
+
Value: + LogoffPreserveTokens
+

Type: DWORD {1,0}
+ Default : 0

+

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
+

Type: REG_SZ or REG_EXPAND_SZ
+ Default: "%TEMP%\AFSCache"
+ Variable: cm_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 prevents the use of + persistent caching (when available) as well as the ability to alter the size + of the cache at runtime using the "fs setcachesize" command.

+
+
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: + TraceBufferSize
+

Type: DWORD
+ Default: 5000 (CM_CONFIGDEFAULT_TRACEBUFSIZE)
+ Variable: traceBufSize

+

Number of entries to keep in trace log.

+
+
Value: + SysName
+

Type: REG_SZ
+ Default: "i386_nt40"
+ Variable: cm_sysName

+

Provides an initial value for "fs sysname".  The string can contain one or more + replacement values for @sys in order of preference separated by whitespace.

+
+
Value: + SecurityLevel
+

Type: DWORD {1,0}
+ Default: 0
+ Variable: cryptall

+

Enables encryption on RX calls.

+
+
Value: + UseDNS
+

Type: DWORD {1,0}
+ Default: 1
+ Variable: cm_dnsEnabled

+

Enables resolving volservers using AFSDB DNS queries.

+

As of 1.3.60, this value is ignored as the DNS query + support utilizes the Win32 DNSQuery API which is available on Win2000 and + above.

+
+
Value: + FreelanceClient
+

Type: DWORD {1,0}
+ Default: 0
+ Variable: cm_freelanceEnabled

+

Enables freelance client.

+
+
Value: + HideDotFiles
+

Type: DWORD {1,0}
+ Default: 1
+ Variable: smb_hideDotFiles

+

Enables marking dotfiles with the hidden attribute.  Dot files are files whose name starts with + a period (excluding "." and "..").

+
+
Value: MaxMpxRequests
+

Type: DWORD
+ Default: 50
+ Variable: smb_maxMpxRequests

+

Maximum number of multiplexed SMB requests that can be + made.

+
+
Value: MaxVCPerServer
+

Type: DWORD
+ Default: 100
+ Variable: smb_maxVCPerServer

+

Maximum number of SMB virtual circuits.

+
+
Value: Cell
+

Type: REG_SZ
+ Default: <none>
+ Variable: rootCellName

+

Name of root cell (the cell from which root.afs should + be mounted in \\afs\all).

+
+
Value: RxNoJumbo
+

Type: DWORD {0,1}
+ Default: 0
+ Variable: rx_nojumbo

+

If enabled, does not send or indicate that we are able + to send or receive RX jumbograms.

+
+
Value: + RxMaxMTU
+

Type: DWORD
+ Default: -1
+ Variable: rx_mtu

+

If set to anything other than -1, uses that value as the + maximum MTU supported by the RX interface.

+

In order to enable OpenAFS to operate across the Cisco + IPSec VPN client, this value must be set to 1264 or smaller.

+
+
Value: + ConnDeadTimeout
+

Type: DWORD
+ Default: 60 (seconds)
+ Variable: ConnDeadtimeout

+

The Connection Dead Time is enforced to be at a minimum + 15 seconds longer than the minimum SMB timeout as specified by + [HKLM\SYSTEM\CurrentControlSet\Services\lanmanworkstation\parameters] + SessTimeout

+

If the minimum SMB timeout is not specified the value is + 45 seconds.  See http://support.microsoft.com:80/support/kb/articles/Q102/0/67.asp

+
+
Value: + HardDeadTimeout
+

Type: DWORD
+ Default: 120 (seconds)
+ Variable: HardDeadtimeout

+

The Hard Dead Time is enforced to be at least double the + ConnDeadTimeout.  The provides an opportunity + for at least one retry.

+
+
Value: + TraceOption
+

Type: DWORD {0-15}
+ Default: 0

+

Enables logging of debug output to the Windows Event + Log.

+

Bit 0 enables logging of "Logon Events" + processed by the Network Provider and Winlogon Event Notification Handler. 

+

Bit 1 enables logging of events captured by the AFS + Client Service.

+

Bit 2 enables real-time viewing of "fs trace" + logging with DbgView or similar tools.

+

Bit 3 enables "fs trace" logging on startup.

+
+
Value: AllSubmount
+

Type: DWORD {0, 1}
+ Default: 1

+

Variable: allSubmount (smb.c)

+

By setting this value to 0, the + "\\NetbiosName\all" mount point will not be created.  This allows the read-write versions of + root.afs to be hidden.

+
+
Value: + NoFindLanaByName
+

Type: DWORD {0, 1}
+ Default: 0

+

Disables the attempt to identity the network adapter to + use by looking for an adapter with a display name of "AFS".

+
+
Value: MaxCPUs
+

Type: DWORD {1..32} or {1..64} depending on the + architecture
+ Default: <no default>

+

If this value is specified, afsd_service.exe will + restrict itself to executing on the specified number of CPUs if there are a + greater number installed in the machine.  +

+
+
Value: + smbAuthType
+

Type: DWORD {0..2}
+ Default: 2

+

If this value is specified, it defines the type of SMB + authentication which must be present in order for the Windows SMB client to + connect to the AFS Client Service's SMB server.  The values are:

+

0 = No authentication required
+ 1 = NTLM authentication required
+ 2 = Extended (GSS SPNEGO) authentication required
+ The default is Extended authentication

+
+
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.

+
+ +

Regkey:
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters\GlobalAutoMapper]

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

Type: REG_SZ

+

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

+
+ +

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 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.  See the + Microsoft Developer Library for further information.

+

MiniDumpNormal = 0x00000000,
+ MiniDumpWithDataSegs = 0x00000001,
+ MiniDumpWithFullMemory = 0x00000002,
+ MiniDumpWithHandleData = 0x00000004,
+ MiniDumpFilterMemory = 0x00000008,
+ MiniDumpScanMemory = 0x00000010,
+ MiniDumpWithUnloadedModules = 0x00000020,
+ MiniDumpWithIndirectlyReferencedMemory = 0x00000040,
+ MiniDumpFilterModulePaths = 0x00000080,
+ MiniDumpWithProcessThreadData = 0x00000100,
+ MiniDumpWithPrivateReadWriteMemory = 0x00000200,
+ MiniDumpWithoutOptionalData = 0x00000400,
+ MiniDumpWithFullMemoryInfo = 0x00000800,
+ MiniDumpWithThreadInfo = 0x00001000,
+ MiniDumpWithCodeSegs = 0x00002000

+
+
Value: + StoreAnsiFilenames
+

Type: REG_DWORD
+ Default: 0x0

+

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. 

+

Note: The use of ANSI characters will render access to + files with 8-bit OEM file names unaccessible from Windows.  This option is of use primarily when you + wish to allow file names produced on Windows to be accessible from Latin-1 UNIX + systems and vice versa.

+
+ +

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

+ + + + + +
+
Value: + "smb/cifs share name"
+

Type: REG_SZ
+ Default: <none>

+

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\Submounts]

+ + + + + +
+
Value: + "submount name"
+

Type: REG_EXPAND_SZ
+ Default: <none>

+

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.

+
+ +

Regkey:
+[HKLM\SOFTWARE\OpenAFS\Client\Server Preferences\VLDB]

+ + + + + +
+
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.

+
+ +

A.2. Integrated +Logon Network provider parameters

+ +

Affects the network provider (afslogon.dll).

+ +

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

+ + + + + +
+
Value: + FailLoginsSilently
+

Type: DWORD
+ Default: 0

+

Do not display message boxes if + the login fails.

+
+ +

Regkey:
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]

+ + + + + + + + + + + + + + + + + + + + + + + +
+
Value: + NoWarnings
+

Type: DWORD
+ Default: 0

+

Disables visible warnings during + logon.

+
+
Value: + AuthentProviderPath
+

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

+

Specifies the install location of the authentication + provider dll.

+
+
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.

+ +

Domain specific registry keys are:

+ +

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

+ +

  (NP key)

+ +

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain]

+ +

  (Domains key)

+ +

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\"domain +name"]

+ +

  (Specific domain +key. One per domain.)

+ +

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST]

+ +

  (Localhost key)

+ +

Example:

+ +

 HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider

+ +

  |

+ +

  +- Domain

+ +

     ++-AD1.EXAMPLE.COM

+ +

     ++-AD2.EXAMPLE.NET

+ +

     ++-LOCALHOST

+ +

Each of the domain specific keys can have the set of +values described in 2.1.1.  The effective +values are chosen as described in 2.1.2.

+ +

A.2.1.1 Domain +specific configuration values

+ +

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain]
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\"domain +name"]
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST]

+ + + + + + + + + + + + + + + + + + + + +
+
Value: + LogonOptions
+

Type: DWORD
+ Default: 0x01

+

NSIS/WiX: depends on user + configuration

+

0x00 - Integrated Logon is not + used
+ 0x01 - Integrated Logon is used
+ 0x02 - High Security Mode is used (deprecated)
+ 0x03 - Integrated Logon with High Security Mode is used (deprecated)

+

High Security Mode generates + random SMB names for the creation of Drive Mappings.  This mode should not be used without + Integrated Logon.

+

As of 1.3.65 the SMB server + supports SMB authentication.  The High + Security Mode should not be used when using SMB authentication (SMBAuthType + setting is non zero).

+
+
Value: + FailLoginsSilentl
+

Type: DWORD (1|0)
+ Default: 0
+ NSIS/WiX: (not set)

+

If true, does not display any visible warnings in the + event of an error during the integrated login process.

+
+
Value: LogonScript
+

Type: REG_SZ or REG_EXPAND_SZ
+ Default: (null)
+ NSIS/WiX: (only value under NP key) <install path>\afscreds.exe -:%s -x + -a -m -n -q

+

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: + TheseCells
+

Type: REG_MULTI_SZ
+ NSIS: <not set>

+

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

+
+ +

A.2.1.2  Selection of effective values for domain +specific configuration

+ +

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.

+ +

1.      +NP key. ("HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider")

+ +

2.      +Domains key. (NP key\"Domain")

+ +

3.      +Specific domain key. (Domains key\X)

+ +

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.

+ +

A.3. AFS +Credentials System Tray Tool parameters

+ +

Affects the behavior of afscreds.exe

+ +

Regkey:
+[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

+ + + + + + + + +
+
Value: + Gateway
+

Type: REG_SZ
+ Default: ""
+ Function: GetGatewayName()

+

If the AFS client is utilizing a + gateway to obtain AFS access, the name of the gateway is specified by this + value.

+
+
Value: Cell
+

Type: REG_SZ
+ Default: <none>
+ Variable: IsServiceConfigured()

+

The value Cell is used to determine if the AFS Client + Service has been properly configured or not.

+
+ +

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

+ + + + + + + + + + + + + + +
+
Value: + ShowTrayIcon
+

Type: DWORD {0, 1}
+ Default: 1
+ Function: InitApp(), Main_OnCheckTerminate()

+

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 5 + will be used to obtain AFS credentials.  + By setting this value to 0, the internal Kerberos 4 implementation + will be used instead.  The current user + value is checked first; if it does not exist the local machine value is + checked.

+
+
Value: + Use524
+

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

+

When MIT Kerberos for Windows can be loaded, Kerberos 5 + will be used to obtain AFS credentials.  + By setting this value to 1, the Kerberos 5 tickets will be converted + to Kerberos 4 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:

+

-A = autoinit
+ -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
+ -Z = unmap drives

+
+ +

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

+ + + + + +
+
Value: + Authentication Cell
+

Type: REG_SZ
+ Default: <none>
+ Function: Afscreds.exe GetDefaultCell()

+

This value allows the user to + configure a different cell name to be used as the default cell when acquiring + tokens in afscreds.exe.

+
+ +

Regkey:
+[HKCU\SOFTWARE\OpenAFS\Client\Reminders]

+ + + + + +
+
Value: + "afs cell name"
+

Type: DWORD {0, 1}
+ Default: <none>
+ Function: LoadRemind(), SaveRemind()

+

These values are used to save + and restore the state of the reminder flag for each cell for which the user + has obtained tokens.

+

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

+
+ +

Regkey:
+[HKCU\SOFTWARE\OpenAFS\Client\Active Maps]

+ + + + + +
+
Value: + "upper case drive letter"
+

Type: DWORD {0, 1}
+ Default: <none>

+

These values are used to store + the persistence state of the AFS drive mappings as listed in the + [...\Client\Mappings] key.

+

These values used to be stored + in the afsdsbmt.ini file

+
+ +

Regkey:
+[HKCU\SOFTWARE\OpenAFS\Client\Mappings]

+ + + + + +
+
Value: + "upper case drive letter"
+

Type: REG_SZ
+ Default: <none>

+

These values are used to store + the AFS path in UNIX notation to which the drive letter is to be mapped.

+

These values used to be stored + in the afsdsbmt.ini file.

+
+ +

A.4 OpenAFS +Client Service Environment Variables

+ + + + + + + + +
+
Variable: + AFS_RPC_ENCRYPT
+

Values:   "OFF" disables the use of RPC + encryption any other value allows RPC encryption to be used
+ Default:  RPC encryption is on

+
+
Variable: + AFS_RPC_PROTSEQ
+

Values:            "ncalrpc"  - local RPC
+                         "ncacn_np" + - named pipes
+                         "ncacn_ip_tcp" + - tcp/ip
+ Default:  local RPC

+
+ +

 

+ +
+ + + + diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/filelist.xml b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/filelist.xml new file mode 100644 index 000000000..ff158d365 --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/filelist.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/header.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/header.htm new file mode 100644 index 000000000..c1bd4e4e1 --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/header.htm @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + +
+ +

+ +

+ +

+ +
+ +
+ +

+ +

+ +

+ +
+ +
+ +

+ +

+ +

+ +
+ +
+ +

+ +

+ +

+ +
+ +
+ +

OpenAFS for Windows 1.4.0 Release Notes

+ +
+ + + + diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/preview.wmf b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/preview.wmf new file mode 100644 index 000000000..8158584d4 Binary files /dev/null and b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/relnotes_files/preview.wmf differ diff --git a/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm new file mode 100644 index 000000000..72bf70cab --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/ReleaseNotes/toc.htm @@ -0,0 +1,1487 @@ + + + + + + + + + +OpenAFS for Windows Release Notes TOC + + + + + + + +
+ +

+ +

1. +Installer Options. Error! Bookmark not defined.

+ +

2. +System Requirements. Error! Bookmark not defined.

+ +

2.1 +Supported Operating Systems. Error! Bookmark not defined.

+ +

2.2 +Disk Space. Error! Bookmark not defined.

+ +

2.3 +Additional Software. Error! Bookmark not defined.

+ +

3. +Operational Notes. Error! Bookmark not defined.

+ +

3.1. +Requirements for Kerberos 5 Authentication. Error! Bookmark not defined.

+ +

3.2. +Use of the Microsoft Loopback Adapter Error! Bookmark not defined.

+ +

3.3. +Using Freelance (Dynamic Root) Mode to Improve Mobility. Error! Bookmark not defined.

+ +

3.4. +Locating AFS Volume Database Servers. Error! Bookmark not defined.

+ +

3.5. +Obtaining AFS Tokens as a Part of Windows Logon. Error! Bookmark not defined.

+ +

3.6. +AFS System Tray Command Line Options. Error! Bookmark not defined.

+ +

3.7. +The “AFS Client Admins” Authorization Group. Error! Bookmark not defined.

+ +

3.8. +OpenAFS support for UNC paths. Error! Bookmark not defined.

+ +

3.9. +OpenAFS includes aklog.exe. Error! Bookmark not defined.

+ +

3.10. +OpenAFS Servers on Windows are Unsupported. Error! Bookmark not defined.

+ +

3.11. +OpenAFS Debugging Symbol files. Error! Bookmark not defined.

+ +

3.12. +Maximum File Size is 2GB.. Error! Bookmark not defined.

+ +

3.13. +Encrypted AFS File Access. Error! Bookmark not defined.

+ +

3.14. +Authenticated Access to the OpenAFS Client Service. Error! Bookmark not defined.

+ +

3.15. +No More INI Files. Error! Bookmark not defined.

+ +

3.16. +Microsoft Windows Internet Connection Firewall Error! Bookmark not defined.

+ +

3.17. +Browsing AFS from the Explorer Shell and Office. Error! Bookmark not defined.

+ +

3.18. +No Support for Byte Range Locking. Error! Bookmark not defined.

+ +

3.19. +Automatic Discarding of AFS Tokens at Logoff. Error! Bookmark not defined.

+ +

3.20. +Terminal Server installations. Error! Bookmark not defined.

+ +

3.21. +Hidden Dot Files. Error! Bookmark not defined.

+ +

3.22. +Status Cache Limits. Error! Bookmark not defined.

+ +

3.23. +NETBIOS over TCP/IP must be enabled. Error! Bookmark not defined.

+ +

3.24. +OpenAFS binaries are digitally signed. Error! Bookmark not defined.

+ +

3.25. +Maximum Size of the AFSCache File. Error! Bookmark not defined.

+ +

3.26. +Filename Character Sets. Error! Bookmark not defined.

+ +

3.27. +Known Character Set Issues with Roaming Profiles. Error! Bookmark not defined.

+ +

3.28. +The AFSCache File. Error! Bookmark not defined.

+ +

3.29. +Restricting OpenAFS Client Service Start and Stop. Error! Bookmark not defined.

+ +

3.30. +The @sys Name List Error! Bookmark not defined.

+ +

3.31. +Symlinks to AFS UNC paths. Error! Bookmark not defined.

+ +

3.32. +Cache Manager Debugging Now Supported. Error! Bookmark not defined.

+ +

3.33. +Windows Logon Caching vs. Kerberos Logons. Error! Bookmark not defined.

+ +

3.34. +Initial Server Preferences. Error! Bookmark not defined.

+ +

3.35. +File Timestamps. Error! Bookmark not defined.

+ +

3.36. +Windows RPC client support must be installed. Error! Bookmark not defined.

+ +

3.37. +Generating Minidumps of the OpenAFS Client Service. Error! Bookmark not defined.

+ +

3.38. +AFS Client Universally Unique Identifiers. Error! Bookmark not defined.

+ +

4. +How to Debug Problems with OpenAFS for Windows: Error! Bookmark not defined.

+ +

4.1. +pioctl debugging (IoctlDebug registry key) Error! Bookmark not defined.

+ +

4.2. +afsd_service initialization log (%WinDir%\TEMP\afsd_init.log) Error! Bookmark not defined.

+ +

4.3. +afsd_service debug logs (fs trace {-on, -off, -dump} +->%WinDir%\TEMP\afsd.log) Error! Bookmark not defined.

+ +

4.4. +Using SysInternal’s DbgView and FileMon Tools. Error! Bookmark not defined.

+ +

4.5. +Microsoft MiniDumps  (fs minidump -> +%WinDir%\TEMP\afsd.dmp) Error! Bookmark not defined.

+ +

4.6. +Single Sign-on (Integrated Logon) debugging. Error! Bookmark not defined.

+ +

4.7. +RX (AFS RPC) debugging (rxdebug) Error! Bookmark not defined.

+ +

4.8. +Cache Manager debugging (cmdebug) Error! Bookmark not defined.

+ +

4.9. +Persistent Cache consistency check. Error! Bookmark not defined.

+ +

5. +Reporting Bugs: Error! Bookmark not defined.

+ +

6. +How to Contribute to the Development of OpenAFS for Windows. Error! Bookmark not defined.

+ +

6.1. +The USENIX OpenAFS Fund. Error! Bookmark not defined.

+ +

6.2. +Secure Endpoints Inc. Error! Bookmark not defined.

+ +

6.3. +The MIT Kerberos Account Error! Bookmark not defined.

+ +

6.4. +Direct contributions of code and/or documentation. Error! Bookmark not defined.

+ +

6.5. +OpenAFS for Windows Mailing Lists. Error! Bookmark not defined.

+ +

7. +MSI Deployment Guide. Error! Bookmark not defined.

+ +

7.1. +Introduction. Error! Bookmark not defined.

+ +

7.2. +Configuration Options. Error! Bookmark not defined.

+ +

7.3 +Additional Resources. Error! Bookmark not defined.

+ +

7.4. +Upgrades. Error! Bookmark not defined.

+ +

Appendix +A: Registry Values. Error! Bookmark not defined.

+ +

A.1. +Service parameters. Error! Bookmark not defined.

+ +

A.2. +Integrated Logon Network provider parameters. Error! Bookmark not defined.

+ +

A.2.1 +Domain specific configuration keys for the Network Provider Error! Bookmark not defined.

+ +

A.3. +AFS Credentials System Tray Tool parameters. Error! Bookmark not defined.

+ +

A.4 +OpenAFS Client Service Environment Variables. Error! Bookmark not defined.

+ +

 

+ +
+ + + + diff --git a/src/WINNT/doc/install/Documentation/en_US/html/index.htm b/src/WINNT/doc/install/Documentation/en_US/html/index.htm index d48275eb4..8cb2fb9f4 100755 --- a/src/WINNT/doc/install/Documentation/en_US/html/index.htm +++ b/src/WINNT/doc/install/Documentation/en_US/html/index.htm @@ -1,14 +1,16 @@ - - - - - - - - - IBM AFS for Windows Documentation - - + + + + + + + + + - + + - + + + - - + + + + +
+ +

+ +

OpenAFS for Windows

+ +

Version 1.4.0

-
[IBM AFS for Windows Documentation] -

-IBM AFS for Windows

+

 

-

-Version 3.6

-  +

Welcome to the OpenAFS for Windows online documentation set!

-

Welcome to the AFS for Windows online documentation set! +

The documentation set includes the OpenAFS for Windows Release Notes and the +IBM AFS for Windows 3.6 product notes and installation and configuration +information for the AFS Server, AFS + Control Center, +AFS Client, and AFS Light products. The OpenAFS for Windows online +documentation set also includes the following administrative documentation: the +IBM AFS Administration Reference and the IBM AFS Administration Guide. +

-

 The documentation set includes product notes and installation -and configuration information for the AFS Server, AFS Control Center, AFS -Client, and AFS Light products. The AFS for Windows online documentation -set also includes the following administrative documentation: the IBM -AFS Administration Reference and the IBM AFS Administration Guide. -Note that the administrative documentation is only available online if -you chose the AFS Supplemental Documentation option when you installed -AFS for Windows on your system. +

Although the IBM AFS documentation is out of date, OpenAFS does not have +revised documentation to replace it at the current time.

-

 Note: Documentation is also available directly from the -AFS for Windows CD-ROM, in the CD:\Documentation directory, -where CD is the letter of your -CD-ROM drive. +

Online Documentation:

-

Online Documentation: +

·         +OpenAFS for Windows +Release Notes

-

     IBM AFS for -Windows Quick Beginnings +

·         +IBM AFS for +Windows 3.6 Quick Beginnings

-

     IBM AFS -for Windows Release Notes +

·         +IBM AFS for +Windows 3.6 Release Notes

-

     IBM AFS Administration -Guide +

·         +IBM AFS 3.6 Administration +Guide

-

     IBM AFS Administration -Reference +

·         +IBM AFS 3.6 Administration +Reference

-

  -
PDF: +

 
+
+

-

Documentation in PDF format is not installed with the online documentation. -Access AFS documentation in PDF format directly from the AFS for Windows -CD-ROM. The PDF files are in the CD:\Documentation\language\PDF -directory, where CD is the letter of your CD-ROM drive and language -is the language in which you want to view the documentation, for example, -en_US for English documentation. -
  +

-

© IBM Corporation 2000. All -Rights Reserved.

+ - - + diff --git a/src/WINNT/doc/install/Documentation/en_US/html/index_files/filelist.xml b/src/WINNT/doc/install/Documentation/en_US/html/index_files/filelist.xml new file mode 100644 index 000000000..c3e5db12a --- /dev/null +++ b/src/WINNT/doc/install/Documentation/en_US/html/index_files/filelist.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/src/WINNT/doc/install/Documentation/en_US/html/index_files/image001.jpg b/src/WINNT/doc/install/Documentation/en_US/html/index_files/image001.jpg new file mode 100644 index 000000000..19d79943d Binary files /dev/null and b/src/WINNT/doc/install/Documentation/en_US/html/index_files/image001.jpg differ diff --git a/src/WINNT/doc/install/Documentation/en_US/html/index_files/image002.jpg b/src/WINNT/doc/install/Documentation/en_US/html/index_files/image002.jpg new file mode 100644 index 000000000..cd8ead730 Binary files /dev/null and b/src/WINNT/doc/install/Documentation/en_US/html/index_files/image002.jpg differ