windows-virtual-memory-20041224
[openafs.git] / doc / txt / winnotes / afs-install-notes.txt
index 1ed4d04..bcce7bf 100644 (file)
@@ -1,4 +1,4 @@
-OpenAFS for Windows 1.3.70 Installation Notes
+OpenAFS for Windows 1.3.74 Installation Notes
 ---------------------------------------------
 
 The OpenAFS for Windows product was very poorly maintained throughout the 
@@ -72,24 +72,38 @@ The OpenAFS Client Service now supports a fake "root.afs" volume which is
 dynamically constructed when the service starts.  This mode is called 
 Freelance mode.  Freelance mode is turned on by default.
 
-The contents of the
-fake "root.afs" volume are constructed dynamically as cells are accessed.
-When the fake "root.afs" volume is constructed it will only contain two
-mount points: a read-only and read-write mount point used to access the
-"root.cell" volume of the default AFS cell.  Any attempt to access a 
-valid cell name will automatically result in a new mount point 
+The contents of the fake "root.afs" volume are constructed dynamically as
+cells are accessed.  When the fake "root.afs" volume is constructed it will
+only contain two mount points: a read-only and read-write mount point used
+to access the "root.cell" volume of the default AFS cell.  Any attempt to
+access a valid cell name will automatically 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 read-write; otherwise the mount point will
 be read-only.  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\all\athena.mit.edu root.cell athena.mit.edu
-    fs mkmount \\AFS\all\.athena.mit.edu root.cell athena.mit.edu -rw
-    fs rmmount \\AFS\all\athena.mit.edu
-    fs rmmount \\AFS\all\.athena.mit.edu
+    >fs mkmount \\AFS\all\athena.mit.edu root.cell athena.mit.edu
+    >fs mkmount \\AFS\all\.athena.mit.edu root.cell athena.mit.edu -rw
+    >fs rmmount \\AFS\all\athena.mit.edu
+    >fs rmmount \\AFS\all\.athena.mit.edu
+
+Beginning in 1.3.74, the Freelance fake root.afs volume will support
+the creation of symlinks.
+
+  >symlink make \\afs\all\link \\afs\all\athena.mit.edu\user\j\a\jaltman
+
+  >symlink list \\afs\all\link
+  '\\afs\all\link' is a symlink to 'athena.mit.edu\user\j\a\jaltman'
+
+  >symlink rm \\afs\all\link
+
+The symlinks are stored in the registry at:
+
+  HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks 
      
 
 4. The OpenAFS for Windows client will use AFSDB DNS records to 
@@ -97,7 +111,7 @@ discover cell information when it is not located in the local CellServDB file
 (\Program Files\OpenAFS\Client\CellServDB).
 
 
-5. OpenAFS for Windows 1.3.70 only supports Windows 2000, Windows XP, and 
+5. OpenAFS for Windows 1.3.72 only supports Windows 2000, Windows XP, and 
 Windows 2003.  Windows NT 4.0 and the entire Windows 9x/Me line are no
 longer supported.  Older releases of OpenAFS are available for download
 if those operating systems must be supported.  The last version with support
@@ -167,10 +181,12 @@ after install time although these options may be altered via the registry either
 per machine or per user.  See AfscredsShortcutParams in registry.txt.
 
 
-8. Some attempts have been made to restrict the ability  
-of users to alter the state of the AFS Client 
-Service.  For example, the following fs.exe commands are now restricted to 
-Administrator:
+8. As of 1.3.71, the OpenAFS for Windows client supports a local Windows
+authorization group called "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 either afs_config.exe
+or fs.exe.  For example, the following fs.exe commands are now restricted 
+to members of the "AFS Client Admin" group:
 
     - checkservers with a non-zero timer value
     - setcachesize
@@ -184,11 +200,13 @@ Administrator:
     - cscpolicy
     - trace
 
-setting the default sysname for a machine should be done via the registry and 
+Setting the default sysname for a machine should be done via the registry and 
 not via "fs sysname".
 
-Some of the AFS Client Configuration Control Panel options are also restricted 
-to use by the "Administrator" account.
+The local "SYSTEM" account is always a member of the "AFS Client Admin" group.
+
+The initial membership of the "AFS Client Admin" group when created by the 
+installer is equivalent to the local "Administrators" group.
 
 
 9. The AFS Client should support UNC paths everywhere.  Power users that make
@@ -216,9 +234,9 @@ Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
    No commandline arguments means authenticate to the local cell.
 
 
-11. The AFS Server functionality provided with OpenAFS 1.3.70 might work but 
+11. The AFS Server functionality provided with OpenAFS 1.3.72 might work but 
 should be considered highly experimental.  It has not been thoroughly tested.
-Any data which would cause pain if lost should be stored in an OpenAFS 
+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 
@@ -243,29 +261,21 @@ statements were compiled into the binaries.
 13. OpenAFS for Windows does not support files larger than 2GB.  
 
 
-14. There are reported problems running the AFS Client on Hyperthreaded 
-Pentium 4 machines.  A registry entry may be created to specify
-that the AFS Client Service should only use a single processor.  If you have
-a hyperthreaded system and you are experiencing crashes, it is advised that
-you create the "MaxCPUs" registry value and set it to "1".
-See "registry.txt" for details. 
-
-
-15. Local RPC is used as the default RPC mechanism for setting 
+14. Local RPC is used as the default RPC mechanism for setting 
 tokens.  TCP RPC is required to be installed and is used for debugging 
 and other functions.
 
 
-16. OpenAFS for Windows automatically open ports in the Windows 
+15. OpenAFS for Windows automatically open ports in the Windows 
 Internet Connection Firewall.
 
 
-17. The OpenAFS for Windows installer by default activates a weak form of 
+16. 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.
 
 
-18. OpenAFS 1.3.70 adds support for authenticated SMB connections using 
+17. OpenAFS 1.3.71 adds support for authenticated SMB connections using 
 either NTLM or GSS SPNEGO (NTLM, Kerberos 5, ...).  In previous versions
 of OpenAFS the SMB connections were unauthenticated which left open the
 door for several security holes which could be used to obtain access to
@@ -288,7 +298,7 @@ add these service principals to the list of principals to be maintained
 for each host.
 
 
-19. As of 1.3.70, INI files are no longer used for the storage of AFS 
+18. As of 1.3.70, INI files are no longer used for the storage of AFS 
 configuration data.  No longer are there any AFS related files stored in the
 %WINDIR% directory.  The CellServDB file is no longer called "afsdsbmt.ini"
 and it is stored in the OpenAFS\Client directory.  The afs_freelance.ini
@@ -299,7 +309,7 @@ data will be automatically migrated; there is no mechanism for automatic
 migration of Submounts, Drive Mappings, Active Maps, and CSCPolicy data.
 
 
-20. As of 1.3.70, the OpenAFS Client is compatible with Windows XP SP2
+19. As of 1.3.70, the OpenAFS Client is compatible 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 
@@ -307,41 +317,165 @@ entries are added to the registry to allow SMB authentication to be
 performed across the loopback connection.
 
 
-21. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote
+20. As of 1.3.70, the OpenAFS Client Service supports the CIFS Remote
 Admin Protocol which provides browsing of server and share information.
 This significantly enhances the interoperability of AFS volumes within the
 Explorer Shell and Microsoft Office applications.
 
 
-22. OpenAFS will now automatically forget a user's tokens upon Logoff
+21. OpenAFS will now 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.
-
-Note: This functionality has been disabled in the 1.3.70 installers due
-to problems discovered with the final release build of XP SP2.  To enable
-this functionality on other versions of Windows the following registry 
-entries should be added:
-
-  REG_DWORD HKLM "Software\Microsoft\Windows NT\CurrentVersion\WinLogon\Notify\AfsLogon" "Asynchronous" 0
-  REG_DWORD HKLM "Software\Microsoft\Windows NT\CurrentVersion\WinLogon\Notify\AfsLogon" "Impersonate"  1
-  REG_SZ    HKLM "Software\Microsoft\Windows NT\CurrentVersion\WinLogon\Notify\AfsLogon" "DLLName" "afslogon.dll"
-  REG_SZ    HKLM "Software\Microsoft\Windows NT\CurrentVersion\WinLogon\Notify\AfsLogon" "Logoff" "AFS_Logoff_Event"
-  REG_SZ    HKLM "Software\Microsoft\Windows NT\CurrentVersion\WinLogon\Notify\AfsLogon" "Startup" "AFS_Startup_Event"
-
+tokens.  Whether or not the profile has been loaded from the registry can
+be determined for Local Accounts, Active Directory accounts and NT4 
+accounts.
+                                                   
 
-23. Terminal Server installations.
+22. Terminal Server installations.
 When installing under Terminal Server, you must execute the NSIS installer
 (.exe) 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.
 
-24. AFS is a Unix native file system.  As such the OpenAFS client attempts
+
+23. AFS is a Unix native file system.  As such 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.
 
+
+24. 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 ACLs are not the principal names from
+the Kerberos 5 ticket.  To support this transition, OpenAFS for Windows
+in 1.3.72 adds a new registry value 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.
+
+
+25. The Status Cache (AFS Config 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 you might want to increase the 
+maximum number of Status Cache entries.  Each entry requires 164K.  Only
+those entries which are used are allocated.
+
+
+26. "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.
+
+
+27. The AFS Client Service and related binaries are digitally signed by
+"Secure Endpoints Inc." beginning with the 1.3.7400 release of OpenAFS
+for Windows.  Starting in the 1.3.7500 release, the AFS Client Service
+will perform a run-time verification check to ensure that all AFS 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 then one version of AFS being installed
+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.  
+
+The registry.txt file documents the "VerifyServiceSignature" registry
+value which can be used to disable the signature check.  The file version
+check cannot be disabled.
+
+
+28. 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 the memory mapped file.  Due to fragmentation of the process 
+spaced caused 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.
+
+
+29. OpenAFS for Windows implements an SMB server which is used as a
+gateway to the AFS filesystem.  Because of the use of SMB, Windows 
+stores all files into AFS using the 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 a 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
+
+As of 1.3.75, a new registry value, HKLM\SOFTWARE\OpenAFS\Client 
+"StoreAnsiFilenames" can be set to instruct OpenAFS for Windows 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.
+
+
+30. 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.
+
+
 ------------------------------------------------------------------------
 
 Reporting Bugs: