Check service database name in OpenSCManager().
[wine] / documentation / registry.sgml
1   <sect1 id="registry">
2     <title>The Registry</title>
3
4     <para>
5       After Win3.x, the registry became a fundamental part of Windows.
6       It is the place where both Windows itself, and all
7       Win95/98/NT/2000/XP/etc.-compliant applications, store
8       configuration and state data. While most sane system
9       administrators (and Wine developers) curse badly at the twisted
10       nature of the Windows registry, it is still necessary for Wine
11       to support it somehow.
12     </para>
13
14     <sect2>
15       <title>The default registry</title>
16
17       <para>
18         A Windows registry contains many keys by default, and some of
19         them are necessary for even installers to operate correctly.
20         The keys that the Wine developers have found necessary to
21         install applications are distributed in a file called
22         <filename>wine.inf</filename>. It is automatically
23         installed for you if you use the
24         <filename>tools/wineinstall</filename> script in the Wine source,
25         but if you want to install it manually, you can do so by using the
26         <command>regedit</command> tool to be found in the
27         <filename>programs/regedit/</filename>
28         directory in Wine source.
29         <filename>wine.inf</filename> is  applied even if
30         you plan to use a native Windows registry, since Wine needs some
31         specific registry settings in its registry (for special
32         workarounds for certain programs etc.).
33         This is done automatically by wine the first time you run it.
34        </para>
35     </sect2>
36
37     <sect2>
38       <title>Using a Windows registry</title>
39
40       <para>
41         If you point Wine at an existing Windows installation (by
42         setting the appropriate directories in
43         <filename>~/.wine/config</filename>, then Wine is able to load
44         registry data from it. However, Wine will not save anything to
45         the real Windows registry, but rather to its own registry
46         files (see below). Of course, if a particular registry value
47         exists in both the Windows registry and in the Wine registry,
48         then Wine will use the latter. In the Wine config file, there
49         are a number of configuration settings in the [registry] section
50         (see below) specific to the handling of Windows registry content by Wine.
51       </para>
52     </sect2>
53
54       <sect2>
55         <title>The Registry</title>
56         <para>
57           The initial default registry content to be used by the Wine
58           registry files is in the file
59           <filename>wine.inf</filename>. It contains directory
60           paths, class IDs, and more; it must be installed before most
61           <filename>INSTALL.EXE</filename> or
62           <filename>SETUP.EXE</filename> applications will work.
63         </para>
64       </sect2>
65
66     <sect2>
67       <title>Registry structure</title>
68
69       <para>
70         The Windows registry is an elaborate tree structure, and not
71         even most Windows programmers are fully aware of how the
72         registry is laid out, with its different "hives" and numerous
73         links between them; a full coverage is out of the scope of
74         this document. But here are the basic registry keys you might
75         need to know about for now.
76       </para>
77
78
79       <variablelist>
80         <varlistentry>
81           <term>HKEY_LOCAL_MACHINE</term>
82           <listitem>
83             <para>
84               This fundamental root key (in win9x it's stored in the
85               hidden file <filename>system.dat</filename>) contains
86               everything pertaining to the current Windows
87               installation.
88             </para>
89           </listitem>
90         </varlistentry>
91         <varlistentry>
92           <term>HKEY_USERS</term>
93           <listitem>
94             <para>
95               This fundamental root key (in win9x it's stored in the
96               hidden file <filename>user.dat</filename>) contains
97               configuration data for every user of the installation.
98             </para>
99           </listitem>
100         </varlistentry>
101         <varlistentry>
102           <term>HKEY_CLASSES_ROOT</term>
103           <listitem>
104             <para>
105               This is a link to HKEY_LOCAL_MACHINE\Software\Classes.
106               It contains data describing things like file
107               associations, OLE document handlers, and COM classes.
108             </para>
109           </listitem>
110         </varlistentry>
111         <varlistentry>
112           <term>HKEY_CURRENT_USER</term>
113           <listitem>
114             <para>
115               This is a link to HKEY_USERS\your_username, i.e., your
116               personal configuration.
117             </para>
118           </listitem>
119         </varlistentry>
120       </variablelist>
121     </sect2>
122
123     <sect2>
124       <title>Wine registry data files</title>
125
126       <para>
127         In the user's home directory, there is a subdirectory named
128         <filename>.wine</filename>, where Wine will try to save its
129         registry by default. It saves into four files, which are:
130       </para>
131
132       <variablelist>
133         <varlistentry>
134           <term><filename>system.reg</filename></term>
135           <listitem>
136             <para>
137               This file contains HKEY_LOCAL_MACHINE.
138             </para>
139           </listitem>
140         </varlistentry>
141         <varlistentry>
142           <term><filename>user.reg</filename></term>
143           <listitem>
144             <para>
145               This file contains HKEY_CURRENT_USER.
146             </para>
147           </listitem>
148         </varlistentry>
149         <varlistentry>
150           <term><filename>userdef.reg</filename></term>
151           <listitem>
152             <para>
153               This file contains HKEY_USERS\.Default (i.e. the default
154               user settings).
155             </para>
156           </listitem>
157         </varlistentry>
158         <varlistentry>
159           <term><filename>wine.userreg</filename></term>
160           <listitem>
161             <para>
162               Wine saves HKEY_USERS to this file (both current and
163               default user), but does not load from it, unless
164               <filename>userdef.reg</filename> is missing.
165             </para>
166           </listitem>
167         </varlistentry>
168       </variablelist>
169       <para>
170         All of these files are human-readable text files, so unlike
171         Windows, you can actually use an ordinary text editor on them
172         if you want (make sure you don't have Wine running when modifying
173         them, otherwise your changes will be discarded).
174       </para>
175       <para>
176         FIXME: global configuration currently not implemented.
177
178         In addition to these files, Wine can also optionally load from
179         global registry files residing in the same directory as the
180         global <filename>wine.conf</filename> (i.e.
181         <filename>/usr/local/etc</filename> if you compiled from
182         source). These are:
183       </para>
184
185       <variablelist>
186         <varlistentry>
187           <term><filename>wine.systemreg</filename></term>
188           <listitem>
189             <para>
190               Contains HKEY_LOCAL_MACHINE.
191             </para>
192           </listitem>
193         </varlistentry>
194         <varlistentry>
195           <term><filename>wine.userreg</filename></term>
196           <listitem>
197             <para>
198               Contains HKEY_USERS.
199             </para>
200           </listitem>
201         </varlistentry>
202       </variablelist>
203     </sect2>
204
205     <sect2>
206       <title>System administration</title>
207
208       <para>
209         With the above file structure, it is possible for a system
210         administrator to configure the system so that a system Wine
211         installation (and applications) can be shared by all the
212         users, and still let the users all have their own personalized
213         configuration. An administrator can, after having installed
214         Wine and any Windows application software he wants the users
215         to have access to, copy the resulting
216         <filename>system.reg</filename> and
217         <filename>user.reg</filename> over to the global registry
218         files (which we assume will reside in
219         <filename>/usr/local/etc</filename> here), with:
220       </para>
221   <screen>
222   cd ~/.wine
223   cp system.reg /usr/local/etc/wine.systemreg
224   cp user.reg /usr/local/etc/wine.userreg
225   </screen>
226       <para>
227         and perhaps even symlink these back to the administrator's
228         account, to make it easier to install apps system-wide later:
229       </para>
230   <screen>
231   ln -sf /usr/local/etc/wine.systemreg system.reg
232   ln -sf /usr/local/etc/wine.userreg user.reg
233   </screen>
234       <para>
235         Note that the <filename>tools/wineinstall</filename> script
236         already does all of this for you, if you install Wine source as root.
237         If you then install Windows applications while logged in as
238         root, all your users will automatically be able to use them.
239         While the application setup will be taken from the global
240         registry, the users' personalized configurations will be saved
241         in their own home directories.
242       </para>
243       <para>
244         But be careful with what you do with the administrator account
245         - if you do copy or link the administrator's registry to the
246         global registry, any user might be able to read the
247         administrator's preferences, which might not be good if
248         sensitive information (passwords, personal information, etc)
249         is stored there. Only use the administrator account to install
250         software, not for daily work; use an ordinary user account for
251         that.
252       </para>
253     </sect2>
254
255     <sect2>
256       <title>The [registry] section</title>
257
258       <para>
259         Now let's look at the <link linkend="config-file">Wine
260         configuration file</link> options for handling the registry.
261       </para>
262
263       <variablelist>
264         <varlistentry>
265           <term>GlobalRegistryDir</term>
266           <listitem>
267             <para>
268               Optional.  Sets the path to look for the Global
269               Registry.
270             </para>
271           </listitem>
272         </varlistentry>
273         <varlistentry>
274           <term>LoadGlobalRegistryFiles</term>
275           <listitem>
276             <para>
277               Controls whether to try to load the global registry
278               files, if they exist.
279             </para>
280           </listitem>
281         </varlistentry>
282         <varlistentry>
283           <term>LoadHomeRegistryFiles</term>
284           <listitem>
285             <para>
286               Controls whether to try to load the user's registry
287               files (in the <filename>.wine</filename> subdirectory of
288               the user's home directory).
289             </para>
290           </listitem>
291         </varlistentry>
292         <varlistentry>
293           <term>LoadWindowsRegistryFiles</term>
294           <listitem>
295             <para>
296               Controls whether Wine will attempt to load registry data
297               from a real Windows registry in an existing MS Windows
298               installation.
299             </para>
300           </listitem>
301         </varlistentry>
302         <varlistentry>
303           <term>WritetoHomeRegistryFiles</term>
304           <listitem>
305             <para>
306               Controls whether registry data will be written to the
307               user's registry files. (Currently, there is no
308               alternative, so if you turn this off, Wine cannot save
309               the registry on disk at all; after you exit Wine, your
310               changes will be lost.)
311             </para>
312           </listitem>
313         </varlistentry>
314         <varlistentry>
315           <term>SaveOnlyUpdatedKeys</term>
316           <listitem>
317             <para>
318               Controls whether the entire registry is saved to the
319               user's registry files, or only subkeys the user have
320               actually changed. Considering that the user's registry
321               will override any global registry files and Windows
322               registry files, it usually makes sense to only save
323               user-modified subkeys; that way, changes to the rest of
324               the global or Windows registries will still affect the
325               user.
326             </para>
327           </listitem>
328         </varlistentry>
329         <varlistentry>
330           <term>PeriodicSave</term>
331           <listitem>
332             <para>
333               If this option is set to a nonzero value, it specifies
334               that you want the registry to be saved to disk at the
335               given interval. If it is not set, the registry will only
336               be saved to disk when the wineserver terminates.
337             </para>
338           </listitem>
339         </varlistentry>
340         <varlistentry>
341           <term>UseNewFormat</term>
342           <listitem>
343             <para>
344               This option is obsolete. Wine now always uses the new
345               format; support for the old format was removed a while
346               ago.
347             </para>
348           </listitem>
349         </varlistentry>
350       </variablelist>
351     </sect2>
352   </sect1>
353
354 <!-- Keep this comment at the end of the file
355 Local variables:
356 mode: sgml
357 sgml-parent-document:("configuring.sgml" "chapter" "sect1" "")
358 End:
359 -->