<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      type="topic" style="task"
      id="dconf-profiles">

  <info>
    <link type="guide" xref="setup" />
    <link type="seealso" xref="dconf-custom-defaults" />
    <link type="seealso" xref="dconf" />
    <revision pkgversion="3.30" date="2019-02-22" status="incomplete"/>

    <credit type="author copyright">
      <name>Ryan Lortie</name>
      <email>[email protected]</email>
      <years>2012</years>
    </credit>
    <credit type="editor">
      <name>Jana Švárová</name>
      <email>[email protected]</email>
    </credit>
    <credit type="editor">
      <name>Petr Kovar</name>
      <email>[email protected]</email>
      <years>2019</years>
    </credit>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <desc>Detailed information about profile and profile selection.</desc>
  </info>

  <title>Profiles</title>

  <p>A <em>profile</em> is a list of configuration databases. The first
  database in a profile is the write-to database and the remaining databases
  are read-only. Each of the system databases is generated from a keyfile
  directory. Each keyfile directory contains one or more keyfiles. Each keyfile
  contains at least one dconf path and one or more keys and the corresponding
  values.</p>

  <p>Key pairs which are set in a <sys>dconf</sys> <em>profile</em> will
  override the default settings unless there is a problem with the value that
  you have set.</p>

  <p>You will usually want your <sys>dconf</sys> profile to consist of a
  <em>user database</em> and at least one system database. The profile must
  list one database per line.</p>

  <p>The first line in a profile is the database that changes are written to. It
  is usually <code>user-db:<input>user</input></code>. <input>user</input> is
  the name of the user database which can normally be found in
  <file>~/.config/dconf</file>.</p>

  <p>A <code>system-db</code> line specifies a system database. These databases
  are found in <file>/etc/dconf/db/</file>.</p>

  <example>
    <listing>
      <title>Sample profile</title>
<code its:translate="no">
user-db:user
system-db:<var>local</var>
system-db:<var>site</var>
</code>
    </listing>
  </example>

  <!-- TODO: explain the profile syntax (maybe new page) -->
  <!--TODO: explain local and site -->

  <p>Configuring a single user and multiple system databases allows for layering
  of preferences. Settings from the <code>user</code> database file take
  precedence over the settings in the <code>local</code> database file, and the
  <code>local</code> database file in turn takes precedence over the
  <code>site</code> database file.</p>

  <p>However, the order of precedence for <link xref="dconf-lockdown">locks</link>
  is reversed. Locks introduced in the <code>site</code> or <code>local</code>
  database files take priority over those present in <code>user</code>.</p>

  <note style="important">
  <p>The <sys>dconf</sys> profile for a session is determined at login, so users
  will have to log out and log in to apply a new <sys>dconf</sys> user profile
  to their session.</p>
  </note>

  <p>For more information, see the <link its:translate="no" href="man:dconf(7)">
  <cmd>dconf</cmd>(7)</link> man page.</p>

  <section id="dconf-profiles">

  <title>Select a profile</title>

  <p>On startup, <sys>dconf</sys> consults the <sys>DCONF_PROFILE</sys>
  environment variable. The variable can specify a relative path to a file in
  <file>/etc/dconf/profile/</file>, or an absolute path, for example, to the
  user's home directory.</p>

  <p>If the environment variable is set, <sys>dconf</sys> attempts to open the
  named profile and aborts if that fails. If the variable is not set,
  <sys>dconf</sys> attempts to open the profile named “user”. If that
  fails, it will fall back to an internal hard-wired configuration.</p>

  <p>For more information, see the <link its:translate="no" href="man:dconf(7)">
  <cmd>dconf</cmd>(7)</link> man page.</p>

  </section>

</page>