Windows Release Notes XML
[openafs.git] / doc / xml / ReleaseNotesWindows / relnotes.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
3         "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY version SYSTEM "version.xml">
5 ]>
6
7 <book>
8   <bookinfo>
9     <title>OpenAFS for Windows Release Notes</title>
10     <copyright>
11       <year>2003-2009</year>
12       <holder>Secure Endpoints Inc.</holder>
13     </copyright>
14     <legalnotice>
15       <para>This documentation is covered by the MIT License.</para>
16     </legalnotice>
17     <revhistory>
18         &version;
19     </revhistory>
20     <abstract>
21       <para>This document provides a series of usage notes regarding the OpenAFS for Windows
22       client, supported platforms, contribution information, debugging techniques, and
23       a reference to supported Windows registry values.
24      </para>
25     </abstract>
26   </bookinfo>
27   <preface>
28     <title id='Preface'>Preface</title>
29
30     <para>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.  </para>
31     <para>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.  </para>
32     <para>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
33       <emphasis>releasing</emphasis> the current contents of the source volume.
34
35
36
37     </para>
38     <para>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.</para>
39     <para>OpenAFS is the product of an open source development effort begun on October 31 2000.  OpenAFS is maintained and developed by a group of volunteers with the support of the user community.   If you use OpenAFS as part of your computing infrastructure please contribute to its continued growth.
40   </para>
41   </preface>
42   <chapter id='chap_1'>
43     <title id='Installer_Options'>Installer Options</title>
44     <para>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:</para>
45     <para>
46       <orderedlist>
47         <listitem>
48    an executable (.exe) that is built using the Nullsoft Scriptable Installation System, or</listitem>
49         <listitem>
50   a Windows Installer package (.msi) that is built using WiX and can be customized for organizations via the use of MSI Transforms (see
51           <link linkend='MSI_Deployment_Guide'>MSI Deployment Guide</link>)
52
53         </listitem>
54       </orderedlist>
55     </para>
56   </chapter>
57   <chapter id='chap_2'>
58     <title id='System_Requirements'>System Requirements</title>
59     <section>
60       <title id='Supported_Operating_Systems'>2.1 Supported Operating Systems</title>
61       <itemizedlist>
62         <listitem>
63           <para>Microsoft Windows 2000 Workstation</para>
64         </listitem>
65         <listitem>
66           <para>Microsoft Windows 2000 Server </para>
67         </listitem>
68         <listitem>
69           <para>Microsoft Windows XP Home</para>
70         </listitem>
71         <listitem>
72           <para>Microsoft Windows XP Professional</para>
73         </listitem>
74         <listitem>
75           <para>Microsoft Windows XP 64</para>
76         </listitem>
77         <listitem>
78           <para>Microsoft Windows 2003 Server (32-bit and 64-bit Intel)</para>
79         </listitem>
80         <listitem>
81           <para>Microsoft Windows 2003 R2 Server (32-bit and 64-bit Intel)</para>
82         </listitem>
83         <listitem>
84           <para>Microsoft Windows Vista (32-bit and 64-bit Intel)</para>
85         </listitem>
86         <listitem>
87           <para>Microsoft Windows 2008 Server (32-bit and 64-bit Intel)</para>
88         </listitem>
89         <listitem>
90           <para>Microsoft Windows 7 RC (32-bit and 64-bit Intel)</para>
91         </listitem>
92         <listitem>
93           <para>Microsoft Windows 2008 Server R2 RC (32-bit and 64-bit Intel)</para>
94         </listitem>
95       </itemizedlist>
96     </section>
97     <section>
98       <title id='Unsupported_Operating_Systems'>2.1.1 Unsupported Operating Systems</title>
99       <itemizedlist>
100         <listitem>
101           <para> Microsoft Windows 95</para>
102         </listitem>
103         <listitem>
104           <para>Microsoft Windows 98</para>
105         </listitem>
106         <listitem>
107           <para>Microsoft Windows 98 OSR2</para>
108         </listitem>
109         <listitem>
110           <para>Microsoft Windows ME</para>
111         </listitem>
112         <listitem>
113           <para>Microsoft NT</para>
114         </listitem>
115       </itemizedlist>
116       <para>Older releases of OpenAFS are available for download if unsupported operating systems must be used.  The last version of OpenAFS with support for Win9x is 1.2.2b.  The last version with support for Windows NT 4.0 is 1.2.10.</para>
117     </section>
118     <section>
119       <title id='Disk_Space'>2.2 Disk Space</title>
120       <para>Up to 60mb required for the OpenAFS binaries plus 100MB for the default AFSCache file.   The size of the AFSCache file may be adjusted via the Registry after installation.  The maximum cache size for 32-bit Windows is approximately 1.2GB.  On 64-bit Windows there is no practical limit on the cache size.</para>
121     </section>
122     <section>
123       <title id='Additional_Software_Packages'>2.3 Additional Software Packages</title>
124       <para>
125         <ulink url='http://web.mit.edu/kerberos/dist/index.html'>MIT Kerberos for Windows</ulink> 2.6.x or 3.x.x if Kerberos v5 authentication support is desired.  The recommended release is version 3.2.2.  For 64-bit Windows installations, the 64-bit version of Kerberos for Windows is required.  For 32-bit Windows installations, the 32-bit version of Kerberos for Windows is required.
126
127
128
129       </para>
130     </section>
131   </chapter>
132   <chapter id='chap_3'>
133     <title id='Operational_Notes'>Operational Notes</title>
134     <section>
135       <title id='Unicode_Support'>3.1. Unicode Support</title>
136       <para>Starting with the 1.5.50 release of OpenAFS for Windows, each of the AFS Client Service, the AFS Explorer Shell Extension, and the command-line tools are Unicode enabled.  No longer is OpenAFS restricted to accessing file system objects whose names can be represented in the locale specific OEM code page.  This has significant benefits for end users.  Most importantly it permits non-Western languages to now be used for file system object names in AFS from Microsoft Windows operating systems.  Now that Unicode names are supported,
137         <ulink url='http://en.wikipedia.org/wiki/Roaming_user_profile'>Roaming User Profiles</ulink> and
138         <ulink url='http://en.wikipedia.org/wiki/Folder_redirection'>Folder Redirection</ulink> will no longer fail when a user attempts to store an object with a name that cannot be represented in the OEM code page.
139
140
141
142       </para>
143       <para>Unicode names are stored in AFS using UTF-8 encoding.  UTF-8 is supported as a locale on MacOS X, Linux, Solaris, and most other operating systems.  This permits non-Western object names to be exchanged between Microsoft Windows and other operating systems.  The OpenAFS for Windows client also implements
144         <ulink url='http://en.wikipedia.org/wiki/Unicode_normalization'>Unicode Normalization</ulink> as part of the name lookup algorithm.  This is necessary because Unicode does not provide a unique representation for each input string.  The use of normalization permits a file system object name created on MacOS X to be matched with the same string entered on Microsoft Windows even though the operating system’s choice of representation may be different.
145
146
147
148       </para>
149       <para>It is important to note that AFS file servers are not character set agnostic.  All file system object names are stored as octet strings without any character set tagging.  If a file system object is created using OEM Code Page 858 and then interpreted as UTF-8 it is likely that the object name will appear to be gibberish.  OpenAFS for Windows goes to great lengths to ensure that the object name is converted to a form that will permit the user to rename the object using Unicode.  Accessing UTF-8 names on UNIX systems that have the locale set to one of the ISO Latin character sets will result in the UTF-8 strings appearing to be gibberish.  </para>
150       <para>Neither UNIX AFS nor Microsoft Windows 2000 systems can perform Unicode Normalization for string comparisons.  Although it is possible to store and read Unicode object names, it is possible that a user may not be able to open an object by typing the name of the object at the keyboard.  GUI point and click operations should permit any object to be accessed.</para>
151     </section>
152     <section>
153       <title id='Kerberos_v5_Requirements'>3.2. Requirements for Kerberos v5 Authentication</title>
154       <para>The Kerberos v4 infrastructure on which the OpenAFS 1.2 series is reliant is no longer secure.  Cross-realm Kerberos is very important in the AFS context and most sites have or are migrating to Kerberos v5 environments.  The OpenAFS 1.4 series (and later) integrates with
155         <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink> 2.6.5 and above to support Kerberos v5 authentication including automatic renewal of AFS tokens and single sign-on via the Microsoft Windows Kerberos Logon Service.
156
157
158
159       </para>
160       <para>The recommended version of
161         <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink> is 3.2.2.  KFW 3.2.2 includes Network Identity Manager 1.3.1 which integrates with the
162         <link linkend='Network_Identity_Manager_Provider'>AFS Provider</link> installed as part of OpenAFS for Windows.
163
164
165
166       </para>
167       <para>When KFW is installed, the OpenAFS for Windows client will obtain Kerberos v5 tickets and use them as tokens without modification.  The OpenAFS client requires that all of the AFS Servers with which it communicates support the use of Kerberos v5 tickets as tokens. If Kerberos v5 based tokens are presented to an AFS server that does not support them, the server will be unable to communicate with the client when tokens are present. Kerberos v5 based tokens are supported by OpenAFS release 1.2.8 or later.  IBM Transarc servers do not support Kerberos v5.</para>
168       <section>
169         <title id='Active_Directory'>3.2.1. Active Directory</title>
170         <para>Microsoft Windows Active Directory can be used as a Kerberos v5 KDC in conjunction with OpenAFS.  There are two things to consider when using an Active Directory as the Kerberos realm that issues the AFS service ticket.  First, the Kerberos v5 tickets issued by Active Directory can be quite large when compared to tickets issued by a traditional KDC due to the incorporation of authorization data (the Microsoft PAC).  If the issued tickets are larger than 344 bytes, the OpenAFS 1.2 servers will be unable to process them and will issue a RXKADBADTICKET error.  OpenAFS 1.4 (and beyond) servers can support the largest tickets that Active Directory can issue.  Second, the Kerberos v5 tickets issued by Windows 2003 Active Directory are encrypted with the DES-CBC-MD5 encryption type (enctype).  OpenAFS 1.2 servers only support the DES-CBC-CRC enctype.  As a result, OpenAFS 1.2 servers cannot process the resulting Kerberos v5 tokens.  Windows 2000 Active Directory issues tickets with the DES-CBC-CRC enctype.</para>
171         <para>Microsoft has documented in
172           <ulink url='http://support.microsoft.com/kb/832572/'>Knowledge Base article 832572</ulink> a new NO_AUTH_REQUIRED flag that can be set on the account mapped to the AFS service principal.  When this flag is set, the PAC authorization data will not be included in the ticket.  Setting this flag is recommended for all accounts that are associated with non-Windows services and that do not understand the authorization data stored in the PAC.  This flag cannot be used if AFS service tickets are obtained via cross-realm using an Active Directory user principal.
173
174
175
176         </para>
177         <para>Note that an Active Directory computer object cannot be used for the afs service principal.</para>
178       </section>
179       <section>
180         <title id='Using_krb524_Service'>3.2.2. Using the krb524 Service</title>
181         <para>Some organizations have AFS cell names and Kerberos realm names which differ by more then just lower and upper case and rely on a modification to krb524d which maps a Kerberos v5 ticket from realm FOO to a Kerberos v4 ticket in realm BAR.  This allows user@FOO to appear to be user@bar for the purposes of accessing the AFS cell.  As of OpenAFS 1.2.8, support was added to allow the immediate use of Kerberos v5 tickets as AFS (2b) tokens. This is the first building block necessary to break away from the limitations of Kerberos v4 with AFS.  By using Kerberos v5 directly we avoid the security holes inherent in Kerberos v4 cross-realm.  We also gain access to cryptographically stronger algorithms for authentication and encryption. </para>
182         <para>Another reason for using Kerberos v5 directly is because the krb524 service runs on a port (4444/udp) which has increasingly been blocked by ISPs.  The port was used to spread a worm which attacked Microsoft Windows in the summer of 2003.  When the port is blocked users find that they are unable to authenticate.</para>
183         <para>Replacing the Kerberos v4 ticket with a Kerberos v5 ticket is a win in all situations except when the cell name does not match the realm name and the principal names placed into the ACL’s are not the principal names from the Kerberos v5 ticket.  To support this transition, OpenAFS for Windows 1.4 adds a new registry value,
184           <link linkend='Value_Use524'>Use524</link>, 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.
185
186
187
188         </para>
189         <para>Note that the OpenAFS 1.4.x servers permit the use of a secondary realm name that can be treated as equivalent to the cell name for authentication.
190         </para>
191       </section>
192       <section>
193         <title id='Network_Identity_Manager_Provider'>3.2.3. Network Identity Manager Provider</title>
194         <para>As of release 1.5.9, OpenAFS for Windows includes a Network Identity Manager Provider for obtaining AFS tokens.  This plug-in is a contribution from
195           <ulink url='https://www.secure-endpoints.com/'>Secure Endpoints Inc.</ulink>  Network Identity Manager is a multiple identity credential management tool that ships with
196           <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink> version 3.0 and above.  The OpenAFS plug-in requires
197           <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink> version 3.1 or above.  Version 3.2.2 is recommended for the best user experience.
198
199
200
201         </para>
202         <para>
203           <inlinemediaobject>
204             <imageobject>
205               <imagedata format='JPG' fileref='relnotes00.jpg' />
206             </imageobject>
207           </inlinemediaobject>
208         </para>
209         <para>The Network Identity Manager replaces the former KFW ticket manager, Leash&quot;, and when combined with the OpenAFS Provider, it is intended to be used as a replacement for the AFS System Tray Tool (afscreds.exe).  Unlike both Leash and the AFS System Tray Tool, Network Identity Manager with the OpenAFS Provider can easily manage AFS tokens for multiple cells from one or more Kerberos v5 identities.</para>
210         <para>
211           <inlinemediaobject>
212             <imageobject>
213               <imagedata format='JPG' fileref='relnotes01.jpg' />
214             </imageobject>
215           </inlinemediaobject>
216         </para>
217         <para>The AFS configuration panel for each Kerberos v5 identity is used to configure which cells credentials should be obtained for and how they should be obtained.  If the cell to realm mapping cannot be automatically determined, it can be explicitly specified.  If the cell does not support Kerberos v5 tickets as tokens, then a krb524 service can be configured.</para>
218         <para>
219           <inlinemediaobject>
220             <imageobject>
221               <imagedata format='JPG' fileref='relnotes02.jpg' />
222             </imageobject>
223           </inlinemediaobject>
224         </para>
225         <para>The OpenAFS Provider configuration panel can be used to check the status of the AFS Client Service and its version.  An optional checkbox is provided that will prevent the AFS System Tray Tool from being started by Windows after login.   A shortcut to the OpenAFS Control Panel is also provided.</para>
226       </section>
227     </section>
228     <section>
229       <title id='Use_of_Microsoft_Loopback'>3.3. Use of the Microsoft Loopback Adapter by the AFS Client Service</title>
230       <para>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.  </para>
231       <para>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 &quot;Client for Microsoft Networks&quot; service and not bound to the &quot;File and Printer Sharing for Microsoft Networks&quot;.  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:</para>
232       <itemizedlist>
233         <listitem>
234           <para>stop the AFS Client Service</para>
235         </listitem>
236         <listitem>
237           <para>bind the "Client for Microsoft Networks" to the MLA</para>
238         </listitem>
239         <listitem>
240           <para>unbind "File and Printer Sharing for Microsoft Networks" from the MLA</para>
241         </listitem>
242         <listitem>
243           <para>Disable and then re-enable the MLA</para>
244         </listitem>
245         <listitem>
246           <para>start the AFS Client Service</para>
247         </listitem>
248       </itemizedlist>
249       <para>When the MLA is not installed the unique NETBIOS name published by OpenAFS SMB server is "
250         <emphasis>MACHINE</emphasis>-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.
251       </para>
252     </section>
253     <section>
254       <title id='Using_Freelance_Mode'>3.4. Using Freelance (Dynamic Root) Mode to Improve Mobility</title>
255       <para>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. </para>
256       <para>To allow the OpenAFS Client Service to operate in these environments, Freelance mode dynamically constructs a fake "root.afs" volume from mount points and symlinks stored in the local registry.</para>
257       <para>The content of the fake &quot;root.afs&quot; volume is dynamically generated as cells are accessed.  When the fake "root.afs" volume is initially constructed it will only contain two mount points: a
258         <emphasis>regular path </emphasis>and
259         <emphasis>read-write path </emphasis>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
260         <emphasis>read-write path</emphasis>; otherwise the mount point will be a
261         <emphasis>regular path</emphasis>.  These mount points are preserved in the registry at key:
262
263
264
265       </para>
266       <para>
267         <link linkend='Regkey_HKLM_SOFTWARE_OpenAFS_Client_Freelance'>HKLM\SOFTWARE\OpenAFS\Client\Freelance</link>
268       </para>
269       <para>Additional mount points may be manually created using the "fs mkmount" command.  Mount points may be removed using the "fs rmmount" command.</para>
270       <para>&gt;fs mkmount \\AFS\athena.mit.edu root.cell athena.mit.edu</para>
271       <para>&gt;fs mkmount \\AFS\.athena.mit.edu root.cell athena.mit.edu -rw</para>
272       <para>&gt;fs rmmount \\AFS\athena.mit.edu</para>
273       <para>&gt;fs rmmount \\AFS\.athena.mit.edu</para>
274       <para>Symlinks may also be created within the Freelance &quot;root.afs&quot; volume.</para>
275       <para>&gt;symlink make \\afs\link \\afs\athena.mit.edu\user\j\a\jaltman</para>
276       <para>      &gt;symlink list \\afs\link</para>
277       <para>      '\\afs\link' is a symlink to 'athena.mit.edu\user\j\a\jaltman'</para>
278       <para>&gt;symlink rm \\afs\link</para>
279       <para>The symlinks are stored in the registry at:</para>
280       <para>
281         <link linkend='Regkey_HKLM_SOFTWARE_OpenAFS_Client_Freelance_Symlinks'>HKLM\SOFTWARE\OpenAFS\Client\Freelance\Symlinks</link> 
282       </para>
283     </section>
284     <section>
285       <title id='Locating_VLDB_via_DNS'>3.5. Locating AFS Volume Database Servers via DNS </title>
286       <para>The OpenAFS for Windows client will use DNS AFSDB records to discover the location of AFS Volume Database servers when entries for the cell are not present in the client's CellServDB file (\%PROGRAMFILES%\OpenAFS\Client\CellServDB).
287       Also see <link linkend="Registry_VLDB_Configuration">Registry Configuration for AFS Volume Database Servers</link>.</para>
288     </section>
289     <section>
290       <title id='Integrated_Logon'>3.6. Obtaining AFS Tokens as a Integrated Part of Windows Logon</title>
291       <para>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 &quot;ATHENA.MIT.EDU&quot; is obtained by performing a domain name to realm mapping on the hostname of one of the cell's Volume Database servers.</para>
292       <para>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.</para>
293       <para>When KFW is configured, Integrated Logon will use it to obtain tokens. Use of KFW for Integrated Logon can be disabled via the
294         <link linkend='EnableKFW'>EnableKFW</link> registry value.  Use of the krb524 service can be configured via the
295         <link linkend='Value_Use524'>Use524</link> registry value.
296       </para>
297       <para>Integrated Logon will not transfer Kerberos v5 tickets into the user’s logon session credential cache. KFW 3.1 and above provides that functionality on its own.</para>
298       <para>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.</para>
299       <para>Integrated Logon supports the ability to obtain tokens for multiple cells.  For further information on how to configure this feature read about the
300         <link linkend='Value_TheseCells'>TheseCells</link> value.
301       </para>
302     </section>
303     <section>
304       <title id='AFS_System_Tray'>3.7. AFS System Tray Command Line Options</title>
305       <para>The AFS System Tray Tool (afscreds.exe) has been deprecated in favor of Network Identity Manager.  afscreds.exe will be removed from the OpenAFS in a future release.</para>
306       <para>The AFS System Tray tool (afscreds.exe) supports several command line options: </para>
307       <itemizedlist>
308         <listitem>
309           <para>-A = autoinit </para>
310         </listitem>
311         <listitem>
312           <para>-E = force existing afscreds to exit</para>
313         </listitem>
314         <listitem>
315           <para>-I = install startup shortcut</para>
316         </listitem>
317         <listitem>
318           <para>-M = renew drive maps </para>
319         </listitem>
320         <listitem>
321           <para>-N = IP address change detection </para>
322         </listitem>
323         <listitem>
324           <para>-Q = quiet mode.  do not display start service dialog if afsd_service is not already running</para>
325         </listitem>
326         <listitem>
327           <para>-S = show tokens dialog on startup</para>
328         </listitem>
329         <listitem>
330           <para>-U = uninstall startup shortcut</para>
331         </listitem>
332         <listitem>
333           <para>-X = test and do map share</para>
334         </listitem>
335         <listitem>
336           <para> -Z = unmap drives</para>
337         </listitem>
338       </itemizedlist>
339       <para>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.</para>
340       <para>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.</para>
341       <para>By default afscreds.exe is configured by the OpenAFS.org installers to use &quot;-A -N -M -Q&quot; 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
342         <link linkend='Value_AfscredsShortcutParams'>AfscredsShortcutParams</link> in
343         <link linkend='appendix_a'>Appendix A</link>.
344       </para>
345     </section>
346     <section>
347       <title id='AFS_Client_Admin_Group'>3.8. The &quot;AFS Client Admins&quot; Authorization Group</title>
348       <para>The OpenAFS for Windows client supports a local Windows authorization group named "AFS Client Admins".  This group is used in place of the "Administrators" group to determine which users are allowed to modify the AFS Client Service configuration via the AFS Control Panel (afs_config.exe) or fs.exe command line tool.  The following fs.exe commands are now restricted to members of the "AFS Client Admins" group:</para>
349       <itemizedlist>
350         <listitem>
351           <para>checkservers with a non-zero timer value</para>
352         </listitem>
353         <listitem>
354           <para>setcachesize</para>
355         </listitem>
356         <listitem>
357           <para>newcell</para>
358         </listitem>
359         <listitem>
360           <para>sysname with a new sysname list</para>
361         </listitem>
362         <listitem>
363           <para>exportafs</para>
364         </listitem>
365         <listitem>
366           <para>setcell</para>
367         </listitem>
368         <listitem>
369           <para>setserverprefs</para>
370         </listitem>
371         <listitem>
372           <para>storebehind</para>
373         </listitem>
374         <listitem>
375           <para>setcrypt</para>
376         </listitem>
377         <listitem>
378           <para>cscpolicy</para>
379         </listitem>
380         <listitem>
381           <para>trace</para>
382         </listitem>
383         <listitem>
384           <para>minidump</para>
385         </listitem>
386       </itemizedlist>
387       <para>The creation or removal of mount points and symlinks in the Freelance &quot;root.afs&quot; volume are also restricted to members of the &quot;AFS Client Admins&quot; group.</para>
388       <para>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.</para>
389       <para>Setting the default sysname for a machine should be done via the
390         <link linkend='Value_SysName'>SysName registry value</link> and not via "fs sysname".
391       </para>
392     </section>
393     <section>
394       <title id='Support_for_UNC_Paths'>3.9. OpenAFS Support for UNC Paths </title>
395       <para>The OpenAFS client supports UNC paths everywhere.  UNC paths provide a canonical name for resources stored within AFS.  UNC paths should be used instead of drive letter mappings whenever possible.   This is especially true when specifying the location of roaming profiles and redirected folders.  </para>
396       <para>Power users that make extensive use of the command line shell, cmd.exe, should consider using JP Software's 4NT or Take Command command processors.  Unlike cmd.exe, the JPSoftware shells fully support UNC paths as the current directory.  JPSoftware added special recognition for OpenAFS to its command shells, 4NT 7.0 and Take Command 7.0.  AFS paths can be entered in UNIX notation (e.g., /afs/openafs.org/software), space utilization reports the output of the volume status for the specified path, and many AFS specific functions and variables have been added to the command language.</para>
397       <para>JPSoftware's web site is
398         <ulink url='http://www.jpsoft.com/'>http://www.jpsoft.com</ulink>.
399       </para>
400       <para>Microsoft PowerShell 1.0 and 2.0 will also support UNC paths as the current directory. </para>
401     </section>
402     <section>
403       <title id='aklog.exe'>3.10. aklog.exe</title>
404       <para>The OpenAFS Client ships with its own version of aklog.exe which should be used in preference to those obtained by other sources.  The OpenAFS aklog.exe supports Kerberos v5 as well as the ability to auto-generate AFS IDs within foreign PTS databases.</para>
405       <para>
406         <programlisting>
407     Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]]
408                  [[-p | -path] pathname]
409                  [-noprdb] [-force]
410                  [-5 [-m]| -4]
411
412                  -d = output debugging information.
413                  cell = zero or more cells for which tokens will be obtained
414                  krb_realm = the kerberos realm of the cell.
415                  pathname = the directory for which authentication is required
416                  -noprdb = don't try to determine AFS ID.
417                  -5 or -4 = use Kerberos V (default) or Kerberos IV tickets
418                  -m = use krb524d to convert Kerberos V tickets to Kerberos IV
419       </programlisting>
420       </para>
421     </section>
422     <section>
423       <title id='OpenAFS_Servers_on_Windows'>3.11. OpenAFS Servers on Windows are Unsupported</title>
424       <para>The AFS Server functionality provided as part of the OpenAFS install package might work but should be considered highly experimental.  It has not been thoroughly tested.  Any data which would cause pain if lost should not be stored in an OpenAFS Server on Windows.</para>
425       <para>Known issues include lack of support for power management and dynamic network configuration.  Salvager is also known to crash.</para>
426       <section>
427         <title id='OpenAFS_Server_Installation'>3.11.1. OpenAFS Server Installation</title>
428         <para>When the OpenAFS Server is installed, the TransarcAFSServer service (bosctlsvc.exe) will be installed and configured.  The TransarcAFSServer service will auto-start the traditional AFS bos server.  The former AFS Server Configuration wizard makes assumptions that no longer hold true and it has therefore been disabled.  However, following the instructions for installing the AFS Servers on UNIX it is possible to properly configure the AFS Servers on Microsoft Windows.  The AFS Server binaries, configuration files, and log files are installed under %Program Files%\OpenAFS\Server.
429           <ulink url='http://www.openafs.org/no-more-des.html'>kaserver has been deprecated and its use is strongly discouraged.</ulink>  Instead, Active Directory or some other Kerberos v5 KDC should be used in its place.
430         </para>
431       </section>
432       <section>
433         <title id='Using_the_AFS_Client_Service_with_OpenAFS_Server'>3.11.2. Using the AFS Client Service when the Server is installed</title>
434         <para>A few notes on the usage of the AFS Client Service if it is going to be used with the OpenAFS AFS Server:</para>
435         <itemizedlist>
436           <listitem>
437             <para>Freelance mode should be disabled when the AFS Client Service is installed on the same machine as the AFS Server,.  Otherwise, you will be unable to manipulate the contents of the root.afs volume for the hosted cell without constructing an explicit mountpoint to the root.afs volume from another volume.</para>
438           </listitem>
439           <listitem>
440             <para>The AFS Server and related tools only support the built in kaserver (Kerberos IV).  If kaserver is being used,
441               <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink> should not be installed or must be disabled via the
442               <link linkend='EnableKFW'>EnableKFW</link> registry value.
443             </para>
444           </listitem>
445           <listitem>
446             <para>The AFS Servers are not aware of power management events nor are they aware of network configuration changes.  It is strongly advised that the AFS servers be installed only on systems that will not be shutdown or suspended unexpectedly.   An inadvertent shutdown will corrupt volume data.</para>
447           </listitem>
448         </itemizedlist>
449       </section>
450     </section>
451     <section>
452       <title id='OpenAFS_Debug_Symbols'>3.12. OpenAFS Debugging Symbol files</title>
453       <para>The OpenAFS for Windows installers include Debugging Symbol files which should be installed if you are experiencing problems and need to send crash reports.  This is true for both the release and the debug versions of the installers.  The difference between the release and debug versions are:</para>
454       <itemizedlist>
455         <listitem>
456           <para>whether or not the binaries were compiled with optimization (release: yes, debug: no)</para>
457         </listitem>
458         <listitem>
459           <para>whether or not the debug symbols are installed by default (release: no, debug: yes)</para>
460         </listitem>
461         <listitem>
462           <para>whether or not
463             <emphasis>fs trace</emphasis> logging is turned on by default (release: no, debug: yes)
464
465
466
467           </para>
468         </listitem>
469         <listitem>
470           <para>whether or not additional debug statements were compiled into the binaries (release: no, debug: yes)</para>
471         </listitem>
472       </itemizedlist>
473     </section>
474     <section>
475       <title id='Large_File_Support'>3.13. Large File (64-bit) Support</title>
476       <para>As of release 1.5.3, OpenAFS for Windows supports files larger than 2GB.  The maximum file size is now 16777216 terabytes when the AFS File Server supports large files.   If the AFS File Server does not support 64-bit file sizes, then the maximum file size remains 2GB.</para>
477     </section>
478     <section>
479       <title id='Encrypted_AFS_Network_Communication'>3.14. Encrypted AFS Network Communication</title>
480       <para>The OpenAFS for Windows installer by default activates a weak form of encrypted data transfer between the AFS client and the AFS servers.  This is often referred to as "fcrypt" mode.  Encrypted data transfer can be turned on or off with the &quot;fs crypt&quot; command.  Transitions between &quot;crypt&quot; and &quot;non-crypt&quot; modes are logged to the Windows Application Event Log. </para>
481     </section>
482     <section>
483       <title id='Authenticated_SMB_Access_to_Client_Service'>3.15. Authenticated SMB Access to the OpenAFS Client Service</title>
484       <para>OpenAFS authenticates SMB connections using either NTLM or GSS SPNEGO (NTLM).  In previous versions of OpenAFS, the SMB connections were unauthenticated which opened the door for several attacks which could be used to obtain access to another user's tokens on shared machines.    </para>
485       <para>When GSS SPNEGO attempts a Kerberos v5 authentication, the Windows SMB client will attempt to retrieve service tickets for "cifs/afs@REALM" (if the loopback adapter is in use) or "cifs/machine-afs@REALM" (if the loopback adapter is not being used).  It is extremely important that this service principal not exist in the KDC database as the Kerberos authentication must fail allowing automatic fallback to NTLM.  When NTLM is used a special local authentication mode will be used that does not require access to the user's password.  Instead, Windows will internally recognize the request as coming from a local logon session.</para>
486     </section>
487     <section>
488       <title id='No_More_INI_Files'>3.16. INI Files Replaced By Windows Registry</title>
489       <para>IBM AFS and OpenAFS 1.2 Windows clients stored configuration data in Windows .INI files.   This OpenAFS client does not use Windows .INI files for the storage of configuration data.   All settings are stored in the registry (see
490         <link linkend='appendix_a'>Appendix A</link>).  The CellServDB file is now stored in either the %ALLUSERSPROFILE%\Application Data\OpenAFS\Client directory (aka \ProgramData\OpenAFS\Client on Vista\Win7\2008) or the %PROGRAMFILES%\OpenAFS\Client directory.   The
491         <link linkend='Value_CellServDBDir'>CellServDBDir</link> registry value or the AFSCONF environment variable can be used to specify an alternative location.
492       </para>
493       <para>For users converting from IBM AFS clients, during installation OpenAFS will relocate the contents of the &quot;afsdcell.ini&quot; file to the new CellServDB file.  OpenAFS will also import the contents of the &quot;afs_freelance.ini&quot; file to the Windows registry.   OpenAFS will not process the contents of the &quot;afsddbmt.ini&quot;.</para>
494     </section>
495     <section>
496       <title id='Windows_Internet_Connection_Firewall'>3.17. Microsoft Windows Internet Connection Firewall</title>
497       <para>The OpenAFS Client is compatible with the Internet Connection Firewall that debuted with Windows XP SP2 and Windows 2003 SP1.  The Internet Connection Firewall will be automatically adjusted to allow the receipt of incoming callback messages from the AFS file server.  In addition, the appropriate
498         <emphasis>Back Connection</emphasis> registry entries are added to allow SMB authentication to be performed across the Microsoft Loopback Adapter.
499       </para>
500     </section>
501     <section>
502       <title id='Browsing_AFS_from_Explorer_Shell'>3.18. Browsing AFS from the Explorer Shell and Office</title>
503       <para>The OpenAFS Client Service implements the CIFS Remote Admin Protocol which allows Explorer to browse server and share information. This significantly enhances the interoperability of AFS volumes within the Explorer Shell and Microsoft Office applications.</para>
504     </section>
505     <section>
506       <title id='Byte_Range_Locking'>3.19. Byte Range Locking</title>
507       <para>Many applications on Windows (e.g. Microsoft Office) require the use of byte range locks applied to a file either to protect against simultaneous file access or as a signaling mechanism.   OpenAFS for Windows release 1.5 (or greater) implements byte range locking within the CIFS-AFS gateway server.   This support for byte range locking obtains AFS’ advisory file server locks to simulate Microsoft Windows mandatory locks.   When an application opens a file, a lock will be obtained from AFS indicating that the file is in use.  If the lock is a write lock, access to the file will be restricted to other applications running on the same machine as the first application to request the lock.   Applications running on other machines will see the AFS full file lock and will be unable to access the file.</para>
508       <para>Most Windows applications and Windows itself opens files in shared read mode. When this is done, a read lock is applied to the file.   This does not prevent shared read access across multiple machines but is used to ensure that no one writes to the file while it is in use.</para>
509       <para>As the CIFS-AFS gateway server attempts to implement Windows lock semantics on top of AFS lock semantics it is important to understand how AFS file locks work.  In Windows there are no special privileges associated with obtaining file locks.  If you can read or execute a file, then you can obtain shared and exclusive locks.  In general, a Windows shared lock equates to an AFS read lock and a Windows exclusive lock equates to an AFS write lock.  In AFS if you can write to a file, then you can obtain a write lock.  However, in AFS if you can read a file it does not mean that you can obtain a read lock on it.   The ability to obtain read locks is granted only if you have the lock (or ‘k’) privilege.  This behavior is required in order to allow anonymous users to read files while preventing them from being able to deny access to the files to other users. 
510         <emphasis>OpenAFS 1.4.0 and earlier as well as all IBM AFS file servers have an implementation bug that prevents users with write privileges from being able to obtain locks without the lock privilege.</emphasis>  When AFS serves data out of read-only volumes the file server will deny all requests for read and write locks because the contents of the volume cannot be changed by the client.
511       </para>
512       <para>Since Microsoft Windows applications almost always attempt to obtain a temporary exclusive lock when accessing files the OpenAFS Client’s CIFS-AFS gateway implements the following semantics in order to reduce the inconvenience on end users.  </para>
513       <itemizedlist mark='bullet'>
514         <listitem>
515           <para>If the file is located on a read-only volume and the application requests a shared lock, the CIFS-AFS server will grant the lock request without asking the AFS file server.</para>
516         </listitem>
517         <listitem>
518           <para>If the file is located on a read-only volume and the application opens the file with write access and requests an exclusive lock, the CIFS-AFS server will refuse the lock request and return a read only error.</para>
519         </listitem>
520         <listitem>
521           <para>If the file is located on a read-only volume and the application opens the file with only read access and requests an exclusive lock, the CIFS-AFS server will fulfill the lock request with a read lock.</para>
522         </listitem>
523         <listitem>
524           <para>If the file is located on a read-write volume and the application requests an exclusive lock, the CIFS-AFS server will request a write lock from the AFS file server.  If granted by the file server, then the CIFS-AFS server will grant the lock request.  If the request is denied due to an access denied error and the user has the lookup, read and lock privileges and the file was opened for read only access, then the CIFS-AFS server will request a read lock from the file server.  If the request is denied due to an access denied error and the user has the lookup and read privileges but not the lock privilege, then the CIFS-AFS server will grant the request even though the AFS file server said ‘no’.  If the user does not have at least those permissions, the CIFS-AFS server will deny the request.</para>
525         </listitem>
526         <listitem>
527           <para>If the file is located on a read-write volume and the application requests a shared lock, the CIFS-AFS server will request a read lock from the AFS file server.  If granted by the file server, then the CIFS-AFS server grants the lock request.  If the request is denied due to an access denied error and the user has the lookup and read privileges but not the lock privilege, then the CIFS-AFS server will grant the request even though the AFS file server said ‘no’.  If the user does not have at least those permissions, the CIFS-AFS server will deny the request.</para>
528         </listitem>
529         <listitem>
530           <para>If multiple processes on the same machine attempt to access the same file simultaneously, the CIFS-AFS server will locally manage the granted locks and all processes will share a single lock on the AFS file server.</para>
531         </listitem>
532         <listitem>
533           <para>If the CIFS-AFS server is unable to renew the AFS file server locks, then it will invalidate the associated file handles.  This is the same behavior that an application will experience if it was using a Windows File Share and the connection was broken.   Invalidating the file handles prevents subsequent data corruption from taking place.</para>
534         </listitem>
535       </itemizedlist>
536       <para>If you wish to disable the acquisition of locks from the file server, this can be performed using the
537         <link linkend='Value_EnableServerLocks'>EnableServerLocks</link> registry value.
538       </para>
539     </section>
540     <section>
541       <title id='Automatic_Discarding_of_Tokens_at_Logoff'>3.20. Automatic Discarding of AFS Tokens at Logoff</title>
542       <para>The OpenAFS Client will automatically forget a user's tokens upon Logoff unless the user's profile was loaded from an AFS volume.  In this situation there is no mechanism to determine when the profile has been successfully written back to the network.  It is therefore unsafe to release the user's tokens.  Whether or not the profile has been loaded from the registry can be determined for Local Accounts, Active Directory accounts and NT4 accounts.</para>
543       <para>If there is a need to disable this functionality, the
544         <link linkend='Value_LogoffPreserveTokens'>LogoffPreserveTokens</link> registry value can be used. (see
545         <link linkend='appendix_a'>Appendix A</link>.)
546       </para>
547     </section>
548     <section>
549       <title id='Windows_Terminal_Server_Installs'>3.21. Windows Terminal Server installations</title>
550       <para>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.</para>
551     </section>
552     <section>
553       <title id='Hidden_Dot_Files'>3.22. Hidden Dot Files</title>
554       <para>AFS is a UNIX native file system.  The OpenAFS client attempts to treat the files stored in AFS as they would be on UNIX.  File and directory names beginning with a "." are automatically given the Hidden attribute so they will not normally be displayed.  This behavior can be altered via the
555         <link linkend='Value_HideDotFiles'>HideDotFiles</link> registry value.
556       </para>
557     </section>
558     <section>
559       <title id='Status_Cache_Limits'>3.23. Status Cache Limits</title>
560       <para>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.</para>
561       <para>If you are experiencing poor performance try increasing the maximum number of Status Cache entries.  Each entry requires approximately 1.2K.  The default number of Status Cache entries is 10,000.  This can be adjusted using the
562         <link linkend='Value_Stats'>Stats</link> registry value.
563       </para>
564     </section>
565     <section>
566       <title id='NETBIOS_over_TCP'>3.24. NETBIOS over TCP/IP must be enabled</title>
567       <para>"Netbios over TCP/IP" must be active on the machine in order for communication with the AFS Client Service to succeed.  If "Netbios over TCP/IP" is disabled on the machine, then communication with the AFS Client Service will be impossible.  If you are using the Microsoft Loopback Adapter, configure the &quot;Netbios over TCP/IP&quot; setting for the adapter.</para>
568     </section>
569     <section>
570       <title id='OpenAFS_binaries_digital_signatures'>3.25. OpenAFS binaries are digitally signed</title>
571       <para>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.  </para>
572       <para>
573         <link linkend='appendix_a'>Appendix A</link> documents the "
574         <link linkend='Value_VerifyServiceSignature'>VerifyServiceSignature</link>" registry value which can be used to disable the signature check.  The file version check cannot be disabled.
575       </para>
576     </section>
577     <section>
578       <title id='Maximum_Cache_Size'>3.26. Maximum Size of the AFSCache File</title>
579       <para>The maximum cache size on 32-bit Windows is approximately 1.3GB.  This is the largest contiguous block of memory in the 2GB process address space which can be used for constructing a memory mapped file.  Due to fragmentation of the process space caused by the loading of libraries required by the digital signature verification code, any attempt to specify a cache size greater then 700MB will result in the automatic disabling of the signature check.  Significantly larger cache sizes can be used on 64-bit Windows.</para>
580       <para>On 32-bit systems that have Apple Bonjour 1.0.6 installed, the maximum cache size is further constrained due design flaw in the Apple mdnsNSP.dll which is injected into all processes that use network services.  On these systems the maximum is approximately 512MB.</para>
581     </section>
582     <section>
583       <title id='Filename_Character_Sets'>3.27. Filename Character Sets</title>
584       <para>This section describes functionality and concerns related to pre-1.5.50 releases of OpenAFS for Windows.   This release stores all file names on the file servers as Unicode encoded using UTF-8.</para>
585       <para>OpenAFS for Windows implements an SMB server which is used as a gateway to the AFS filesystem.  Because of limitations of the SMB implementation in pre-1.5.50 releases, Windows stored 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 or Unicode (UTF-8) character sets typically used as the default on UNIX systems in both the United States and Western Europe.  Filenames stored by OpenAFS for Windows were therefore unreadable on UNIX systems if they include any of the following characters:</para>
586       <informaltable frame='all'>
587         <tgroup rowsep='1' align='left' colsep='1' cols='1'>
588           <colspec colwidth='442pt' colname='c1' />
589           <tbody>
590             <row>
591               <entry>
592                 <para>     [Ç]  128  08/00  200  80  C cedilla</para>
593                 <para>     [ü]  129  08/01  201  81  u diaeresis</para>
594                 <para>     [é]  130  08/02  202  82  e acute</para>
595                 <para>     [â]  131  08/03  203  83  a circumflex</para>
596                 <para>     [ä]  132  08/04  204  84  a diaeresis</para>
597                 <para>     [à]  133  08/05  205  85  a grave</para>
598                 <para>     [å]  134  08/06  206  86  a ring</para>
599                 <para>     [ç]  135  08/07  207  87  c cedilla</para>
600                 <para>     [ê]  136  08/08  210  88  e circumflex</para>
601                 <para>     [ë]  137  08/09  211  89  e diaeresis</para>
602                 <para>     [è]  138  08/10  212  8A  e grave</para>
603                 <para>     [ï]  139  08/11  213  8B  i diaeresis</para>
604                 <para>     [î]  140  08/12  214  8C  i circumflex</para>
605                 <para>     [ì]  141  08/13  215  8D  i grave</para>
606                 <para>     [Ä]  142  08/14  216  8E  A diaeresis</para>
607                 <para>     [Å]  143  08/15  217  8F  A ring</para>
608                 <para>     [É]  144  09/00  220  90  E acute</para>
609                 <para>     [æ]  145  09/01  221  91  ae diphthong</para>
610                 <para>     [Æ]  146  09/02  222  92  AE diphthong</para>
611                 <para>     [ô]  147  09/03  223  93  o circumflex</para>
612                 <para>     [ö]  148  09/04  224  94  o diaeresis</para>
613                 <para>     [ò]  149  09/05  225  95  o grave</para>
614                 <para>     [û]  150  09/06  226  96  u circumflex</para>
615                 <para>     [ù]  151  09/07  227  97  u grave</para>
616                 <para>     [ÿ]  152  09/08  230  98  y diaeresis</para>
617                 <para>     [Ö]  153  09/09  231  99  O diaeresis</para>
618                 <para>     [Ü]  154  09/10  232  9A  U diaeresis</para>
619                 <para>     [ø]  155  09/11  233  9B  o slash</para>
620                 <para>     [£]  156  09/12  234  9C  Pound sterling sign</para>
621                 <para>     [Ø]  157  09/13  235  9D  O slash</para>
622                 <para>     [×]  158  09/14  236  9E  Multiplication sign</para>
623                 <para>     [ƒ]  159  09/15  237  9F  Florin sign</para>
624               </entry>
625             </row>
626           </tbody>
627         </tgroup>
628       </informaltable>
629       <para> </para>
630       <para>The pre-1.5.50 OpenAFS Client provided an optional registry value,
631         <link linkend='Value_StoreAnsiFilenames'>StoreAnsiFilenames</link>, that could 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.
632       </para>
633       <para>All versions of OpenAFS for Windows 1.5.50 and above exchange file names with Microsoft Windows using the Unicode character set. All file names are read from and stored to AFS file servers using the UTF-8 encoding of Unicode. As a result the
634         <link linkend='Value_StoreAnsiFilenames'>StoreAnsiFilenames</link> option is no longer supported.
635       </para>
636     </section>
637     <section>
638       <title id='Character_Set_Issues_Roaming_Profiles'>3.28. Character Set Issues with Roaming Profiles</title>
639       <para>This section describes functionality and concerns related to pre-1.5.50 releases of OpenAFS for Windows.   This release stores all file names on the file servers as Unicode encoded using UTF-8.</para>
640       <para>There is a known issue with storing Windows Roaming Profiles when the profile contains either directories or files with names which cannot be represented in the local OEM character set.  In this case, attempts to write the profile back to AFS will fail during the character set conversion.  The pre-1.5.50 OpenAFS Client’s CIFS gateway did not support UNICODE.  To avoid this problem some sites run custom logoff scripts (assigned by group policy) which rename all files to use only the supported characters for the locale.</para>
641       <para>Versions of OpenAFS for Windows 1.5.50 and above do not suffer from these issues.</para>
642     </section>
643     <section>
644       <title id='AFSCache_File'>3.29. The AFSCache File</title>
645       <para>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.  </para>
646       <para>The performance of the AFS Client Service is significantly affected by the access times associated with the AFSCache paging file.   When given the choice, the AFSCache file should be placed on a fast disk, preferably NTFS, the file should not be compressed and should consist of as few fragments as possible.   Significant performance gains can be achieved by defragmenting the AFSCache file with SysInternal's Contig utility while the AFS Client Service is stopped.</para>
647     </section>
648     <section>
649       <title id='Restricting_OpenAFS_Service_Start_and_Stop'>3.30. Restricting OpenAFS Client Service Start and Stop</title>
650       <para>A new command line tool, afsdacl.exe, can be used to restrict the ability to start and stop the OpenAFS Client Service.</para>
651       <para>
652         <programlisting>
653     afsdacl : Set or reset the DACL to allow starting or stopping
654               the afsd service by any ordinary user.
655
656     Usage: afsdacl [-set | -reset] [-show]
657            -set   : Sets the DACL
658            -reset : Reset the DACL
659            -show  : Show current DACL (SDSF)
660     </programlisting>
661       </para>
662     </section>
663     <section>
664       <title id='SysName_List'>3.31. The @sys Name List</title>
665       <para>The default @sys name list in the OpenAFS Client is set to "x86_win32 i386_w2k i386_nt40" for 32-bit x86 systems.  The default is "amd64_win64" for amd 64-bit versions of Windows.</para>
666     </section>
667     <section>
668       <title id='Symlinks_to_AFS_UNC_Paths'>3.32. Symlinks to AFS UNC Paths</title>
669       <para>In OpenAFS, symlinks to AFS UNC paths, \\AFS[\all]\..., are treated the same as symlinks to /afs/...  However, please use /afs/... as the Windows UNC form will not work on UNIX client.</para>
670       <para>The <emphasis>symlink make</emphasis> command will automatically translate \\AFS\... to /afs/... for you.</para>
671     </section>
672     <section>
673       <title id='Cache_Manager_Debugging'>3.33. Cache Manager Debugging</title>
674       <para>The OpenAFS Client implements the Cache Manager Debugging RPC Interface.  The CM debugger can be queried with cmdebug.exe.  </para>
675       <para>
676         <programlisting>
677     Usage: cmdebug -servers &lt;server machine&gt; [-port &lt;IP port&gt;] [-long] [-refcounts]
678                     [-callbacks] [-ctime] [-addrs] [-cache] [-cellservdb] [-help]
679     Where: -long        print all info
680            -refcounts   print only cache entries with positive reference counts
681            -callbacks   print only cache entries with callbacks
682            -ctime       print human readable expiration time
683            -addrs       print only host interfaces
684            -cache       print only cache configuration
685            -cellservdb  print only cellservdb info
686     </programlisting>
687       </para>
688     </section>
689     <section>
690       <title id='Windows_Logon_Caching_vs_Kerberos_Logons'>3.34. Windows Logon Caching vs. Kerberos Logons</title>
691       <para>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.</para>
692     </section>
693     <section>
694       <title id='Initial_Server_Preferences'>3.35. Initial Server Preferences</title>
695       <para>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
696         <link linkend='appendix_a'>Appendix A</link> for details on the "
697         <link linkend='Regkey_HKLM_SOFTWARE_OpenAFS_Client_ServerPreferences_VLDB'>Server Preferences</link>" keys.
698       </para>
699     </section>
700     <section>
701       <title id='File_Timestamps_and_DST'>3.36. File Timestamps and Daylight Saving Time</title>
702       <para>The OpenAFS Client reports timestamps on files stored in AFS in UTC all year round.  In locales with daylight savings time, previous versions of AFS for Windows reported the time when DST is active as UTC+1.  This was done to preserve the relative local time for the user.  A file stored at 11:00am EST in January would be reported as having been stored at 11:00am EDT in June.  Unfortunately, this has the negative side effect of changing the reported timestamp from 16:00UTC to 15:00UTC.  Since Windows treats all file times in UTC, data synchronization applications which rely on the timestamp would believe that all files stored in AFS had changed.</para>
703       <para>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.</para>
704     </section>
705     <section>
706       <title id='Windows_RPC_client_support'>3.37. Windows RPC client support must be installed </title>
707       <para>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":</para>
708       <para>   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_np"</para>
709       <para>   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_ip_tcp"</para>
710       <para>   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncadg_ip_udp"</para>
711       <para>   HKLM "SOFTWARE\Microsoft\RPC\ClientProtocols" "ncacn_http"</para>
712     </section>
713     <section>
714       <title id='Generating_Minidumps'>3.38. Generating Minidumps of the OpenAFS Client Service</title>
715       <para>OpenAFS 1.4 added a new command, "fs minidump".  This command can be used at any time to generate a mini dump file containing the current stack of the afsd_service.exe process.   This output can be very helpful when debugging the AFS Client Service when it is unresponsive to SMB/CIFS requests.</para>
716     </section>
717     <section>
718       <title id='AFS_UUIDs_vs_System_Cloning'>3.39. AFS Client Universally Unique Identifiers (UUIDs) vs. System Cloning</title>
719       <para>The OpenAFS Client implements Universally Unique Identifiers (UUIDs).  They are used to provide the AFS file server with a method of identifying the client that is independent of IP address.  This permits the AFS file server to track mobile clients or those behind Network Address Translators when they move from address to address or port to port. Tracking the client improves client performance by permitting callback state to be maintained across location changes. The UUID is generated when the AFSCache file is created and is maintained as long as the contents of the AFSCache file are valid.  The UUID is stored in the AFSCache file. </para>
720       <para>When cloning machines that have Windows AFS client installed it is necessary to generate a new UUID for each client. This will be done automatically if the Windows Machine SID is re-generated using Microsoft SysPrep. If the SID is not being re-generated either the AFSCache file should be deleted or the command
721         <emphasis>fs uuid -generate</emphasis> must be executed after the the clone is created.
722         <emphasis role='bold'>Multiple AFS clients reporting the same UUID will not only result in horrible AFS client performance and cache inconsistencies, but they will also put a tremendous strain on the AFS file servers.</emphasis>
723       </para>
724       <para>For lab environments that wish to erase all cached data on each restart, the
725         <link linkend='Value_NonPersistentCaching'>NonPersistentCaching</link> option will disable the use of the persistent cache file. As a side effect, a new UUID will be generated for the AFS client service on each restart.
726       </para>
727       <para>When a Windows system is cloned, the Microsoft Loopback Adapter will be disabled in the cloned system.  Administrators must re-install the Microsoft Loopback Adapter within the cloned environment.  This can be automated by using the OpenAFS &quot;
728         <emphasis>instloop.exe</emphasis> –
729         <emphasis>i</emphasis>&quot; command.  Instloop.exe can be extracted from the MSI installer by performing an administrative install via
730         <emphasis>msiexec.exe /a</emphasis>.
731       </para>
732     </section>
733     <section>
734       <title id='Delayed_Write_Errors'>3.40. Delayed Write Errors with Microsoft Office Applications</title>
735       <para>Microsoft Office makes heavy use of asynchronous input/output methods for reading and writing to file streams.  This can result in hundreds of requests being simultaneously queued for service by the CIFS client with a fixed timeout period.  As the AFS CIFS server is local to the machine the Windows CIFS client believes that it can respond almost instantaneously to write requests as the actual writing to the AFS file server is performed by a background daemon thread.  When the actual network bandwidth to the AFS file server is slow and the file size is large it is possible for the CIFS client to time out the connection.  When this happens a &quot;delayed write error&quot; will be reported to the user and the application may crash.  The only workaround at the current time is to save first to a local disk and subsequently copy the file to AFS as copying a file with the explorer shell does not use asynchronous i/o. </para>
736       <para>The CIFS session timeout defaults to 45 seconds and can be increased by modifying the
737         <link linkend='Value_ConnDeadTimeout'>ConnDeadTimeout registry value</link>.
738       </para>
739       <para>Beginning with the 1.5.33 release, the performance characteristics of SMB Write Data operations can be adjusted.  In prior releases all writes were performed using a restricted asynchronous store model in which only one asynchronous store operation per file can be performed at a time.  The reason for this restriction is limit the amount of data the cache manager will accept without it having been written to the file server.  If too much unwritten data is accepted, the file close operation will block until all of the unwritten data is output and this could trigger a CIFS client disconnect.  </para>
740       <para>Prior to 1.5.33 the size of the asynchronous store was always equal to the chunk size which was often too large for low bandwidth connections.  The asynchronous store size now defaults to 32KB and is configurable using the
741         <link linkend='Value_SMBAsyncStoreSize'>SMBAsyncStoreSize</link> registry value.  Asynchronous store operations can also be disabled using the
742         <link linkend='Value_EnableSMBAsyncStore'>EnableSMBAsyncStore</link> registry value in which case all writes received by the cache manager block until the Rx StoreData operation completes.
743       </para>
744       <para>During the first quarter of 2009 Microsoft added new functionality to the SMB Redirector which permits an extended timeout period to be used
745             for an enumerated list of Netbios server names.  This functionality was distributed in Service Pack 2 for Vista and 2008 and is incorporated
746             into the RTM releases of Windows 7 and Server 2008 R2.  Updates to Windows XP (KB916204), XP64 (KB969289), and Server 2003 (KB969289) were
747             made available as hot fixes.  When this support is available, the OpenAFS for Windows client 1.5.61 and above will raise the timeout period
748             from 45 seconds to 10 minutes.</para>
749     </section>
750     <section>
751       <title id='Global_Drives'>3.41. Global Drives (aka Service Drive Letters) are no longer supported by Microsoft</title>
752       <para>The Global DriveAuto-mount feature has been deprecated due to the following Microsoft KB article.</para>
753       <para>
754         <ulink url='http://msdn.microsoft.com/library/en-us/dllproc/base/services_and_redirected_drives.asp'>http://msdn.microsoft.com/library/en-us/dllproc/base/services_and_redirected_drives.asp</ulink>
755       </para>
756       <para>The article says that services mounting drive letters are no longer supported by Microsoft and may act unpredictably. 
757             The experience other users have had is that if the connection to the OpenAFS CIFS/SMB server is terminated by the
758             Windows CIFS client, the drive mapping may not be re-established until the machine is rebooted.</para>
759       <para>OpenAFS supports UNC paths and whenever possible applications should be modified to use UNC form
760             \\AFS\&lt;cellname&gt;\&lt;path&gt; instead of drive letters.</para>
761       <para>Another problem with service mounted drive letters is that the drives are reported as local disk devices
762             and cannot be resolved as being mapped to the \\AFS name space.  As a result, AFS path ioctl operations will
763             fail.  The fs.exe and symlink.exe command line tools and the AFS Explorer Shell extension will not operate
764             on service mounted drive letters.</para>
765     </section>
766     <section>
767       <title id='64-bit_Windows'>3.42. 64-bit Microsoft Windows Installations</title>
768       <para>Although 64-bit Windows platforms support both 64-bit and 32-bit applications, the OpenAFS Service installed on the machine must be 64-bit.  The 64-bit installer contains only 64-bit executables.  In order to support 32-bit applications that link against OpenAFS libraries it is required that a separate 32-bit OpenAFS Tools set be installed.  For example, the 32-bit version of Kerberos for Windows can be used with the 32-bit OpenAFS Tools to manage AFS tokens.</para>
769       <para>OpenAFS on 64-bit Windows benefits from the lifting of the 2GB process memory restriction that is present in 32-bit Windows.   Without this restriction the AFS Cache File can become arbitrarily large limited only by available disk space.</para>
770     </section>
771     <section>
772       <title id='Windows_Vista_Known_Issues'>3.43. Known Issues with Microsoft Windows Vista, Windows 7, and Server 2008 [R2]</title>
773       <para>OpenAFS for Windows works with Microsoft Windows Vista, Windows 7 and Server 2008 [R2] from both the command prompt and the Explorer Shell.
774             When performing an upgrade from earlier versions of Microsoft Windows the Microsoft Loopback Adapter (MSLA) will be uninstalled.
775             OpenAFS should be re-installed after the Windows Upgrade installation to restore the MSLA configuration.</para>
776       <para>Due to a feature change in Windows Vista’s Plug-n-Play network stack, during a standby/hibernate operation the
777             MSLA is disabled just as any other hardware device would be.  This causes the OpenAFS Client’s network binding to be lost.
778             As a result, it takes anywhere from 30 to 90 seconds after the operating system is resumed for access to the OpenAFS Client
779             and the AFS file name space to be restored.  Until the network bindings have been re-established, ticket managers and other
780             tools will report that the &quot;AFS Client Service may not have been started&quot;.</para>
781       <para>Windows Vista, Windows 7, and Server 2008 [R2] implement
782         <ulink url='http://www.microsoft.com/technet/windowsvista/library/0d75f774-8514-4c9e-ac08-4c21f5c6c2d9.mspx'>User Account Control</ulink> (UAC), a new security feature that implements least user privilege.  With UAC, applications only run with the minimum required privileges.  Even Administrator accounts run applications without the &quot;Administrator&quot; access control credentials.  One side effect of this is that existing applications that mix user and system configuration capabilities must be re-written to separate those functions that require &quot;Administrator&quot; privileges into a separate process space.  Future updates to OpenAFS will incorporate the necessary privilege separation, until that time some functions such as the Start and Stop Service features of the AFS System Tray tool and the AFS Control Panel will not work unless they are &quot;Run as Administrator&quot;.  When a Vista user account that is a member of the &quot;Administrators&quot; group is used to access the AFS Control Panel (afs_config.exe), the process must be &quot;Run as Administrator&quot;.   Otherwise, attempts to modify the OpenAFS configuration will appear to succeed but in reality will have failed due to Vista’s system file and registry virtualization feature.
783       </para>
784       <para>The help files provided with OpenAFS are in .HLP format.
785         <ulink url='http://support.microsoft.com/kb/917607'>Windows Vista, Windows 7, and Server 2008 [R2] do not include a help engine for this format.</ulink>
786       </para>
787     </section>
788     <section>
789       <title id='AFS_Share_Direct_Access_to_Volumes'>3.44. New AFS Share Name Syntax Provides Direct Access to Volumes</title>
790       <para>Starting with the 1.5.21 release of OpenAFS for Windows, the following syntax can be used to access any volume in any cell without requiring the creation of a mount point.</para>
791       <para>\\AFS\&lt;cell&gt;&lt;mount point type&gt;&lt;volume&gt;\</para>
792       <para>Where &lt;cell&gt; can be either a full cell name or an unambiguous prefix, the &lt;mount point type&gt; is ‘#’ for a normal mount point or ‘%’ to force the use of a read-write volume, and &lt;volume&gt; is either a volume name or its ID number.</para>
793       <para>Examples include:</para>
794       <para>    \\AFS\athena.mit.edu#user.jaltman\</para>
795       <para>    \\AFS\athena%user.jaltman\</para>
796       <para>    \\AFS\athena.mit.edu# 537235559\</para>
797     </section>
798     <section>
799       <title id='Differences_between_Windows_and_Unix'>3.45. Differences between Windows and UNIX &quot;fs examine&quot;</title>
800       <para>The OpenAFS for Windows version of &quot;fs examine&quot; provide two additional lines of output when compared to the
801         UNIX implementation.  These lines include the owner and group information for the file as well as the volume status.
802         The Windows output will also indicate the type of object {File, Directory, Mountpoint, Symlink, ...} that was examined.</para>
803       <para>[C:\]fs examine \\afs\athena#user.jaltman</para>
804       <para>Directory \\afs\athena#user.jaltman (537235559.1.1) contained in cell athena.mit.edu</para>
805       <para>
806         <emphasis role='bold'>Owner jaltman (28180) Group jaltman (28180)</emphasis>
807       </para>
808       <para>Volume status for vid = 537235559 named user.jaltman is</para>
809       <para>Current disk quota is 1500000</para>
810       <para>Current blocks used are 1244184</para>
811       <para>The partition has 151945877 blocks available out of 511163724</para>
812       <para><emphasis role='bold'>Volume is online</emphasis></para>
813       <para></para>
814       <para>The object owner and group information is not available on Microsoft Windows via any other method.</para>
815       <para>To set the owner use <emphasis>fs chown -owner &lt;user name or id&gt; [-path &lt;dir/file path&gt;+] [-literal]</emphasis></para>
816       <para>To set the group use <emphasis>fs chgrp -group &lt;user name or id&gt; [-path &lt;dir/file path&gt;+] [-literal]</emphasis></para>
817     </section>
818     <section>
819       <title id='fs_Command_Literal_Option'>3.46. Literal evaluation of AFS objects via fs commands</title>
820       <para>Beginning with the 1.5.31 release, the fs commands
821         <emphasis>examine</emphasis>,
822         <emphasis>flush</emphasis>,
823         <emphasis>whereis</emphasis>, and
824         <emphasis>whichcell</emphasis> provide a new command-line parameter,
825         <emphasis>-literal</emphasis>.  When specified, if the evaluated object is a symlink or a mountpoint the resulting output will describe the specified object and not the object that is the target of the symlink or mountpoint.
826       </para>
827     </section>
828     <section>
829       <title id='Out_of_Quota_Errors'>3.47. Out of Quota errors</title>
830       <para>Prior to the 1.5.31 release, out of quota errors were reported to the calling application as an out of space error.  As of 1.5.31, an out of space error will indicate that the partition on which the volume is located is in fact out of space.  Whereas an out of quota error indicates that the user does not have permission to allocate additional space.</para>
831     </section>
832     <section>
833       <title id='Linked_Cells'>3.48. Linked Cells</title>
834       <para>The 1.5.55 release adds support for linked cells as implemented in the Unix OpenAFS client.  When two cells are linked, a volume lookup in one cell that fails is retried in the linked cell.  This functionality can be used to implement:</para>
835       <itemizedlist mark='bullet'>
836         <listitem>
837           <para>a test cell which provides substitutes for a subset of the volumes in the linked production cell</para>
838         </listitem>
839         <listitem>
840           <para>a cell renaming</para>
841         </listitem>
842         <listitem>
843           <para>a cell splitting</para>
844         </listitem>
845         <listitem>
846           <para>a cell merger</para>
847         </listitem>
848       </itemizedlist>
849       <para>Two cells are linked in the CellServDB file:</para>
850       <para>
851         <programlisting>
852        &gt;cell-one     cell-two        #Description
853        ...
854        &gt;cell-two     cell-one        #Description
855        ...
856        </programlisting>
857       </para>
858       <para>aklog and Network Identity Manager will automatically obtain tokens for the linked cell when tokens for the other cell is specified.
859       </para>
860     </section>
861     <section>
862     <title id="Registry_VLDB_Configuration">3.49 Registry Configuration for AFS Volume Database Servers</title>
863     <para>Beginning with the 1.5.60 release, the <link linkend="Regkey_HKLM_SOFTWARE_OpenAFS_Client_CellServDB">[HKLM\SOFTWARE\OpenAFS\Client\CellServDB]</link>
864     registry key can be used to distribute Volume Database Server location information either as a supplement to the <emphasis>CellServDB file</emphasis> or
865     as a substitute for it.  The precedence order for lookups is: Registry, File, and then DNS.</para>
866     </section>
867     <section>
868     <title id="HTMLHelp_Documentation">3.50 Documentation Converted to Windows HTML Help</title>
869     <para>Starting with the 1.5.60 release, this document, the OpenAFS Administrator Guide and the OpenAFS User Guide are provided in HTML Help format instead
870     of raw HTML pages.</para>
871     </section>
872     <section>
873       <title id='MSRPC_Services'>3.51. Support for Microsoft RPC Services: WKSSVC and SRVSVC</title>
874       <para>Beginning with the 1.5.62 release, the OpenAFS SMB Server supports named pipes and the Microsoft RPC Services
875         WKSSVC and SRVSVC.  This permits a significantly improved Netbios Server browsing experience with both the
876         <emphasis>NET VIEW \\AFS</emphasis> command and the Explorer Shell.  No longer will Windows display truncated
877         cell names as available network shares.  The network share properties will also include the object type and
878         and the target of symlinks and mount points.</para>
879     </section>
880   </chapter>
881   <chapter id='chap_4'>
882     <title id='How_to_Debug_Problems'>How to Debug Problems with OpenAFS for Windows</title>
883     <para>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.</para>
884     <section>
885       <title id='pioctl_debugging'>4.1. pioctl debugging (
886         <link linkend='Value_IoctlDebug'>IoctlDebug</link> registry key)
887       </title>
888       <para>pioctl (path-based ioctl) calls are used by various tools to communicate with the AFS Client Service.  Some of the operations performed include:</para>
889       <itemizedlist>
890         <listitem>
891           <para>setting/querying tokens  (tokens.exe, aklog.exe, afscreds.exe)</para>
892         </listitem>
893         <listitem>
894           <para>setting/querying ACLs </para>
895         </listitem>
896         <listitem>
897           <para>setting/querying cache parameters</para>
898         </listitem>
899         <listitem>
900           <para>flushing files or volumes</para>
901         </listitem>
902         <listitem>
903           <para>setting/querying server preferences</para>
904         </listitem>
905         <listitem>
906           <para>querying path location</para>
907         </listitem>
908         <listitem>
909           <para>checking the status of servers and volumes</para>
910         </listitem>
911         <listitem>
912           <para>setting/querying the sysname list</para>
913         </listitem>
914       </itemizedlist>
915       <para>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.   </para>
916       <para>To assist in debugging these problems, the registry value:</para>
917       <para>  [HKLM\SOFTWARE\OpenAFS\Client]</para>
918       <para>  REG_DWORD:  IoctlDebug   = 0x01</para>
919       <para>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.</para>
920     </section>
921     <section>
922       <title id='afsd_service_init_log'>4.2. afsd_service initialization log (%WinDir%\TEMP\afsd_init.log)</title>
923       <para>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.</para>
924       <para>The
925         <link linkend='Value_MaxLogSize'>MaxLogSize</link> 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.
926       </para>
927     </section>
928     <section>
929       <title id='afsd_service_debug_log'>4.3. afsd_service debug logs (fs trace {-on, -off, -dump} -&gt;%WinDir%\TEMP\afsd.log)</title>
930       <para>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
931         <link linkend='Value_TraceBufferSize'>TraceBufferSize registry value</link>:
932       </para>
933       <para>  [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
934       <para>  REG_DWORD  TraceBufferSize </para>
935       <para>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.</para>
936     </section>
937     <section>
938       <title id='Using_Sysinternals_Tools'>4.4. Using SysInternal’s Debug Viewer, Process Monitor and Process Explorer Tools</title>
939       <para>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
940         <ulink url='http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx'>Debug Viewer</ulink> to capture real-time debugging output.  When the OpenAFS Client Service starts and Bit 2 of the
941         <link linkend='Value_TraceOption'>TraceOption</link> value in the registry is set, all trace log events are output using the Windows Debug Monitor interface (OutputDebugString). 
942       </para>
943       <para>  [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
944       <para>REG_DWORD   TraceOption = 0x04</para>
945       <para>Use &quot;fs trace –on&quot; and &quot;fs trace –off&quot; to toggle the generation of log messages. </para>
946       <para>Sysinternal’s
947         <ulink url='http://technet.microsoft.com/en-us/sysinternals/bb896645.aspx'>Process Monitor</ulink> can be use to monitor the file operations requested by applications and their success or failure.  
948       </para>
949       <para>In Process Monitor, set a filter to include only events on file paths that refer to the AFS name space. Be sure to include both the UNC path as well as any drive letters mapped to AFS. </para>
950       <para>Turn on the
951         <emphasis>Clock Time</emphasis> and
952         <emphasis>Show Milliseconds</emphasis> options in both tools to make it easier to synchronize the application requests and the resulting OpenAFS Client Service operations.   The captured data can be stored to files for inclusion in
953         <link linkend='Reporting_Bugs'>bug reports</link>.
954       </para>
955       <para>Sysinternal's
956         <ulink url='http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx'>Process Explorer</ulink> is a replacement for the Windows Task Manager and so much more.  Process Explorer can be configured to use the DbgHelp.dll from "
957         <ulink url='http://www.microsoft.com/whdc/devtools/debugging/default.mspx'>Microsoft Debugging Tools for Windows</ulink>" as well as the debug symbols shipped as an optional component of the OpenAFS for Windows installer.  (Options-&gt;Configure Symbols)   Once configured the "Threads" tab of the process properties dialog will permit the viewing of a fully documented stack for each displayed thread.  Hint: If there is a deadlock in the cache manager, two or more of the threads will be stuck in a call to osi_TWait().
958       </para>
959     </section>
960     <section>
961       <title id='Creating_Microsoft_Minidumps'>4.5. Creating Microsoft MiniDumps
962 (fs minidump -&gt; %WinDir%\TEMP\afsd.dmp)</title>
963       <para>If the AFS Client Service become unresponsive to any form of communication there may be a serious error that can only be debugged by someone with access to the source code and a debugger.   The "fs minidump" command can be used to force the generation of a MiniDump file containing the state of all of the threads in the AFS Client Service process.  The most accurate MiniDump files will be produced after installing "
964         <ulink url='http://www.microsoft.com/whdc/devtools/debugging/default.mspx'>Microsoft Debugging Tools for Windows</ulink>".
965       </para>
966       <para>The
967         <link linkend='Value_MiniDumpType'>MiniDumpType</link> registry value can be used to adjust the scope of the process information included within the dump file.  By default the MiniDump only contains the stacks of all threads and the values of all global variables.  A much more useful MiniDump is one that contains the contents of the heap.  Be warned, a MiniDump with heap will be as large as the cache file.  In addition, it will include all of the data stored within the cache.  If there are privacy concerns, do not produce a MiniDump with heap.
968       </para>
969     </section>
970     <section>
971       <title id='Integrated_Logon_Debugging'>4.6. Single Sign-on (Integrated Logon) debugging</title>
972       <para>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
973         <link linkend='Value_TraceOption'>TraceOption</link> registry value:
974       </para>
975       <para>  [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
976       <para>  REG_DWORD   TraceOption = 0x01</para>
977       <para>will instruct the Integrated Logon Network Provider and Event Handlers to log information to the Windows Event Log: Application under the name &quot;AFS Logon".</para>
978     </section>
979     <section>
980       <title id='rxdebug_usage'>4.7. RX (AFS RPC) debugging (rxdebug)</title>
981       <para>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.  </para>
982       <para>
983         <programlisting>
984     Usage: rxdebug -servers &lt;server machine&gt; [-port &lt;IP port&gt;] [-nodally]
985            [-allconnections] [-rxstats] [-onlyserver] [-onlyclient]
986            [-onlyport &lt;show only &lt;port&gt;&gt;]
987            [-onlyhost &lt;show only &lt;host&gt;&gt;]
988            [-onlyauth &lt;show only &lt;auth level&gt;&gt;] [-version]
989            [-noconns] [-peers] [-help]
990     Where: -nodally         don't show dallying conns
991            -allconnections  don't filter out uninteresting connections
992            -rxstats         show Rx statistics
993            -onlyserver      only show server conns
994            -onlyclient      only show client conns
995            -version         show AFS version id
996            -noconns         show no connections
997            -peers           show peers
998       </programlisting>
999       </para>
1000     </section>
1001     <section>
1002       <title id='cmdebug_usage'>4.8. Cache Manager debugging (cmdebug)</title>
1003       <para>The cmdebug.exe tool can be used to query the state of the AFS Cache Manager on a given machine.</para>
1004       <para>
1005         <programlisting>
1006     Usage: cmdebug -servers &lt;server machine&gt; [-port &lt;IP port&gt;] [-long] [-refcounts]
1007            [-callbacks] [-ctime] [-addrs] [-cache] [-cellservdb] [-help]
1008     Where: -long        print all info
1009            -refcounts   print only cache entries with positive reference counts
1010            -callbacks   print only cache entries with callbacks
1011            -ctime       print human readable expiration time
1012            -addrs       print only host interfaces
1013            -cache       print only cache configuration
1014            -cellservdb  print only cellservdb info
1015       </programlisting>
1016       </para>
1017     </section>
1018     <section>
1019       <title id='Persistent_Cache_Consistency_Check'>4.9. Persistent Cache consistency check</title>
1020       <para>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.</para>
1021       <para>  afsd_service.exe --validate-cache &lt;cache-path&gt;</para>
1022     </section>
1023     <section>
1024       <title id='Token_Acquisition_Debugging'>4.10. Token Acquisition Debugging</title>
1025       <para>If you are having trouble obtaining tokens with the Network Identity Manager AFS credential provider, it is recommended that you verify your ability to obtain tokens using the command-line tools
1026         <emphasis>klog.exe</emphasis> (if you are using kaserver) or
1027         <emphasis>kinit.exe</emphasis> and
1028         <emphasis>aklog.exe</emphasis> (if you are using Kerberos v5.)  The aklog.exe
1029         <emphasis>–d</emphasis> option will be quite helpful in diagnosing Kerberos v5 related problems.
1030       </para>
1031     </section>
1032   </chapter>
1033   <chapter id='chap_5'>
1034     <title id='Reporting_Bugs'>Reporting Bugs</title>
1035     <para>Bug reports should be sent to
1036       <ulink url='mailto:openafs-bugs@openafs.org?subject=Bug%20Report'>openafs-bugs@openafs.org</ulink>.  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.
1037     </para>
1038     <para>Configuring DrWatson to generate dump files for crashes:</para>
1039     <orderedlist>
1040       <listitem>
1041         <para>Run drwtsn32.exe to configure or to identify where the log and the crash dump files are created: </para>
1042       </listitem>
1043       <listitem>
1044         <para>click Start &gt; Run...  </para>
1045       </listitem>
1046       <listitem>
1047         <para>type drwtsn32 &lt;enter&gt;. </para>
1048       </listitem>
1049       <listitem>
1050         <para>Select either a Crash Dump Type: Mini or Full. </para>
1051       </listitem>
1052       <listitem>
1053         <para>Clear Dump Symbol Table</para>
1054       </listitem>
1055       <listitem>
1056         <para>Clear Append to Existing Log file. </para>
1057       </listitem>
1058       <listitem>
1059         <para>Check Dump All Thread Contexts.</para>
1060       </listitem>
1061       <listitem>
1062         <para>Check Create Crash Dump File</para>
1063       </listitem>
1064       <listitem>
1065         <para>Next run the monitoring module of Dr. Watson: </para>
1066       </listitem>
1067       <listitem>
1068         <para>click Start &gt; Run...</para>
1069       </listitem>
1070       <listitem>
1071         <para>type drwatson &lt;enter&gt;. </para>
1072       </listitem>
1073       <listitem>
1074         <para>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.</para>
1075       </listitem>
1076     </orderedlist>
1077     <para>Once you have the Dr. Watson's logfile and minidump, zip them and attach them to your e-mail.</para>
1078     <para>When reporting a error, please be sure to include the version of OpenAFS.
1079     </para>
1080   </chapter>
1081   <chapter id='chap_6'>
1082     <title id='Contributing_to_OpenAFS'>How to Contribute to the Development of OpenAFS for Windows</title>
1083     <para>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.</para>
1084     <section>
1085       <title id='USENIX_OpenAFS_Fund'>6.1. The USENIX OpenAFS Fund </title>
1086       <para>
1087         <ulink url='http://www.usenix.org/'>USENIX</ulink>, 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.
1088       </para>
1089       <informaltable frame='none'>
1090         <tgroup rowsep='1' align='left' colsep='1' cols='1'>
1091           <colspec colwidth='405pt' colname='c1' />
1092           <tbody>
1093             <row>
1094               <entry>
1095                 <para>
1096                   <programlisting>
1097     USENIX OpenAFS Fund
1098     USENIX Association
1099     2560 Ninth St., Suite 215
1100     Berkeley, CA 94710
1101                   </programlisting>
1102                 </para>
1103               </entry>
1104             </row>
1105           </tbody>
1106         </tgroup>
1107       </informaltable>
1108       <para>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
1109         <ulink url='https://db.usenix.org/cgi-bin/openafs/openafs.cgi'>donation online</ulink>.
1110       </para>
1111     </section>
1112     <section>
1113       <title id='Secure_Endpoints_Inc'>6.2. Secure Endpoints Inc. </title>
1114       <para>
1115         <ulink url='http://www.secure-endpoints.com/'>Secure Endpoints Inc.</ulink> provides development and support services for OpenAFS for Windows and
1116         <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink>.  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.
1117       </para>
1118       <para>Secure Endpoints Inc. accepts software development agreements from organizations who wish to fund a well-defined set of bug fixes or new features. </para>
1119       <para>Secure Endpoints Inc. provides contract based support for the OpenAFS for Windows and the
1120         <ulink url='http://web.mit.edu/kerberos/'>MIT Kerberos for Windows</ulink> products.
1121       </para>
1122     </section>
1123     <section>
1124       <title id='Direct_Code_Contributions'>6.3. Direct contributions of code and/or documentation </title>
1125       <para>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. </para>
1126     </section>
1127     <section>
1128       <title id='OAFW_Mailing_Lists'>6.4. OpenAFS for Windows Mailing Lists</title>
1129       <para>If you wish to participate in OpenAFS for Windows development please join the
1130         <ulink url='mailto:openafs-win32-devel@openafs.org?subject=OpenAFS%20for%20Windows%20Development%20Contribution'>openafs-win32-devel@openafs.org</ulink> mailing list.
1131       </para>
1132       <para>
1133         <emphasis role='bold'>https://lists.openafs.org/mailman/listinfo/openafs-win32-devel</emphasis>
1134       </para>
1135       <para>User questions should be sent to the
1136         <ulink url='mailto:openafs-info@openafs.org?subject=OpenAFS%20for%20Windows%20User%20Question'>openafs-info@openafs.org</ulink> mailing list. 
1137       </para>
1138       <para>
1139         <emphasis role='bold'>https://lists.openafs.org/mailman/listinfo/openafs-info</emphasis>
1140       </para>
1141       <para>You must join the mailing lists if you wish to post to the list without incurring a moderation delay.</para>
1142     </section>
1143   </chapter>
1144   <chapter id='chap_7'>
1145     <title id='MSI_Deployment_Guide'>MSI Deployment Guide</title>
1146     <section>
1147       <title id='Introduction_to_MSI_Deployment'>7.1. Introduction</title>
1148       <para>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.</para>
1149       <para>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.</para>
1150       <section>
1151         <title id='MSI_Deployment_Requirements'>7.1.1 Requirements</title>
1152         <para>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.</para>
1153         <para>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.</para>
1154         <para>For reference, the schema for the MSI package is based on SCHEMA.MSI distributed with the Platform SDK.</para>
1155         <para>For general information about "Windows Installer", refer to:</para>
1156         <para>   
1157           <ulink url='http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp'>http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp</ulink>
1158         </para>
1159         <para>For general information about authoring MSI transforms, refer to:</para>
1160         <para>   
1161           <ulink url='http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp'>http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp</ulink>
1162         </para>
1163         <para>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:</para>
1164         <para>   
1165           <ulink url='http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp'>http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp</ulink>
1166         </para>
1167       </section>
1168       <section>
1169         <title id='MSI_Authoring_Transforms'>7.1.2 Authoring a Transform</title>
1170         <para>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:</para>
1171         <orderedlist>
1172           <listitem>
1173             <para>copy openafs.msi openafs-modified.msi</para>
1174           </listitem>
1175           <listitem>
1176             <para>(edit the openafs-modified.msi to include the necessary changes)</para>
1177           </listitem>
1178           <listitem>
1179             <para>msitran -g openafs.msi openafs-modified.msi openafs-transform.mst</para>
1180           </listitem>
1181           <listitem>
1182             <para>(generates openafs-transform.mst, which is the transform)</para>
1183           </listitem>
1184         </orderedlist>
1185         <para>Transforms have an extension of .mst.  'msitran' is a tool distributed as part of the "Windows Installer" SDK (part of the Windows Platform SDK).</para>
1186         <para>You can test a transform by:</para>
1187         <orderedlist>
1188           <listitem>
1189             <para>copy openafs.msi openafs-test.msi</para>
1190           </listitem>
1191           <listitem>
1192             <para>msitran -a openafs-transform.mst openafs-test.msi</para>
1193           </listitem>
1194         </orderedlist>
1195         <para>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.</para>
1196         <para>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.</para>
1197       </section>
1198     </section>
1199     <section>
1200       <title id='MSI_Configuration_Options'>7.2. Configuration Options</title>
1201       <para>The logic necessary to implement many of the settings described in
1202         <link linkend='appendix_a'>Appendix A</link> 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.
1203       </para>
1204       <section>
1205         <title id='MSI_Configurable_Properties'>7.2.1 Configurable Properties</title>
1206         <para>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.</para>
1207         <para>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.</para>
1208         <para>For each property, the associated registry setting is referenced by the same text used in
1209           <link linkend='appendix_a'>Appendix A</link>.
1210         </para>
1211         <para>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.</para>
1212         <para>Numeric values should be authored as decimal strings.</para>
1213         <section>
1214           <title id='MSI_Setting_Properties'>7.2.1.1 Setting Properties</title>
1215           <para>In order to set a property,</para>
1216           <orderedlist>
1217             <listitem>
1218               <para>Open the MSI in ORCA.EXE</para>
1219             </listitem>
1220             <listitem>
1221               <para>Select the 'Property' table from the list of tables on the left.</para>
1222             </listitem>
1223             <listitem>
1224               <para>Find the property in the list of properties on the right, double click the value and type the new value.</para>
1225             </listitem>
1226             <listitem>
1227               <para>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.</para>
1228             </listitem>
1229           </orderedlist>
1230         </section>
1231         <section>
1232           <title id='MSI_OAFW_Properties'>7.2.1.2 OpenAFS for Windows Properties</title>
1233           <informaltable frame='all'>
1234             <tgroup rowsep='1' align='left' colsep='1' cols='1'>
1235               <colspec colwidth='447pt' colname='c1' />
1236               <tbody>
1237                 <row>
1238                   <entry>
1239                     <para>
1240                       <emphasis>(Service parameters):</emphasis>
1241                     </para>
1242                     <para>[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
1243                   </entry>
1244                 </row>
1245                 <row>
1246                   <entry>
1247                     <para>
1248                       <emphasis>(Network provider):</emphasis>
1249                     </para>
1250                     <para>[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]</para>
1251                   </entry>
1252                 </row>
1253                 <row>
1254                   <entry>
1255                     <para>
1256                       <emphasis>(OpenAFS Client):</emphasis>
1257                     </para>
1258                     <para>[HKLM\SOFTWARE\OpenAFS\Client]</para>
1259                   </entry>
1260                 </row>
1261               </tbody>
1262             </tgroup>
1263           </informaltable>
1264           <section>
1265             <title id='MSI_OAFW_Registry_Properties'>7.2.1.2.1 Registry Properties</title>
1266             <para>These properties are used to set the values of registry entries associated with OpenAFS for Windows.</para>
1267             <informaltable frame='all'>
1268               <tgroup rowsep='1' align='left' colsep='1' cols='1'>
1269                 <colspec colwidth='447pt' colname='c1' />
1270                 <tbody>
1271                   <row>
1272                     <entry>
1273                       <para>
1274                         <emphasis role='bold'>AFSCACHEPATH</emphasis>
1275                       </para>
1276                       <para>Registry key    :
1277                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1278                       </para>
1279                       <para>Registry value :
1280                         <link linkend='Value_CachePath'>CachePath</link>
1281                       </para>
1282                       <para>Valid values    : string .</para>
1283                     </entry>
1284                   </row>
1285                   <row>
1286                     <entry>
1287                       <para>
1288                         <emphasis role='bold'>AFSCACHESIZE</emphasis>
1289                       </para>
1290                       <para>Registry key    :
1291                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1292                       </para>
1293                       <para>Registry value :
1294                         <link linkend='Value_CacheSize'>CacheSize</link>
1295                       </para>
1296                       <para>Valid values    : numeric</para>
1297                     </entry>
1298                   </row>
1299                   <row>
1300                     <entry>
1301                       <para>
1302                         <emphasis role='bold'>AFSCELLNAME</emphasis>
1303                       </para>
1304                       <para>Registry key    :
1305                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1306                       </para>
1307                       <para>Registry value :
1308                         <link linkend='Value_Cell'>Cell</link>
1309                       </para>
1310                       <para>Valid values    : string</para>
1311                     </entry>
1312                   </row>
1313                   <row>
1314                     <entry>
1315                       <para>
1316                         <emphasis role='bold'>FREELANCEMODE</emphasis>
1317                       </para>
1318                       <para>Registry key    :
1319                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1320                       </para>
1321                       <para>Registry value :
1322                         <link linkend='Value_FreelanceClient'>FreelanceClient</link>
1323                       </para>
1324                       <para>Valid values    : '1' or '0'</para>
1325                     </entry>
1326                   </row>
1327                   <row>
1328                     <entry>
1329                       <para>
1330                         <emphasis role='bold'>HIDEDOTFILES</emphasis>
1331                       </para>
1332                       <para>Registry key    :
1333                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1334                       </para>
1335                       <para>Registry value :
1336                         <link linkend='Value_HideDotFiles'>HideDotFiles</link>
1337                       </para>
1338                       <para>Valid values    : '1' or '0'</para>
1339                     </entry>
1340                   </row>
1341                   <row>
1342                     <entry>
1343                       <para>
1344                         <emphasis role='bold'>LOGONOPTIONS</emphasis>
1345                       </para>
1346                       <para>Registry key    :
1347                         <link linkend='Domain_Specific_Regkeys'>(Network Provider)</link>
1348                       </para>
1349                       <para>Registry value :
1350                         <link linkend='Value_LogonOptions'>LogonOptions</link>
1351                       </para>
1352                       <para>Valid values    : '0', '1' or '3'</para>
1353                       <para>See
1354                         <link linkend='appendix_a'>Appendix A</link>
1355                         <link linkend='Domain_Specific_Configuration'>section 2.1 (Domain Specific Configuration keys for Network Provider)</link> for more details.
1356
1357
1358
1359                       </para>
1360                     </entry>
1361                   </row>
1362                   <row>
1363                     <entry>
1364                       <para>
1365                         <emphasis role='bold'>MOUNTROOT</emphasis>
1366                       </para>
1367                       <para>Registry key    :
1368                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1369                       </para>
1370                       <para>Registry value :
1371                         <link linkend='Value_Mountroot'>Mountroot</link>
1372                       </para>
1373                       <para>Valid values    : string</para>
1374                     </entry>
1375                   </row>
1376                   <row>
1377                     <entry>
1378                       <para>
1379                         <emphasis role='bold'>NETBIOSNAME</emphasis>
1380                       </para>
1381                       <para>Registry key    :
1382                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1383                       </para>
1384                       <para>Registry value :
1385                         <link linkend='Value_NetbiosName'>NetbiosName</link>
1386                       </para>
1387                       <para>Valid values    : string (at most 15 characters)</para>
1388                     </entry>
1389                   </row>
1390                   <row>
1391                     <entry>
1392                       <para>
1393                         <emphasis role='bold'>NOFINDLANABYNAME</emphasis>
1394                       </para>
1395                       <para>Registry key    :
1396                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1397                       </para>
1398                       <para>Registry value :
1399                         <link linkend='Value_NoFindLanaByName'>NoFindLanaByName</link>
1400                       </para>
1401                       <para>Valid values    : '1' or '0'</para>
1402                     </entry>
1403                   </row>
1404                   <row>
1405                     <entry>
1406                       <para>
1407                         <emphasis role='bold'>RXMAXMTU</emphasis>
1408                       </para>
1409                       <para>Registry key    :
1410                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1411                       </para>
1412                       <para>Registry value :
1413                         <link linkend='Value_RxMaxMTU'>RxMaxMTU</link>
1414                       </para>
1415                       <para>Valid values    : numeric</para>
1416                     </entry>
1417                   </row>
1418                   <row>
1419                     <entry>
1420                       <para>
1421                         <emphasis role='bold'>SECURITYLEVEL</emphasis>
1422                       </para>
1423                       <para>Registry key    :
1424                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1425                       </para>
1426                       <para>Registry value :
1427                         <link linkend='Value_SecurityLevel'>SecurityLevel</link>
1428                       </para>
1429                       <para>Valid values    : '1' or '0'</para>
1430                     </entry>
1431                   </row>
1432                   <row>
1433                     <entry>
1434                       <para>
1435                         <emphasis role='bold'>SMBAUTHTYPE</emphasis>
1436                       </para>
1437                       <para>Registry key    :
1438                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1439                       </para>
1440                       <para>Registry value :
1441                         <link linkend='Value_smbAuthType'>SMBAuthType</link>
1442                       </para>
1443                       <para>Valid values    : '0','1' or '2'</para>
1444                     </entry>
1445                   </row>
1446                   <row>
1447                     <entry>
1448                       <para>
1449                         <emphasis role='bold'>STOREANSIFILENAMES</emphasis>
1450                       </para>
1451                       <para>Registry key    :
1452                         <link linkend='Regkey_HKLM_SOFTWARE_OpenAFS_Client'>(OpenAFS Client)</link>
1453                       </para>
1454                       <para>Registry value :
1455                         <link linkend='Value_StoreAnsiFilenames'>StoreAnsiFilenames</link>
1456                       </para>
1457                       <para>Valid values    : '0' or '1'</para>
1458                       <para>This option is no longer supported as of 1.5.50 now that all file names are stored to AFS file servers using the UTF-8 encoding of Unicode.</para>
1459                     </entry>
1460                   </row>
1461                   <row>
1462                     <entry>
1463                       <para>
1464                         <emphasis role='bold'>USEDNS</emphasis>
1465                       </para>
1466                       <para>Registry key    :
1467                         <link linkend='Service_Parameters'>(Service Parameters)</link>
1468                       </para>
1469                       <para>Registry value :
1470                         <link linkend='Value_UseDNS'>UseDNS</link>
1471                       </para>
1472                       <para>Valid values    : '1' or '0'</para>
1473                     </entry>
1474                   </row>
1475                 </tbody>
1476               </tgroup>
1477             </informaltable>
1478           </section>
1479           <section>
1480             <title id='MSI_OAFW_AFSCreds_Properties'>
1481                7.2.1.2.2 AFSCreds.exe Properties
1482             </title>
1483             <para>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.</para>
1484             <informaltable frame='all'>
1485               <tgroup rowsep='1' align='left' colsep='1' cols='1'>
1486                 <colspec colwidth='447pt' colname='c1' />
1487                 <tbody>
1488                   <row>
1489                     <entry>
1490                       <para>
1491                         <emphasis role='bold'>CREDSSTARTUP</emphasis>
1492                       </para>
1493                       <para>Valid values    : '1' or '0'</para>
1494                       <para>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.</para>
1495                     </entry>
1496                   </row>
1497                   <row>
1498                     <entry>
1499                       <para>
1500                         <emphasis role='bold'>CREDSAUTOINIT</emphasis>
1501                       </para>
1502                       <para>Valid values    : '-a' or ''</para>
1503                       <para>Enables automatic initialization.</para>
1504                     </entry>
1505                   </row>
1506                   <row>
1507                     <entry>
1508                       <para>
1509                         <emphasis role='bold'>CREDSIPCHDET</emphasis>
1510                       </para>
1511                       <para>Valid values    : '-n' or ''</para>
1512                       <para>Enables IP address change detection.</para>
1513                     </entry>
1514                   </row>
1515                   <row>
1516                     <entry>
1517                       <para>
1518                         <emphasis role='bold'>CREDSQUIET</emphasis>
1519                       </para>
1520                       <para>Valid values    : '-q' or ''</para>
1521                       <para>Enables quiet mode.</para>
1522                     </entry>
1523                   </row>
1524                   <row>
1525                     <entry>
1526                       <para>
1527                         <emphasis role='bold'>CREDSRENEWDRMAP</emphasis>
1528                       </para>
1529                       <para>Valid values    : '-m' or '’</para>
1530                       <para>Enables renewing drive map at startup.</para>
1531                     </entry>
1532                   </row>
1533                   <row>
1534                     <entry>
1535                       <para>
1536                         <emphasis role='bold'>CREDSSHOW</emphasis>
1537                       </para>
1538                       <para>Valid values    : '-s' or ''</para>
1539                       <para>Enables displaying the credential manager window when AFSCREDS starts up.</para>
1540                     </entry>
1541                   </row>
1542                 </tbody>
1543               </tgroup>
1544             </informaltable>
1545           </section>
1546         </section>
1547       </section>
1548       <section>
1549         <title id='MSI_Existing_Registry_Entries'>7.2.2 Existing Registry Entries</title>
1550         <para>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).</para>
1551       </section>
1552       <section>
1553         <title id='MSI_Replacing_Configuration_Files'>7.2.3 Replacing Configuration Files</title>
1554         <para>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.</para>
1555         <para>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).</para>
1556         <para>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.</para>
1557         <para>The walkthrough below is to add a custom 'CellServDB' file.</para>
1558         <orderedlist>
1559           <listitem>
1560             <para>Disable the component that contains the configuration file that you want to replace.</para>
1561             <orderedlist>
1562               <listitem>
1563                 <para>Locate and select the 'Component' table in the 'Tables' list.</para>
1564               </listitem>
1565               <listitem>
1566                 <para>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
1567                   <link linkend='MSI_Configuration_File_Components'>7.2.3.1</link>.  For this example, the component name is 'elf_CellServDB'.
1568                 </para>
1569               </listitem>
1570               <listitem>
1571                 <para>Go to the 'Condition' column of the component.</para>
1572               </listitem>
1573               <listitem>
1574                 <para>Enter a condition that evaluates to false. I.e. 'DONOTINSTALL'. (Note that an undefined property always evaluates to false).</para>
1575                 <para>Note that you can also use this step to disable other configuration files without providing replacements.</para>
1576               </listitem>
1577             </orderedlist>
1578           </listitem>
1579           <listitem>
1580             <para>Add a new component containing the new configuration file.</para>
1581             <orderedlist>
1582               <listitem>
1583                 <para>Select the 'Component' table in the 'Tables' list.</para>
1584               </listitem>
1585               <listitem>
1586                 <para>Select 'Tables'-&gt;'Add Row' (Ctrl-R).</para>
1587               </listitem>
1588               <listitem>
1589                 <para>Enter the following :</para>
1590                 <informaltable frame='all'>
1591                   <tgroup rowsep='1' align='left' colsep='1' cols='2'>
1592                     <colspec colwidth='84pt' colname='c1' />
1593                     <colspec colwidth='318pt' colname='c2' />
1594                     <tbody>
1595                       <row>
1596                         <entry>
1597                           <para>Component</para>
1598                         </entry>
1599                         <entry>
1600                           <para>cmf_my_CellServDB</para>
1601                         </entry>
1602                       </row>
1603                       <row>
1604                         <entry>
1605                           <para>ComponentID</para>
1606                         </entry>
1607                         <entry>
1608                           <para>{7019836F-BB2C-4AF6-9463-0D6EC9035CF1}</para>
1609                         </entry>
1610                       </row>
1611                       <row>
1612                         <entry>
1613                           <para>Directory_</para>
1614                         </entry>
1615                         <entry>
1616                           <para>dirClient</para>
1617                         </entry>
1618                       </row>
1619                       <row>
1620                         <entry>
1621                           <para>Attributes</para>
1622                         </entry>
1623                         <entry>
1624                           <para>144</para>
1625                         </entry>
1626                       </row>
1627                       <row>
1628                         <entry>
1629                           <para>Condition</para>
1630                         </entry>
1631                         <entry>
1632                           <para> </para>
1633                         </entry>
1634                       </row>
1635                       <row>
1636                         <entry>
1637                           <para>KeyPath</para>
1638                         </entry>
1639                         <entry>
1640                           <para>fil_my_CellServDB</para>
1641                         </entry>
1642                       </row>
1643                     </tbody>
1644                   </tgroup>
1645                 </informaltable>
1646                 <para>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.</para>
1647                 <para>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.</para>
1648                 <para>            'fil_my_CellServDB' is a key into the 'File' table which we will fill later.</para>
1649               </listitem>
1650             </orderedlist>
1651           </listitem>
1652           <listitem>
1653             <para>Add a new feature to hold the new component.</para>
1654             <orderedlist>
1655               <listitem>
1656                 <para>Select the 'Feature' table.</para>
1657               </listitem>
1658               <listitem>
1659                 <para>Add a new row (Ctrl-R or 'Tables'-&gt;'Add Row') with the following values:</para>
1660                 <informaltable frame='all'>
1661                   <tgroup rowsep='1' align='left' colsep='1' cols='2'>
1662                     <colspec colwidth='94pt' colname='c1' />
1663                     <colspec colwidth='307pt' colname='c2' />
1664                     <tbody>
1665                       <row>
1666                         <entry>
1667                           <para>Feature</para>
1668                         </entry>
1669                         <entry>
1670                           <para>fea_my_CellServDB</para>
1671                         </entry>
1672                       </row>
1673                       <row>
1674                         <entry>
1675                           <para>Feature_Parent</para>
1676                         </entry>
1677                         <entry>
1678                           <para>feaClient</para>
1679                         </entry>
1680                       </row>
1681                       <row>
1682                         <entry>
1683                           <para>Title</para>
1684                         </entry>
1685                         <entry>
1686                           <para> </para>
1687                         </entry>
1688                       </row>
1689                       <row>
1690                         <entry>
1691                           <para>Description</para>
1692                         </entry>
1693                         <entry>
1694                           <para> </para>
1695                         </entry>
1696                       </row>
1697                       <row>
1698                         <entry>
1699                           <para>Display</para>
1700                         </entry>
1701                         <entry>
1702                           <para>0</para>
1703                         </entry>
1704                       </row>
1705                       <row>
1706                         <entry>
1707                           <para>Level</para>
1708                         </entry>
1709                         <entry>
1710                           <para>30</para>
1711                         </entry>
1712                       </row>
1713                       <row>
1714                         <entry>
1715                           <para>Directory_</para>
1716                         </entry>
1717                         <entry>
1718                           <para> </para>
1719                         </entry>
1720                       </row>
1721                       <row>
1722                         <entry>
1723                           <para>Attributes</para>
1724                         </entry>
1725                         <entry>
1726                           <para>8</para>
1727                         </entry>
1728                       </row>
1729                     </tbody>
1730                   </tgroup>
1731                 </informaltable>
1732                 <para>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.</para>
1733                 <para>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).</para>
1734                 <para>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.</para>
1735               </listitem>
1736             </orderedlist>
1737           </listitem>
1738           <listitem>
1739             <para>Join the component and the feature.</para>
1740             <orderedlist>
1741               <listitem>
1742                 <para>Select the 'FeatureComponents' table.</para>
1743               </listitem>
1744               <listitem>
1745                 <para>Add a new row with the following values:</para>
1746                 <informaltable frame='all'>
1747                   <tgroup rowsep='1' align='left' colsep='1' cols='2'>
1748                     <colspec colwidth='90pt' colname='c1' />
1749                     <colspec colwidth='312pt' colname='c2' />
1750                     <tbody>
1751                       <row>
1752                         <entry>
1753                           <para>Feature</para>
1754                         </entry>
1755                         <entry>
1756                           <para>fea_my_CellServDB</para>
1757                         </entry>
1758                       </row>
1759                       <row>
1760                         <entry>
1761                           <para>Component</para>
1762                         </entry>
1763                         <entry>
1764                           <para>cmf_my_CellServDB</para>
1765                         </entry>
1766                       </row>
1767                     </tbody>
1768                   </tgroup>
1769                 </informaltable>
1770               </listitem>
1771             </orderedlist>
1772           </listitem>
1773           <listitem>
1774             <para>Add an entry to the 'File' table.</para>
1775             <orderedlist>
1776               <listitem>
1777                 <para>Select the 'File' table.</para>
1778               </listitem>
1779               <listitem>
1780                 <para>Add a new row with the following values:</para>
1781                 <informaltable frame='all'>
1782                   <tgroup rowsep='1' align='left' colsep='1' cols='2'>
1783                     <colspec colwidth='91pt' colname='c1' />
1784                     <colspec colwidth='311pt' colname='c2' />
1785                     <tbody>
1786                       <row>
1787                         <entry>
1788                           <para>File</para>
1789                         </entry>
1790                         <entry>
1791                           <para>fil_my_CellServDB</para>
1792                         </entry>
1793                       </row>
1794                       <row>
1795                         <entry>
1796                           <para>Component_</para>
1797                         </entry>
1798                         <entry>
1799                           <para>cmf_my_CellServDB</para>
1800                         </entry>
1801                       </row>
1802                       <row>
1803                         <entry>
1804                           <para>FileName</para>
1805                         </entry>
1806                         <entry>
1807                           <para>CellServDB</para>
1808                         </entry>
1809                       </row>
1810                       <row>
1811                         <entry>
1812                           <para>FileSize</para>
1813                         </entry>
1814                         <entry>
1815                           <para>(enter file size here)</para>
1816                         </entry>
1817                       </row>
1818                       <row>
1819                         <entry>
1820                           <para>Attributes</para>
1821                         </entry>
1822                         <entry>
1823                           <para>8192</para>
1824                         </entry>
1825                       </row>
1826                       <row>
1827                         <entry>
1828                           <para>Sequence</para>
1829                         </entry>
1830                         <entry>
1831                           <para>1000</para>
1832                         </entry>
1833                       </row>
1834                     </tbody>
1835                   </tgroup>
1836                 </informaltable>
1837                 <para>                (leave other fields blank)</para>
1838                 <para>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.</para>
1839                 <para>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.</para>
1840               </listitem>
1841             </orderedlist>
1842           </listitem>
1843           <listitem>
1844             <para>Set a media source for the file.</para>
1845             <orderedlist>
1846               <listitem>
1847                 <para>Select the 'Media' table.</para>
1848               </listitem>
1849               <listitem>
1850                 <para>Add a row with the following values :</para>
1851                 <informaltable frame='all'>
1852                   <tgroup rowsep='1' align='left' colsep='1' cols='2'>
1853                     <colspec colwidth='93pt' colname='c1' />
1854                     <colspec colwidth='309pt' colname='c2' />
1855                     <tbody>
1856                       <row>
1857                         <entry>
1858                           <para>DiskId</para>
1859                         </entry>
1860                         <entry>
1861                           <para>2</para>
1862                         </entry>
1863                       </row>
1864                       <row>
1865                         <entry>
1866                           <para>LastSequence</para>
1867                         </entry>
1868                         <entry>
1869                           <para>1000</para>
1870                         </entry>
1871                       </row>
1872                     </tbody>
1873                   </tgroup>
1874                 </informaltable>
1875                 <para>                (leave other fields blank)</para>
1876                 <para>The sequence number of 1000 designates this as the media source for the newly added file.
1877         </para>
1878               </listitem>
1879             </orderedlist>
1880           </listitem>
1881         </orderedlist>
1882         <section>
1883           <title id='MSI_Configuration_File_Components'>7.2.3.1 Components for Configuration Files</title>
1884           <para>CellServDB: 'cpf_CellServDB' (ID {D5BA4C15-DBEC-4292-91FC-B54C30F24F2A})</para>
1885         </section>
1886       </section>
1887       <section>
1888         <title id='MSI_Adding_Domain_Specific_Registry_Keys'>7.2.4 Adding Domain Specific Registry Keys</title>
1889         <para>Following is an example for adding domain specific registry keys.</para>
1890         <para>    Refer to
1891           <link linkend='appendix_a'>Appendix A</link> section 2.1 for more information.
1892
1893
1894
1895         </para>
1896         <para>    Columns that are unspecified should be left empty.</para>
1897         <para>    We create a new feature and component to hold the new registry keys.</para>
1898         <informaltable frame='all'>
1899           <tgroup rowsep='1' align='left' colsep='1' cols='1'>
1900             <colspec colwidth='448pt' colname='c1' />
1901             <tbody>
1902               <row>
1903                 <entry>
1904                   <para>    'Feature' table:</para>
1905                 </entry>
1906               </row>
1907               <row>
1908                 <entry>
1909                   <para>            (new row)
1910             Feature            : 'feaDomainKeys'
1911             Feature Parent : 'feaClient'
1912             Display           : 0
1913             Level               : 30
1914             Attributes        : 10</para>
1915                 </entry>
1916               </row>
1917               <row>
1918                 <entry>
1919                   <para>    'Component' table:</para>
1920                 </entry>
1921               </row>
1922               <row>
1923                 <entry>
1924                   <para>            (new row)
1925             Component     : 'rcm_DomainKeys'
1926             ComponentId  : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
1927             Directory         : 'TARGETDIR'
1928             Attributes        : 4
1929             KeyPath          : 'reg_domkey0'</para>
1930                 </entry>
1931               </row>
1932               <row>
1933                 <entry>
1934                   <para>    'FeatureComponents' table:</para>
1935                 </entry>
1936               </row>
1937               <row>
1938                 <entry>
1939                   <para>            (new row)
1940             Feature            : 'feaDomainKeys'
1941             Component     : 'rcm_DomainKeys'</para>
1942                 </entry>
1943               </row>
1944               <row>
1945                 <entry>
1946                   <para>    'Registry' table:</para>
1947                 </entry>
1948               </row>
1949               <row>
1950                 <entry>
1951                   <para>            (new row)
1952             Registry          : 'reg_domkey0'
1953             Root                : 2
1954             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
1955             Component     : 'rcm_DomainKeys'</para>
1956                 </entry>
1957               </row>
1958               <row>
1959                 <entry>
1960                   <para>            (new row)
1961             Registry          : 'reg_domkey1'
1962             Root                : 2
1963             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
1964             Name              : '*'
1965             Component     : 'rcm_DomainKeys'</para>
1966                 </entry>
1967               </row>
1968               <row>
1969                 <entry>
1970                   <para>            (new row)
1971             Registry          : 'reg_domkey2'
1972             Root                : 2
1973             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
1974             Name              : '*'
1975             Component     : 'rcm_DomainKeys'</para>
1976                 </entry>
1977               </row>
1978               <row>
1979                 <entry>
1980                   <para>            (new row)
1981             Registry          : 'reg_domkey3'
1982             Root                : 2
1983             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
1984             Name              : 'LogonOptions'
1985             Value              : 1
1986             Component     : 'rcm_DomainKeys'</para>
1987                 </entry>
1988               </row>
1989               <row>
1990                 <entry>
1991                   <para>            (new row)
1992             Registry          : 'reg_domkey4'
1993             Root                : 2
1994             Key                 : SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
1995             Name              : '*'
1996             Component     : 'rcm_DomainKeys'</para>
1997                 </entry>
1998               </row>
1999               <row>
2000                 <entry>
2001                   <para>            (new row)
2002             Registry          : 'reg_domkey5'
2003             Root                : 2
2004             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
2005             Name              : 'LogonOptions'
2006             Value              : 0
2007             Component     : 'rcm_DomainKeys'</para>
2008                 </entry>
2009               </row>
2010               <row>
2011                 <entry>
2012                   <para>            (new row)
2013             Registry          : 'reg_domkey6'
2014             Root                : 2
2015             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
2016             Name              : 'FailLoginsSilently'
2017             Value              : 1
2018             Component     : 'rcm_DomainKeys'</para>
2019                 </entry>
2020               </row>
2021             </tbody>
2022           </tgroup>
2023         </informaltable>
2024         <para> </para>
2025         <para>The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable integrated logon) and 'LOCALHOST' (disable integrated logon and fail logins silently).</para>
2026       </section>
2027       <section>
2028         <title id='MSI_Adding_Site_Specific_Freelance_Registry_Keys'>7.2.5 Adding Site Specific Freelance Registry Keys</title>
2029         <para>Following is an example for adding site specific Freelance registry keys to pre-populate the Mountpoints and Symlinks in the fake root.afs volume.</para>
2030         <para>    Columns that are unspecified should be left empty.</para>
2031         <para>    We create a new feature and component to hold the new registry keys.</para>
2032         <informaltable frame='all'>
2033           <tgroup rowsep='1' align='left' colsep='1' cols='1'>
2034             <colspec colwidth='447pt' colname='c1' />
2035             <tbody>
2036               <row>
2037                 <entry>
2038                   <para>    'Feature' table:</para>
2039                 </entry>
2040               </row>
2041               <row>
2042                 <entry>
2043                   <para>            (new row)
2044             Feature            : 'feaFreelanceKeys'
2045             Feature Parent : 'feaClient'
2046             Display           : 0
2047             Level               : 30
2048             Attributes        : 10</para>
2049                 </entry>
2050               </row>
2051               <row>
2052                 <entry>
2053                   <para>    'Component' table:</para>
2054                 </entry>
2055               </row>
2056               <row>
2057                 <entry>
2058                   <para>            (new row)
2059             Component     : 'rcm_FreelanceKeys'
2060             ComponentId  : '{4E3B3CBF4-9AE7-40C3-7B09-C48CF842C583}'
2061             Directory         : 'TARGETDIR'
2062             Attributes        : 4
2063             KeyPath          : 'reg_freekey0'</para>
2064                 </entry>
2065               </row>
2066               <row>
2067                 <entry>
2068                   <para>    'FeatureComponents' table:</para>
2069                 </entry>
2070               </row>
2071               <row>
2072                 <entry>
2073                   <para>            (new row)
2074             Feature            : 'feaFreelanceKeys'
2075             Component     : 'rcm_FreelanceKeys'</para>
2076                 </entry>
2077               </row>
2078               <row>
2079                 <entry>
2080                   <para>    'Registry' table:</para>
2081                 </entry>
2082               </row>
2083               <row>
2084                 <entry>
2085                   <para>            (new row)
2086             Registry          : 'reg_freekey0'
2087             Root                : 2
2088             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'
2089             Component     : 'rcm_FreelanceKeys'</para>
2090                 </entry>
2091               </row>
2092               <row>
2093                 <entry>
2094                   <para>            (new row)
2095             Registry          : 'reg_freekey1'
2096             Root                : 2
2097             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'
2098             Name              : '0'
2099             Value              : 'athena.mit.edu#athena.mit.edu:root.cell.'
2100             Component     : 'rcm_FreelanceKeys'</para>
2101                 </entry>
2102               </row>
2103               <row>
2104                 <entry>
2105                   <para>            (new row)
2106             Registry          : 'reg_freekey2'
2107             Root                : 2
2108             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'
2109             Name              : '1'
2110             Value              : '.athena.mit.edu%athena.mit.edu:root.cell.'
2111             Component     : 'rcm_FreelanceKeys'</para>
2112                 </entry>
2113               </row>
2114               <row>
2115                 <entry>
2116                   <para>            (new row)
2117             Registry          : 'reg_freekey3'
2118             Root                : 2
2119             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
2120             Component     : 'rcm_FreelanceKeys'</para>
2121                 </entry>
2122               </row>
2123               <row>
2124                 <entry>
2125                   <para>            (new row)
2126             Registry          : 'reg_freekey4'
2127             Root                : 2
2128             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
2129             Name              : '0'
2130             Value              : 'athena:athena.mit.edu.'
2131             Component     : 'rcm_FreelanceKeys'</para>
2132                 </entry>
2133               </row>
2134               <row>
2135                 <entry>
2136                   <para>            (new row)
2137             Registry          : 'reg_freekey5'
2138             Root                : 2
2139             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
2140             Name              : '1'
2141             Value              : '.athena:.athena.mit.edu.'
2142             Component     : 'rcm_FreelanceKeys'</para>
2143                 </entry>
2144               </row>
2145             </tbody>
2146           </tgroup>
2147         </informaltable>
2148         <para>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.
2149         </para>
2150       </section>
2151     </section>
2152     <section>
2153       <title id='Additional_Resources'>7.3 Additional Resources</title>
2154       <para>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.</para>
2155       <para>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 :</para>
2156       <para>http://msdn.microsoft.com/library/en-us/msi/setup/using_transforms_to_add_resources.asp</para>
2157       <para>A sample walkthrough of adding a new configuration file is in section 2.3.</para>
2158       <para>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.</para>
2159       <para>If you are creating new components, retain the same component GUID when creating new transforms against new releases of the OpenAFS MSI package.</para>
2160       <para>After making the adjustments to the MSI database using ORCA.EXE you can generate a transform with MSITRAN.EXE as follows :</para>
2161       <para>(Modified MSI package is 'openafs-en_US_new.msi' and the original MSI package is 'openafs-en_US.msi'.  Generates transform 'openafs-transform.mst')</para>
2162       <para>    &gt; msitran.exe -g openafs-en_US.msi openafs-en_US_new.msi openafs-transform.mst</para>
2163       <para>See the Platform SDK documentation for information on command line options for MSITRAN.EXE.</para>
2164     </section>
2165     <section>
2166       <title id='Upgrades'>7.4. Upgrades</title>
2167       <para>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.</para>
2168       <para>Versions of OpenAFS that are upgraded by the MSI package are:</para>
2169       <orderedlist>
2170         <listitem>
2171           <para>OpenAFS MSI package</para>
2172           <para>Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}</para>
2173           <para>Up to current release</para>
2174         </listitem>
2175         <listitem>
2176           <para>MIT's Transarc AFS MSI package</para>
2177           <para>Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}</para>
2178           <para>Up to version 3.6.2</para>
2179         </listitem>
2180         <listitem>
2181           <para>OpenAFS NSIS package</para>
2182           <para>All versions</para>
2183         </listitem>
2184       </orderedlist>
2185       <para>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.</para>
2186       <para>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.</para>
2187       <para>When performing an upgrade with msiexec.exe execute the MSI with the repair options "vomus".</para>
2188     </section>
2189   </chapter>
2190   <chapter id='appendix_a' label='Appendix A'>
2191     <title id='Registry_Values'>Registry Values</title>
2192     <section>
2193       <title id='Service_Parameters'>A.1. Service parameters</title>
2194       <para>The service parameters primarily affect the behavior of the AFS client service (afsd_service.exe).</para>
2195       <section>
2196         <title id='Regkey_TransarcAFSDaemon_Parameters'>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</title>
2197         <section>
2198             <title id='Regkey_TransarcAFSDaemon_Parameters_LanAdapter'>Value: LanAdapter</title>
2199             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2200             <para>Type: DWORD</para>
2201             <para>Default: -1</para>
2202             <para>Variable: LANadapter</para>
2203             <para>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'.</para>
2204         </section>
2205         <section>
2206             <title id='Regkey_TransarcAFSDaemon_Parameters_CacheSize'><anchor id='Value_CacheSize' />Value: CacheSize</title>
2207             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2208             <para>Type: DWORD</para>
2209             <para>Default: 98304 (CM_CONFIGDEFAULT_CACHESIZE)</para>
2210             <para>Variable: cm_initParams.cacheSize</para>
2211             <para>Size of the AFS cache in 1k blocks.</para>
2212         </section>
2213         <section>
2214             <title id='Regkey_TransarcAFSDaemon_Parameters_ChunkSize'>Value: ChunkSize</title>
2215             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2216                   <para>Type: DWORD</para>
2217                   <para>Default: 20 (CM_CONFIGDEFAULT_CHUNKSIZE)</para>
2218                   <para>Variable: cm_logChunkSize (cm_chunkSize = 1 &lt;&lt; cm_logChunkSize)</para>
2219                   <para>Size of chunk for reading and writing. Actual chunk size is 2^cm_logChunkSize. The default chunk size is therefore 1 MB.</para>
2220                 </section>
2221                 <section>
2222                 <title id='Regkey_TransarcAFSDaemon_Parameters_Daemons'>Value: Daemons</title>
2223                   <para>
2224                     <emphasis>Value: Daemons</emphasis>
2225                   </para>
2226                   <para>Type: DWORD</para>
2227                   <para>Default: 4 (CM_CONFIGDEFAULT_DAEMONS)</para>
2228                   <para>Variable: numBkgD</para>
2229                   <para>Number of background daemons (number of threads of cm_BkgDaemon). (see cm_BkgDaemon in cm_daemon.c)</para>
2230                 </section>
2231
2232
2233                 <section>
2234             <title id='Regkey_TransarcAFSDaemon_Parameters_ServerThreads'>Value: ServerThreads</title>
2235             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2236                   <para>Type: DWORD</para>
2237                   <para>Default: 25 (CM_CONFIGDEFAULT_SVTHREADS)</para>
2238                   <para>Variable: numSvThreads</para>
2239                   <para>Number of SMB server threads (number of threads of smb_Server). (see smb_Server in smb.c).</para>
2240                 </section>
2241
2242
2243                 <section>
2244             <title id='Regkey_TransarcAFSDaemon_Parameters_Stats'>Value: Stats</title>
2245                     <anchor id='Value_Stats' />
2246             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2247                   <para>Type: DWORD</para>
2248                   <para>Default: 10000 (CM_CONFIGDEFAULT_STATS)</para>
2249                   <para>Variable: cm_initParams.nStatCaches</para>
2250                   <para>Cache configuration.</para>
2251                 </section>
2252
2253
2254                 <section>
2255             <title id='Regkey_TransarcAFSDaemon_Parameters_Volumes'>Value: Volumes</title>
2256             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2257                   <para>
2258                        Type: DWORD
2259                   </para>
2260                   <para>
2261 Default:  3333 (CM_CONFIGDEFAULT_STATS/3)
2262                   </para>
2263                   <para>
2264 Variable: cm_initParams.nVolumes</para>
2265                   <para>
2266                     <emphasis>Cache configuration.</emphasis>
2267                   </para>
2268                 </section>
2269
2270
2271                 <section>
2272             <title id='Regkey_TransarcAFSDaemon_Parameters_Cells'>Value: Cells</title>
2273             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2274                   <para>Type: DWORD
2275                   </para>
2276                   <para>
2277 Default: 1024 (CM_CONFIGDEFAULT_CELLS)
2278                   </para>
2279                   <para>
2280 Variable: cm_initParams.nCells</para>
2281                   <para>
2282                     <emphasis>Cache configuration.</emphasis>
2283                   </para>
2284                 </section>
2285
2286
2287                 <section>
2288             <title id='Regkey_TransarcAFSDaemon_Parameters_LogoffPreserveTokens'>Value: LogoffPreserveTokens</title>
2289                     <anchor id='Value_LogoffPreserveTokens' />
2290             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2291                   <para>Type: DWORD {1,0}
2292                   </para>
2293                   <para>
2294 Default : 0</para>
2295                   <para>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.</para>
2296                 </section>
2297
2298
2299                 <section>
2300             <title id='Regkey_TransarcAFSDaemon_Parameters_RootVolume'>Value: RootVolume</title>
2301             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2302                   <para>Type: REG_SZ
2303                   </para>
2304                   <para>
2305 Default: "root.afs"
2306                   </para>
2307                   <para>
2308 Variable: cm_rootVolumeName</para>
2309                   <para>Root volume name.</para>
2310                 </section>
2311
2312
2313                 <section>
2314             <title id='Regkey_TransarcAFSDaemon_Parameters_MountRoot'>Value: MountRoot</title>
2315                     <anchor id='Value_Mountroot' />
2316             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2317                   <para>Type: REG_SZ
2318                   </para>
2319                   <para>
2320 Default: "/afs"
2321                   </para>
2322                   <para>
2323 Variable: cm_mountRoot</para>
2324                   <para>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)</para>
2325                 </section>
2326
2327
2328                 <section>
2329             <title id='Regkey_TransarcAFSDaemon_Parameters_CachePath'>Value: CachePath</title>
2330                     <anchor id='Value_CachePath' />
2331             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2332                   <para>Type: REG_SZ or REG_EXPAND_SZ
2333                   </para>
2334                   <para>
2335 Default: "%TEMP%\AFSCache"
2336                   </para>
2337                   <para>
2338 Variable: cm_CachePath</para>
2339                   <para>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.</para>
2340                 </section>
2341
2342
2343                 <section>
2344             <title id='Regkey_TransarcAFSDaemon_Parameters_NonPersistentCaching'>Value: NonPersistentCaching</title>
2345                     <anchor id='Value_NonPersistentCaching' />
2346             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2347                   <para>Type: DWORD [0..1]
2348                   </para>
2349                   <para>
2350 Default: 0
2351                   </para>
2352                   <para>
2353 Variable: buf_CacheType</para>
2354                   <para>When this registry value is set to a non-zero value, the CachePath value is ignored and the cache data is stored in the windows paging file.  This disables the use of persistent caching and the ability to maintain a single UUID for the AFS client service across restarts.</para>
2355                 </section>
2356
2357
2358                 <section>
2359             <title id='Regkey_TransarcAFSDaemon_Parameters_ValidateCache'>Value: ValidateCache</title>
2360             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2361                   <para>Type: DWORD [0..2]
2362                   </para>
2363                   <para>
2364 Default: 1
2365                   </para>
2366                   <para>
2367 Variable: buf_CacheType</para>
2368                   <para>This value determines if and when persistent cache validation is performed.</para>
2369                   <para>
2370                     <simplelist>
2371                       <member>0 - Validation is disabled</member>
2372                       <member>1 - Validation is performed at startup</member>
2373                       <member>2 - Validation is performed at shutdown</member>
2374                     </simplelist>
2375                   </para>
2376                 </section>
2377
2378
2379                 <section>
2380             <title id='Regkey_TransarcAFSDaemon_Parameters_TrapOnPanic'>Value: TrapOnPanic</title>
2381             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2382                   <para>Type: DWORD {1,0}
2383                   </para>
2384                   <para>
2385 Default: 0
2386                   </para>
2387                   <para>
2388 Variable: traceOnPanic</para>
2389                   <para>Issues a breakpoint in the event of a panic. (breakpoint: _asm int 3).</para>
2390                 </section>
2391
2392
2393                 <section>
2394             <title id='Regkey_TransarcAFSDaemon_Parameters_NetbiosName'>Value: NetbiosName</title>
2395                     <anchor id='Value_NetbiosName' />
2396             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2397                   <para>Type: REG_EXPAND_SZ
2398                   </para>
2399                   <para>
2400 Default: "AFS"
2401                   </para>
2402                   <para>
2403 Variable: cm_NetbiosName</para>
2404                   <para>Specifies the NetBIOS name to be used when binding to a Loopback adapter.  To provide the old behavior specify a value of  "%COMPUTERNAME%-AFS".</para>
2405                 </section>
2406
2407
2408                 <section>
2409             <title id='Regkey_TransarcAFSDaemon_Parameters_IsGateway'>Value: IsGateway</title>
2410             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2411                   <para>Type: DWORD {1,0}
2412                   </para>
2413                   <para>
2414 Default: 0
2415                   </para>
2416                   <para>
2417 Variable: isGateway</para>
2418                   <para>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.</para>
2419                   <para>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.</para>
2420                 </section>
2421
2422
2423                 <section>
2424             <title id='Regkey_TransarcAFSDaemon_Parameters_ReportSessionStartups'>Value: ReportSessionStartups</title>
2425             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2426                   <para>Type: DWORD {1,0}
2427                   </para>
2428                   <para>
2429 Default: 0
2430                   </para>
2431                   <para>
2432 Variable: reportSessionStartups</para>
2433                   <para>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.</para>
2434                 </section>
2435
2436
2437                 <section>
2438             <title id='Regkey_TransarcAFSDaemon_Parameters_TraceBufferSize'>Value: TraceBufferSize</title>
2439                     <anchor id='Value_TraceBufferSize' />
2440             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2441                   <para>Type: DWORD
2442                   </para>
2443                   <para>
2444 Default: 10000 (CM_CONFIGDEFAULT_TRACEBUFSIZE)
2445                   </para>
2446                   <para>
2447 Variable: traceBufSize</para>
2448                   <para>Number of entries to keep in trace log.</para>
2449                 </section>
2450
2451
2452                 <section>
2453             <title id='Regkey_TransarcAFSDaemon_Parameters_SysName'>Value: SysName</title>
2454                     <anchor id='Value_SysName' />
2455             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2456                   <para>Type: REG_SZ
2457                   </para>
2458                   <para>
2459 Default: &quot;x86_win32 i386_w2k i386_nt40&quot; (X86)
2460                   </para>
2461                   <para>
2462 &quot;amd64_win64 x86_win32 i386_w2k&quot; (AMD64)
2463                   </para>
2464                   <para>
2465 Variable: cm_sysName</para>
2466                   <para>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.</para>
2467                 </section>
2468
2469
2470                 <section>
2471             <title id='Regkey_TransarcAFSDaemon_Parameters_SecurityLevel'>Value: SecurityLevel</title>
2472                     <anchor id='Value_SecurityLevel' />
2473             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2474                   <para>Type: DWORD {1,0}
2475                   </para>
2476                   <para>
2477 Default: 0
2478                   </para>
2479                   <para>
2480 Variable: cryptall</para>
2481                   <para>Enables encryption on RX calls.</para>
2482                 </section>
2483
2484
2485                 <section>
2486             <title id='Regkey_TransarcAFSDaemon_Parameters_UseDNS'>Value: UseDNS</title>
2487                     <anchor id='Value_UseDNS' />
2488             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2489                   <para>Type: DWORD {1,0}
2490                   </para>
2491                   <para>
2492 Default: 1
2493                   </para>
2494                   <para>
2495 Variable: cm_dnsEnabled</para>
2496                   <para>Enables resolving volservers using AFSDB DNS queries.</para>
2497                 </section>
2498
2499
2500                 <section>
2501             <title id='Regkey_TransarcAFSDaemon_Parameters_FreelanceClient'>Value: FreelanceClient</title>
2502                     <anchor id='Value_FreelanceClient' />
2503             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2504                   <para>Type: DWORD {1,0}
2505                   </para>
2506                   <para>
2507 Default: 0
2508                   </para>
2509                   <para>
2510 Variable: cm_freelanceEnabled</para>
2511                   <para>Enables freelance client.</para>
2512                 </section>
2513
2514
2515                 <section>
2516             <title id='Regkey_TransarcAFSDaemon_Parameters_HideDotFiles'>Value: HideDotFiles</title>
2517                     <anchor id='Value_HideDotFiles' />
2518             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2519                   <para>Type: DWORD {1,0}
2520                   </para>
2521                   <para>
2522 Default: 1
2523                   </para>
2524                   <para>
2525 Variable: smb_hideDotFiles</para>
2526                   <para>Enables marking dotfiles with the hidden attribute.  Dot files are files whose name starts with a period (excluding "." and "..").</para>
2527                 </section>
2528
2529
2530                 <section>
2531             <title id='Regkey_TransarcAFSDaemon_Parameters_MaxMpxRequests'>Value: MaxMpxRequests</title>
2532             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2533                   <para>Type: DWORD
2534                   </para>
2535                   <para>
2536 Default: 50
2537                   </para>
2538                   <para>
2539 Variable: smb_maxMpxRequests</para>
2540                   <para>Maximum number of multiplexed SMB requests that can be made.</para>
2541                 </section>
2542
2543
2544                 <section>
2545             <title id='Regkey_TransarcAFSDaemon_Parameters_MaxVCPerServer'>Value: MaxVCPerServer</title>
2546             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2547                   <para>Type: DWORD
2548                   </para>
2549                   <para>
2550 Default: 100
2551                   </para>
2552                   <para>
2553 Variable: smb_maxVCPerServer</para>
2554                   <para>Maximum number of SMB virtual circuits.</para>
2555                 </section>
2556
2557
2558                 <section>
2559             <title id='Regkey_TransarcAFSDaemon_Parameters_Cell'>Value: Cell</title>
2560                     <anchor id='Value_Cell' />
2561             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2562                   <para>Type: REG_SZ
2563                   </para>
2564                   <para>
2565 Default: &lt;none&gt;
2566                   </para>
2567                   <para>
2568 Variable: rootCellName</para>
2569                   <para>Name of root cell (the cell from which root.afs should be mounted in \\afs\all).</para>
2570                 </section>
2571
2572
2573                 <section>
2574             <title id='Regkey_TransarcAFSDaemon_Parameters_RxEnablePeerStats'>Value: RxEnablePeerStats</title>
2575             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2576                   <para>Type: DWORD {0, 1}
2577                   </para>
2578                   <para>
2579 Default: 1
2580                   </para>
2581                   <para>
2582 Variable: rx_enable_peer_stats</para>
2583                   <para>When set to 1, the Rx library collects peer statistics.</para>
2584                   <para> </para>
2585                 </section>
2586
2587
2588                 <section>
2589             <title id='Regkey_TransarcAFSDaemon_Parameters_RxEnableProcessStats'>Value: RxEnableProcessStats</title>
2590             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2591                   <para>Type: DWORD {0, 1}
2592                   </para>
2593                   <para>
2594 Default: 1
2595                   </para>
2596                   <para>
2597 Variable: rx_extra_process_stats</para>
2598                   <para>When set to 1, the Rx library collects process statistics.</para>
2599                   <para> </para>
2600                 </section>
2601
2602
2603                 <section>
2604             <title id='Regkey_TransarcAFSDaemon_Parameters_RxExtraPackets'>Value: RxExtraPackets</title>
2605             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2606                   <para>Type: DWORD
2607                   </para>
2608                   <para>
2609 Default: 120
2610                   </para>
2611                   <para>
2612 Variable: rx_extraPackets</para>
2613                   <para>When set, this number of extra Rx packets are allocated at startup.</para>
2614                 </section>
2615
2616
2617                 <section>
2618             <title id='Regkey_TransarcAFSDaemon_Parameters_RxMaxMTU'>Value: RxMaxMTU</title>
2619                     <anchor id='Value_RxMaxMTU' />
2620             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2621                   <para>Type: DWORD
2622                   </para>
2623                   <para>
2624 Default: 0
2625                   </para>
2626                   <para>
2627 Variable: rx_mtu</para>
2628                   <para>If set to anything other than 0, that value is used as the maximum send and receive MTU supported by the RX interface.</para>
2629                   <para>In order to enable OpenAFS to operate across releases of the Cisco IPSec VPN client prior than 5.0, this value must be set to 1264 or smaller.</para>
2630                 </section>
2631
2632
2633                 <section>
2634             <title id='Regkey_TransarcAFSDaemon_Parameters_RxNoJumbo'>Value: RxNoJumbo</title>
2635             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2636                   <para>Type: DWORD {0,1}
2637                   </para>
2638                   <para>
2639 Default: 0
2640                   </para>
2641                   <para>
2642 Variable: rx_nojumbo</para>
2643                   <para>If enabled, does not send or indicate that we are able to send or receive RX jumbograms.</para>
2644                 </section>
2645
2646
2647                 <section>
2648             <title id='Regkey_TransarcAFSDaemon_Parameters_ConnDeadTimeout'>Value: ConnDeadTimeout</title>
2649                     <anchor id='Value_ConnDeadTimeout' />
2650             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2651                   <para>Type: DWORD
2652                   </para>
2653                   <para>
2654 Default: 0 (seconds)
2655                   </para>
2656                   <para>
2657 Variable: ConnDeadtimeout</para>
2658                   <para>When the value is 0, this setting is configured to be one-half the HardDeadTimeout value.</para>
2659                 </section>
2660
2661
2662                 <section>
2663             <title id='Regkey_TransarcAFSDaemon_Parameters_HardDeadTimeout'>Value: HardDeadTimeout</title>
2664             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2665                   <para>Type: DWORD
2666                   </para>
2667                   <para>
2668 Default: 0 (seconds)
2669                   </para>
2670                   <para>
2671 Variable: HardDeadtimeout</para>
2672                   <para>The Hard Dead Time is enforced to be at least double the ConnDeadTimeout.  The provides an opportunity for at least one retry. </para>
2673                   <para>The value 0 seconds means that the real timeout should be set to be equal to the minimum SMB timeout which can be configured in the registry at: </para>
2674                   <para></para>
2675                   <para>  [HKLM\SYSTEM\CurrentControlSet\Services\lanmanworkstation\parameters]</para>
2676                   <para>    SessTimeout</para>
2677                   <para></para>
2678                   <para>If the minimum SMB timeout is not specified the value is 45 seconds.  See
2679                     <ulink url='http://support.microsoft.com/support/kb/articles/Q102/0/67.asp'>http://support.microsoft.com:80/support/kb/articles/Q102/0/67.asp</ulink>
2680                   </para>
2681                 </section>
2682
2683
2684                 <section>
2685             <title id='Regkey_TransarcAFSDaemon_Parameters_TraceOption'>Value: TraceOption</title>
2686                     <anchor id='Value_TraceOption' />
2687             <para>Regkey: [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]</para>
2688                   <para>Type: DWORD {0-15}
2689                   </para>
2690                   <para>
2691 Default: 0</para>
2692                   <para>Enables logging of debug output to the Windows Event Log.</para>
2693                   <para>Bit 0 enables logging of "Logon Events" processed by the Network Provider and Winlogon Event Notification Handler.  </para>
2694                   <para>Bit 1 enables logging of events captured by the AFS Client Service.</para>
2695                   <para>Bit 2 enables real-time viewing of "fs trace" logging with DbgView or similar tools.</para>
2696                   <para>Bit 3 enables "fs trace" logging on startup.</para>
2697                 </section>
2698
2699
2700                 <section>
2701             <title id='Regkey_TransarcAFSDaemon_Parameters_AllSubmount'>Value: AllSubmount</title>