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

  <info>
    <link type="guide" xref="setup" />
    <link type="seealso" xref="dconf" />
    <link type="seealso" xref="dconf-profiles" />
    <revision pkgversion="3.30" date="2019-02-08" status="review"/>

    <credit type="author copyright">
      <name>Ryan Lortie</name>
      <email>desrt@desrt.ca</email>
      <years>2012</years>
    </credit>
    <credit type="author">
      <name>Aruna Sankaranarayanan</name>
      <email>aruna.evam@gmail.com</email>
    </credit>
    <credit type="editor">
      <name>Petr Kovar</name>
      <email>pknbe@volny.cz</email>
      <years>2019</years>
    </credit>

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

    <desc>Use <sys its:translate="no">dconf</sys> <em>keyfiles</em> to
    configure specific settings with a text editor.</desc>
  </info>

  <title>Control system settings with keyfiles</title>

  <p>System database files, located in
  <file its:translate="no">/etc/dconf/db</file>, cannot be edited because
  they are written in GVDB format. In order to change system settings using a
  text editor, you can modify <em>keyfiles</em> found in
  <em>keyfile directories</em>. Each keyfile directory corresponds to a
  particular system database file, and has the same name as the database file
  with a “.d” extension appended (for example,
  <file>/etc/dconf/db/local.d</file>). All keyfile directories are found in
  <file its:translate="no">/etc/dconf/db</file>, and each one contains keyfiles
  in a special format that can be compiled into the
  <sys its:translate="no">dconf</sys> database.</p>

  <listing>
    <title>A keyfile in this directory will look something like this:</title>
      <code>
# Some useful default settings for our site

[system/proxy/http]
host='172.16.0.1'
enabled=true

[org/gnome/desktop/background]
picture-uri='file:///usr/local/rupert-corp/company-wallpaper.jpeg'
      </code>
  </listing>

  <note style="important">
    <p><cmd>dconf update</cmd> must be run whenever you modify a keyfile.
    When you do this, <sys its:translate="no">dconf</sys> compares the
    timestamp on a system database file with the timestamp on the corresponding
    keyfile directory. If the timestamp on the keyfile directory is more
    recent than the one on the database file,
    <sys its:translate="no">dconf</sys> regenerates the
    <code>system-db</code> file and sends a notification to the system
    <sys>D-Bus</sys>, which in turn notifies all running applications to
    reread their settings.</p>
  </note>

  <p>The group name in the keyfile references a
  <link href="https://developer.gnome.org/GSettings/">GSettings schema ID</link>.
  For example, <code>org/gnome/desktop/background</code> references the
  schema <code>org.gnome.desktop.background</code>, which contains the key
  <code>picture-uri</code>.</p>

  <p>The values under a group are expected in
  <link href="https://developer.gnome.org/glib/stable/gvariant-text.html">serialized
  GVariant form</link>.</p>

</page>