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, 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, 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 must.
 153       </para>
 154       <para>
 155         In addition to these files, Wine can also optionally load from
 156         global registry files residing in the same directory as the
 157         global <filename>wine.conf</filename> (i.e.
 158         <filename>/usr/local/etc</filename> if you compiled from
 159         source). These are:
 160       </para>
 161
 162       <variablelist>
 163         <varlistentry>
 164           <term><filename>wine.systemreg</filename></term>
 165           <listitem>
 166             <para>Contains HKEY_LOCAL_MACHINE.</para>
 167           </listitem>
 168         </varlistentry>
 169         <varlistentry>
 170           <term><filename>wine.userreg</filename></term>
 171           <listitem>
 172             <para>Contains HKEY_USERS.</para>
 173           </listitem>
 174         </varlistentry>
 175       </variablelist>
 176     </sect2>
 177
 178     <sect2>
 179       <title>System administration</title>
 180
 181       <para>
 182         With the above file structure, it is possible for a system
 183         administrator to configure the system so that a system Wine
 184         installation (and applications) can be shared by all the
 185         users, and still let the users all have their own personalized
 186         configuration. An administrator can, after having installed
 187         Wine and any Windows application software he wants the users
 188         to have access to, copy the resulting
 189         <filename>system.reg</filename> and
 190         <filename>wine.userreg</filename> over to the global registry
 191         files (which we assume will reside in
 192         <filename>/usr/local/etc</filename> here), with:
 193       </para>
 194       <screen>
 195 cd ~/.wine
 196 cp system.reg /usr/local/etc/wine.systemreg
 197 cp wine.userreg /usr/local/etc/wine.userreg
 198       </screen>
 199       <para>
 200         and perhaps even symlink these back to the administrator's
 201         account, to make it easier to install apps system-wide later:
 202       </para>
 203       <screen>
 204 ln -sf /usr/local/etc/wine.systemreg system.reg
 205 ln -sf /usr/local/etc/wine.userreg wine.userreg
 206       </screen>
 207       <para>
 208         Note that the <filename>tools/wineinstall</filename> script
 209         already does all of this for you, if you install Wine as root.
 210         If you then install Windows applications while logged in as
 211         root, all your users will automatically be able to use them.
 212         While the application setup will be taken from the global
 213         registry, the users' personalized configurations will be saved
 214         in their own home directories.
 215       </para>
 216       <para>
 217         But be careful with what you do with the administrator account
 218         - if you do copy or link the administrator's registry to the
 219         global registry, any user might be able to read the
 220         administrator's preferences, which might not be good if
 221         sensitive information (passwords, personal information, etc)
 222         is stored there. Only use the administrator account to install
 223         software, not for daily work; use an ordinary user account for
 224         that.
 225       </para>
 226     </sect2>
 227
 228     <sect2>
 229       <title>The default registry</title>
 230
 231       <para>
 232         A Windows registry contains many keys by default, and some of
 233         them are necessary for even installers to operate correctly.
 234         The keys that the Wine developers have found necessary to
 235         install applications are distributed in a file called
 236         <filename>winedefault.reg</filename>. It is automatically
 237         installed for you if you use the
 238         <filename>tools/wineinstall</filename> script, but if you want
 239         to install it manually, you can do so by using the
 240         <command>regapi</command> tool. You can find more information
 241         about this in the
 242         <filename>documentation/no-windows</filename> document in the
 243         Wine distribution.
 244       </para>
 245     </sect2>
 246
 247     <sect2>
 248       <title>The [registry] section</title>
 249
 250       <para>
 251         With the above information fresh in mind, let's look at the
 252         <filename>wine.conf</filename>/<filename>~/.wine/config</filename>
 253         options for handling the registry.
 254       </para>
 255
 256       <variablelist>
 257         <varlistentry>
 258           <term>LoadGlobalRegistryFiles</term>
 259           <listitem>
 260             <para>
 261               Controls whether to try to load the global registry
 262               files, if they exist.
 263             </para>
 264           </listitem>
 265         </varlistentry>
 266         <varlistentry>
 267           <term>LoadHomeRegistryFiles</term>
 268           <listitem>
 269             <para>
 270               Controls whether to try to load the user's registry
 271               files (in the <filename>.wine</filename> subdirectory of
 272               the user's home directory).
 273             </para>
 274           </listitem>
 275         </varlistentry>
 276         <varlistentry>
 277           <term>LoadWindowsRegistryFiles</term>
 278           <listitem>
 279             <para>
 280               Controls whether Wine will attempt to load registry data
 281               from a real Windows registry in an existing MS Windows
 282               installation.
 283             </para>
 284           </listitem>
 285         </varlistentry>
 286         <varlistentry>
 287           <term>WritetoHomeRegistryFiles</term>
 288           <listitem>
 289             <para>
 290               Controls whether registry data will be written to the
 291               user's registry files. (Currently, there is no
 292               alternative, so if you turn this off, Wine cannot save
 293               the registry on disk at all; after you exit Wine, your
 294               changes will be lost.)
 295             </para>
 296           </listitem>
 297         </varlistentry>
 298         <varlistentry>
 299           <term>UseNewFormat</term>
 300           <listitem>
 301             <para>
 302               This option is obsolete. Wine now always uses the new
 303               format; support for the old format was removed a while
 304               ago.
 305             </para>
 306           </listitem>
 307         </varlistentry>
 308         <varlistentry>
 309           <term>PeriodicSave</term>
 310           <listitem>
 311             <para>
 312               If this option is set to a nonzero value, it specifies
 313               that you want the registry to be saved to disk at the
 314               given interval. If it is not set, the registry will only
 315               be saved to disk when the wineserver terminates.
 316             </para>
 317           </listitem>
 318         </varlistentry>
 319         <varlistentry>
 320           <term>SaveOnlyUpdatedKeys</term>
 321           <listitem>
 322             <para>
 323               Controls whether the entire registry is saved to the
 324               user's registry files, or only subkeys the user have
 325               actually changed. Considering that the user's registry
 326               will override any global registry files and Windows
 327               registry files, it usually makes sense to only save
 328               user-modified subkeys; that way, changes to the rest of
 329               the global or Windows registries will still affect the
 330               user.
 331             </para>
 332           </listitem>
 333         </varlistentry>
 334       </variablelist>
 335     </sect2>
 336   </sect1>
 337
 338 <!-- Keep this comment at the end of the file
 339 Local variables:
 340 mode: sgml
 341 sgml-parent-document:("configuring.sgml" "chapter" "sect1" "")
 342 End:
 343 -->