Dconf is the low-level configuration system used by the GNOME desktop environment. It is basically a database, where the various configuration are stored as keys together with their values. The keys in the database can be inspected, changed, or dumped with the dconf utility or by using the dconf-editor graphical tool.
In this tutorial we see how manage dconf keys, how to backup and restore them and how to keep the database status in sync with a configuration file.
In this tutorial you will learn:
- How to list keys in the dconf database
- How to read the value of a key
- How to change the value of a key
- How to backup and restore dconf keys
- How to manage dconf with the dconf-editor GUI
| Category | Requirements, Conventions or Software Version Used |
|---|---|
| System | Distribution independent |
| Software | Dconf database, the dconf or dconf-editor utilities |
| Other | None |
| Conventions | # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux-commands to be executed as a regular non-privileged user |
Listing the keys in a database
In a dconf database, keys are organized in a “tree” structure. From the user point of view, keys are organized in directories, the root one being /. To list the content of a certain directory, we can use the dconf utility with the list command, which takes a directory as argument. To list the content of the / directory, we would run:
$ dconf list /
The command returns the following output on my machine:
org/
In the same way, to list the content of the /org/ directory, we would run:
$ dconf list /org/ gnome/ gtk/
As you can notice in the example above, the path of the directory passed as argument to the “list” command include a trailing slash. The first directory returned in the output,
gnome/, contains the keys related to the GNOME desktop environment, while gtk/ contains keys related to the GTK toolkit (the graphical toolkit used by GNOME):
$ dconf list /org/gnome/ TextEditor/ calculator/ control-center/ desktop/ evolution-data-server/ login-screen/ nautilus/ nm-applet/ settings-daemon/ shell/ system/ terminal/
Retrieving the value of a key
To retrieve a value of a key stored in the dconf database, we can use the read command of the dconf utility. Let’s an example. The picture used as the GNOME desktop environment wallpaper is stored in the /org/gnome/desktop/background/picture-uri key in dconf. To read the value of the key, we pass the its path (without trailing slash) as argument to “read” command::
$ dconf read /org/gnome/desktop/background/picture-uri
The command returns the value of the key, which in this case is:
'file:///home/egdoc/.local/share/backgrounds/2022-08-20-14-48-58-1.jpg'
Changing the value of a key
To change the value of a key stored in the dconf database, we use the write command, and pass the key path as first argument, and the value we want to assign to it, as the second one. Suppose we want to change the wallpaper used by our GNOME desktop, using a file with the following URI: 'file:///mnt/data/system/wallpapers/3.jpg'. Here is the command we would run:
$ dconf write /org/gnome/desktop/background/picture-uri "'file:///mnt/data/system/wallpapers/3.jpg'"
You may have notice that in the example above we used additional quoting for the string which indicates the path of the image to be used as wallpaper. This is because the value of a dconf key, must be provided in the GVariant format.
Backup and restore a dconf database
The dconf utility provides certain commands which can be used to create and restore a backup of the status of all the keys contained in a certain directory in the dconf database. Such commands are, respectively, dump and load.
The “dump” command allows us to dump the content the directory passed as its argument. By default the output of the command is sent to stdout, but it can be easily written to a file using a shell redirection. Supposing we want to backup the content of the entire database, and store it in the dconf_backup.txt file, we would run:
$ dconf dump / > dconf_backup.txt
Here is an example of how the dump is organized:
[org/gnome/TextEditor] indent-style='space' last-save-directory='file:///home/egdoc/Downloads' show-line-numbers=true spellcheck=false tab-width=uint32 2 wrap-text=false [...]
The “load” command performs the opposite operation, letting us populate the dconf database with the values read from its standard input. It accepts the path of the directory to restore as its sole argument. To restore the configuration we stored in the dconf_backup.txt file in the previous example, we would run:
$ dconf load / < dconf_backup.txt
Keeping the dconf setup in sync with a configuration file
The strategy we used to create a dconf backup in the previous example is not very convenient: each time we perform a modification to our configuration, we must re-create the dump again to keep the “backup” up to date. An alternative strategy is to keep the dconf configuration synchronized with a text file. Here is how we can implement it.
The first thing to do is to add the
service-db:keyfile/user line at the beginning of the /etc/dconf/profile/user file, which, after the modification, should look like this:
service-db:keyfile/user user-db:user system-db:local system-db:site system-db:distro
The second thing to do, is to place the file containing the dconf backup we previously created in ~/.config/dconf/user.txt, or create the dump directly in this position:
$ dconf dump / > ~/.config/dconf/user.txt
With this strategy, which will become effective once we close and open a new session (typically by logging out and performing a new login) the dconf setup will be read from the aforementioned file and the modifications we made to the keys in the database, will be automatically written to it. This setup is particularly useful if we want to keep the dconf configuration under version control, like
we do for our dotfiles, for example.
Managing dconf with the dconf-editor GUI
Until now we saw how to manage keys stored in the dconf database by using the dconf command line utility. If we prefer to use a graphical tool to perform the same operations, we can use dconf-editor, which is included in the repositories of all the major Linux distributions. To install it on Fedora, we run:
$ sudo dnf install dconf-editor
On Debian and Debian-based distributions, instead:
$ sudo apt install dconf-editor
The package is included in the Archlinux “extra” repository. On the rolling distribution we can install it with the following command:
$ sudo pacman -Sy dconf-editor
The first time we launch the application, we are warned to use it with care:
From the application interface, as you can observe in the screenshot below, we can easily navigate the various directories, change the key values and even bookmark the most frequently used locations by clicking on the “star” button, in order to access them faster:
Conclusions
In this article we saw how to manage settings and options stored in the dconf database, which is used by the GNOME desktop environment. We saw how to use the dconf command line utility to list existing keys, retrieve and change their values and create/restore a backup of the dconf database. We also saw how to keep the dconf status it in sync with a textual configuration file. Finally, we saw how to manage the dconf database via the dconf-editor graphical application.
