documentation/registry.sgml

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