documentation/registry.sgml

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