css: some padding and margin fixes
[openafs-wiki.git] / WindowsTroubleshootingGuide.mdwn
1 # <a name="Troubleshooting Guide for _OpenA"></a> Troubleshooting Guide for [[OpenAFS]] for Windows
2
3 <div>
4   <ul>
5     <li><a href="#Troubleshooting Guide for _OpenA"> Troubleshooting Guide for OpenAFS for Windows</a><ul>
6         <li><a href="#Bugs"> Bugs</a><ul>
7             <li><a href="#Are my tokens destroyed when I l"> Are my tokens destroyed when I logout?</a></li>
8             <li><a href="#How come my non-ASCII filename c"> How come my non-ASCII filename characters are wrong; code page problems?</a></li>
9             <li><a href="#Why do my 2 GB+ files break?"> Why do my 2 GB+ files break?</a></li>
10             <li><a href="#Why does the Client Service cras"> Why does the Client Service crash when I start my laptop?</a></li>
11             <li><a href="#Why does _OpenAFS for Windows cr"> Why does OpenAFS for Windows crash on my Hyperthreaded Pentium 4?</a></li>
12           </ul>
13         </li>
14         <li><a href="#Error Messages"> Error Messages</a><ul>
15             <li><a href="#I receive a "Delayed Write failu"> I receive a "Delayed Write failure" error when saving documents from Microsoft Office to AFS volumes. What can I do?</a></li>
16             <li><a href="#I receive errors stating that th"> I receive errors stating that the AFS Client Service may not have been started; what should I do?</a></li>
17             <li><a href="#When I have obtained tokens usin"> When I have obtained tokens using Kerberos for Windows, I receive errors similar to "Ticket contained unknown key version number". What is wrong?</a></li>
18             <li><a href="#Why can't I use _OpenAFS with an"> Why can't I use OpenAFS with an Active Directory KDC?</a></li>
19             <li><a href="#Why can't I install _OpenAFS on"> Why can't I install OpenAFS on Windows NT, ME or 9x?</a></li>
20             <li><a href="#Why do I receive "AFS is still s"> Why do I receive "AFS is still starting. Retry?" messages when I have turned off "Obtain tokens at logon"?</a></li>
21             <li><a href="#What is this _MrxSmb event 3019"> What is this MrxSmb event 3019 that pops up in my System Log?</a></li>
22             <li><a href="#Why isn't the AFS Light Gateway"> Why isn't the AFS Light Gateway working anymore?</a></li>
23           </ul>
24         </li>
25         <li><a href="#Features"> Features</a><ul>
26             <li><a href="#There is only one cell listed in"> There is only one cell listed in <tt>\\AFS\all</tt> or when browsing <tt>\\AFS</tt>. Where are all my cells?</a><ul>
27                 <li><a href="#Broken Root Volume"> Broken Root Volume</a></li>
28                 <li><a href="#Freelance Mode"> Freelance Mode</a></li>
29               </ul>
30             </li>
31             <li><a href="#What happened to the files in th"> What happened to the files in the Windows directory, like <tt>afsdcell.ini</tt>, <tt>afs_freelance.ini</tt> and <tt>afsdsbmt.ini</tt>?</a></li>
32             <li><a href="#Why can I not use fs to set the"> Why can I not use <tt>fs</tt> to set the X option anymore?</a></li>
33             <li><a href="#Why should I abandon Kerberos 4?"> Why should I abandon Kerberos 4?</a></li>
34             <li><a href="#What is the difference between t"> What is the difference between the Nullsoft Installer (.exe) and the Microsoft Installer (.msi)?</a></li>
35           </ul>
36         </li>
37         <li><a href="#Nomenclature"> Nomenclature</a><ul>
38             <li><a href="#What is "Freelance Mode"?"> What is "Freelance Mode"?</a></li>
39             <li><a href="#What is "High Security Mode"?"> What is "High Security Mode"?</a></li>
40             <li><a href="#What is the Microsoft Loop Back"> What is the Microsoft Loop Back Adapter?</a></li>
41             <li><a href="#What is a "submount"?"> What is a "submount"?</a></li>
42             <li><a href="#What is "Symbol Information"?"> What is "Symbol Information"?</a></li>
43           </ul>
44         </li>
45       </ul>
46     </li>
47   </ul>
48 </div>
49
50 ## <a name="Bugs"></a> Bugs
51
52 ### <a name="Are my tokens destroyed when I l"></a> Are my tokens destroyed when I logout?
53
54 Hard to tell. If your profile is local (not on the network, roaming) there is no need for the tokens, and they are destroyed when you logout.
55
56 If, on the other hand, you are using roaming profiles, there is unfortunately no way for the AFS Client Service to know when the profile has been put back into AFS. Thus, the "roaming" could fail if the service tried to forget the tokens. When using roaming profiles, the tokens are not destroyed on logout.
57
58 ### <a name="How come my non-ASCII filename c"></a> How come my non-ASCII filename characters are wrong; code page problems?
59
60 Yes, it is. Currently, the [[OpenAFS]] implementation uses a SMB server with which Windows communicates. This server is not yet able to handle all code pages. So, if you are accessing files from other systems as well, you will experience the old code page mismatch problem.
61
62 The CIFS protocol itself has support for Unicode. Hopefully, it will be implemented in [[OpenAFS]] in the future. (from J. Altman)
63
64 ### <a name="Why do my 2 GB+ files break?"></a> Why do my 2 GB+ files break?
65
66 First of all, note that the default cache size is 20 MB, which means a 2 GB file will flush the cache directly. Second, [[OpenAFS]] does not yet support files larger than 2<sup>31</sup> bytes, which is 2 GB.
67
68 ### <a name="Why does the Client Service cras"></a> Why does the Client Service crash when I start my laptop?
69
70 If the [[OpenAFS]] Client Service cannot connect to your home cell when it starts, it will crash.
71
72 To solve this problem, look up Freelance Mode in the [[WindowsConfigurationReferenceGuide]].
73
74 ### <a name="Why does _OpenAFS for Windows cr"></a> Why does [[OpenAFS]] for Windows crash on my Hyperthreaded Pentium 4?
75
76 This is due to a known bug. Set `MaxCPUs` (type DWORD) (in `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters`) to 1. This restricts the [[OpenAFS]] Client Service to use one processor.
77
78 ## <a name="Error Messages"></a> Error Messages
79
80 ### <a name="I receive a &quot;Delayed Write failu"></a> I receive a "Delayed Write failure" error when saving documents from Microsoft Office to AFS volumes. What can I do?
81
82 Windows has support for a concept known as Overlapped I/O. It is frequently used in Microsoft Office programs. The idea is that the program sends several file read, or write, requests at once and handles them in the order they are completed. This way, writes to different locations do not have to wait for previous writes to complete. It is mostly a performance enhancement.
83
84 Unfortunately, [[OpenAFS]] for Windows currently does not handle these overlapping requests very well. You are probably better off saving to local disk and then copying into AFS.
85
86 ### <a name="I receive errors stating that th"></a> I receive errors stating that the AFS Client Service may not have been started; what should I do?
87
88 First, you should check if the service is running or not. You can do this in Control Panel\\Administration Tools\\Services. If it is not, try to start it. Won't work? File a bugreport!
89
90 You could try to login on a local account (like Administrator) and browse `\\AFS`. Check that you have RPC running.
91
92 If all fails, file a bugreport!
93
94 ### <a name="When I have obtained tokens usin"></a> When I have obtained tokens using Kerberos for Windows, I receive errors similar to "Ticket contained unknown key version number". What is wrong?
95
96 As with most things on the computer, this error message is not entirely correct. It is not neccessarily the version number of the key that is wrong. Two of the most common reasons are
97
98 - Wrong cell. You may have obtained tokens for one cell and are now trying to reach another cell. Try doing `afslog` for the new cell if you know you should have access to it.
99 - Old server. Support for [[KerberosV]] tickets is a relatively new feature of [[OpenAFS]]. You will need an [[OpenAFS]] 1.2.8 or later server to use the feature. Either update the server, or disable [[KerberosV]]. Read about the latter in the [[Configuration Reference Guide|Main/WindowsConfigurationReferenceGuide#Disable_Automatic_Use_of_KerberosV]].
100
101 ### <a name="Why can&#39;t I use _OpenAFS with an"></a> Why can't I use [[OpenAFS]] with an Active Directory KDC?
102
103 You can; however, Microsoft uses Kerberos tickets in a way no one anticipated during protocol design. While remaining syntactically valid, the tickets the AD KDC issues are very large: they can be 10 kB while other KDC implementations usually issue tickets around 500 bytes in size.
104
105 You will have to setup you AFS server to support the larger ticket sizes, or update your server.
106
107 ### <a name="Why can&#39;t I install _OpenAFS on"></a><a name="Why can&#39;t I install _OpenAFS on "></a> Why can't I install [[OpenAFS]] on Windows NT, ME or 9x?
108
109 As of version 1.3.65, the old Windows branch will no longer be maintained. The interface for the Windows NT series and the Windows 9x series are completely different. Most users now use Windows 2000 or newer. Less has changed between Windows NT 4 and Windows 2000, but the developer community has decided to discontinue support for Windows NT 4 too.
110
111 The main reason for this decision is a lack of developers and funding. [[OpenAFS]] for Windows is a free project and requires donations, or developers with time left, to move forward. Old versions of [[OpenAFS]] for Windows 9x and NT 4 are still available.
112
113 ### <a name="Why do I receive &quot;AFS is still s"></a> Why do I receive "AFS is still starting. Retry?" messages when I have turned off "Obtain tokens at logon"?
114
115 The AFS Client Service is trying to start, but is waiting for something. This may be a slow or non-existent DNS server, a faulty AFS server, or simply an unplugged cable. The important thing to know is that AFS does not have enough information to begin normal operation. Check your DNS, AFS servers and [[CellServDB]].
116
117 ### <a name="What is this _MrxSmb event 3019"></a><a name="What is this _MrxSmb event 3019 "></a> What is this [[MrxSmb]] event 3019 that pops up in my System Log?
118
119 The [[MrxSmb]] event 3019 is due to the use of the [[WindowsLoopBackAdapter]]. It can be safely ignored. (from [JSI FAQ, 3136](http://www.jsiinc.com/SUBG/TIP3100/rh3136.htm))
120
121 ### <a name="Why isn&#39;t the AFS Light Gateway"></a><a name="Why isn&#39;t the AFS Light Gateway "></a> Why isn't the AFS Light Gateway working anymore?
122
123 The Light Gateway works by simply publishing what [[OpenAFS]] has already built for internal use. If you install the [[WindowsLoopBackAdapter]], the submounts will only be published on the local computer. Either remove the Loop Back Adapter, or stop using the gateway functionality.
124
125 ## <a name="Features"></a> Features
126
127 ### <a name="There is only one cell listed in"></a> There is only one cell listed in `\\AFS\all` or when browsing `\\AFS`. Where are all my cells?
128
129 There are two possible reasons:
130
131 #### <a name="Broken Root Volume"></a> Broken Root Volume
132
133 You may have chosen the wrong default cell. Maybe that cell only has one cell mounted at the root.
134
135 #### <a name="Freelance Mode"></a> Freelance Mode
136
137 Your computer is currently using Freelance Mode. Read about that below.
138
139 ### <a name="What happened to the files in th"></a> What happened to the files in the Windows directory, like `afsdcell.ini`, `afs_freelance.ini` and `afsdsbmt.ini`?
140
141 They are gone. All INI files but one have been put into the Windows registry. Use the [[WindowsConfigurationReferenceGuide]] and `regedit` to change them.
142
143 The only file preserved is the `afsdsbmt.ini`, which is now called `CellServDB` and moved to `C:\Program Files\OpenAFS\Client\` (default location).
144
145 ### <a name="Why can I not use fs to set the"></a><a name="Why can I not use fs to set the "></a> Why can I not use `fs` to set the X option anymore?
146
147 Starting with version 1.3.65 several settings now require Administrator privileges to change them.
148
149 ### <a name="Why should I abandon Kerberos 4?"></a> Why should I abandon Kerberos 4?
150
151 A giant security hole was found in the Kerberos 4 protocol. This led the world to move over to the (already deployed) more secure Kerberos 5 protocol. The problem occurs when using trusted domains.
152
153 Recent updates to [[OpenAFS]] include support for Kerberos 5. If your cell still uses **_kaserver_** or a plain Kerberos 4 server, you should update them to use Kerberos 5. The **_kaserver_** can be seen as deprecated. The most common Kerberos 5 servers (KDCs) are [Heimdal](http://www.pdc.kth.se/heimdal/), [MIT Kerberos](http://web.mit.edu/kerberos/www/) and [Microsoft's Active Directory services](http://www.microsoft.com/).
154
155 ### <a name="What is the difference between t"></a> What is the difference between the Nullsoft Installer (.exe) and the Microsoft Installer (.msi)?
156
157 [[OpenAFS]] for Windows is distributed in two different packages. The first uses the Nullsoft Install System (NSIS) and is a stand-alone executable file. The second is the Microsoft (Windows) Installer (MSI) package, which relies on the pre-installed Microsoft Installer.
158
159 The NSIS package is preferred for computers you want to install interactively on. The dialogs are more elaborate and gives you more control when installing. On the other hand, if you are deploying on a large Windows site, you may want to do this automagically on all computers at once, thus not using an interactive interface. For this reason, the (scriptable) Microsoft Installer package was design as a common base. You can modify the steps to suit your needs.
160
161 For more information, see the [MSI Deployment Guide](http://www.openafs.org/dl/openafs/1.3.70/winnt/msi-deployment-guide.txt).
162
163 ## <a name="Nomenclature"></a> Nomenclature
164
165 ### <a name="What is &quot;Freelance Mode&quot;?"></a> What is "Freelance Mode"?
166
167 AFS was originally intended to be run on stationary office computers. It required the AFS servers to be reachable at any time. Laptop computers operate differently: users disconnect and connect their computers to different networks several times a day. This led the AFS community to invent "Freelance Mode." Since the user's default cell determines which cells will be visible to the user, a workaround was neccessary when laptops began moving around.
168
169 If you have a laptop, or will otherwise be without a connection to the servers of your default cell, you should have this enabled. If your computer can always communicate with the servers of the default cell, this mode is superfluous.
170
171 To switch Freelance Mode on and off, please read the [[Configuration Reference|Main/WindowsConfigurationReferenceGuide#Freelance_Client_Support]].
172
173 ### <a name="What is &quot;High Security Mode&quot;?"></a> What is "High Security Mode"?
174
175 It is a deprecated way of achieving a modicum of security. Before the [[OpenAFS]] for Windows client was able to use authenticated SMB connections, you had a potential security risk when more than one user was logging on to the same computer at once.
176
177 The High Security Mode created a SMB share with a random name (instead of the default <tt>\\\\machine-AFS</tt>), thus making it harder for anyone else to connect to it. There is no reason to use High Security Mode now that [[OpenAFS]] for Windows supports SMB authentication.
178
179 ### <a name="What is the Microsoft Loop Back"></a><a name="What is the Microsoft Loop Back "></a> What is the Microsoft Loop Back Adapter?
180
181 See the [[WindowsLoopBackAdapter]] page.
182
183 ### <a name="What is a &quot;submount&quot;?"></a> What is a "submount"?
184
185 A submount is used in [[OpenAFS]] for Windows to map drives. Instead of mapping drives directly to the AFS server, the [[OpenAFS]] Client uses another approach. It uses the CIFS file system as an intermediary. So, the Windows computer really thinks it maps a normal Windows share. These shares are the same thing as a submount. When you want to map a drive, the [[OpenAFS]] service creates a submount, exports it for Windows to see it, and maps the share. The submount "all" is always available and is the root of the AFS file system (`/afs` in Unix). This means you can always access any cell by writing `\\AFS\all\cell\...`.
186
187 This is a quick-and-dirty approach, but it has an upside. In Unix, the way to shorten a path is to install a symbolic link. In Windows, this is not possible. Using submounts, however, you can create shortcuts to any AFS path. Say you often use the path `/afs/openafs.org/usr/someone/development/code/openafs/src/WINNT`. Then you could create a submount (say, "openafs-nt") of it, thus reducing the path to `\\AFS\openafs-nt`.
188
189 ### <a name="What is &quot;Symbol Information&quot;?"></a> What is "Symbol Information"?
190
191 When installing [[OpenAFS]], you have the option of installing symbol information. This helps the developers track down crashes. It is only informational, and if you don't intend to send bug reports (you really should), there is no need for this feature.