dconf System Administrator Guide

This page attempts to document information that system administrators are likely to find useful with respect to configuring system-wide settings with dconf. Vendors may also find this information useful for setting dconf up for system administrator customisation.

Profiles

dconf is based on the concept of a 'profile'. A profile is a list of configuration databases.

The search order for keys is not exactly the same as it was with GConf; there is no concept of a mandatory database. For key lookup, the user's personal database always takes the highest priority, followed by the system databases in the order described by the profile. To make up for the loss of mandatory databases, there is the ability to add 'locks' to system databases. If a lock for a particular key is installed into a database then no database listed above that one in the profile will be able to modify that setting. This can be used to enforce mandatory settings.

The lock system has an advantage that the installation of mandatory keys lacked: it is possible to lock entire subpaths. This way, a particular database can enforce that the schema defaults will be used without explicitly specifying every single key and its value as a mandatory key.

You can actually think of the search for a dconf key as starting in the lowest database and checking for locked keys all the way to the top level database, stopping if it finds one. If no locked keys are found then dconf searches the user's database and then back down the profile again for unlocked keys. Stated another way, locks installed into databases lower in the profile take precedence over locks installed in higher databases.

Profile Selection

On startup, dconf consults the DCONF_PROFILE environment variable. If set, dconf will attempt to open the named profile, aborting if that fails. If the environment variable is not set, dconf will attempt to open the profile named "user" and if that fails, it will fall back to an internal hard-wired configuration.

Profile Specification

dconf stores its profiles in text files. $DCONF_PROFILE can specify a relative path to the file from "/etc/dconf/profile/", or an absolute path (such as in a user's home directory). For example, the 'user' profile is stored in "/etc/dconf/profile/user". The profile name can only use alphanumeric characters or '_'.

A profile file might look like the following:

user-db:user
system-db:local
system-db:site

Each line in a profile specifies one dconf database. The first line indicates the database used to write changes, and the remaining lines indicate read-only databases. (The first line should specify a user-db, so that users can actually make configuration changes.)

A "user-db" line specifies a user database. These databases are found in ${XDG_CONFIG_HOME}/dconf/ (typically ~/.config/dconf/). The name of the file to open in that directory is exactly as it is written in the profile. In our example, "~/.config/dconf/user" would be opened. This file is expected to be in the binary dconf (GVDB) database format. Note that XDG_CONFIG_HOME cannot be set/modified per terminal or session (E.G. export XDG_CONFIG_HOME=...), because then the writer and reader would be working on different DBs (the writer is started by DBus and cannot see that variable).

A "service-db" line instructs dconf to place the binary database file for the user database in XDG_RUNTIME_DIR. Since this location is not persistent, the rest of the line instructs dconf how to store the database persistently. A typical line is service-db:keyfile/user, which tells dconf to synchronize the binary database with a plain text keyfile in ${XDG_CONFIG_HOME}/dconf/user.txt. The synchronization is bi-directional, to support multiple logins with shared NFS home directories.

A "system-db" line specifies a system database. These databases are found in /etc/dconf/db/. Again, the name of the file to open in that directory is exactly as it is written in the profile and the file is expected to be in GVDB format. In our example, the files "/etc/dconf/db/local" and "/etc/dconf/db/site" would be opened. Settings from 'local' would take priority over settings from 'site', but locks installed in 'site' would take priority over 'local' (and 'user').

For backward compatibility with previous versions of the dconf profile format, if lines do not have user-db: or system-db: specified, dconf will assume that the first line specifies a user database and the remaining lines specify system databases.

Hard-wired Default

If the DCONF_PROFILE environment variable is unset and the "user" profile can not be opened, then the effect is as if the profile was specified by this file:

user-db:user

That is, the user's personal database is consulted and there are no system settings.

Keyfile Directories

To support the ability to configure the system with a text editor, dconf has introduced keyfile directories. For any given system database, a corresponding directory can be created (with ".d" added to the filename, for example "/etc/dconf/db/local.d"). This directory contains keyfiles in a special format that can be compiled into the dconf database.

A keyfile in this directory will look something like this:

# 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'

After modifying any keyfile in one of these directories, the 'dconf update' tool should be run. This tool scans the /etc/dconf/db/ directory for databases with corresponding '.d' directories. If the timestamp on the directory is newer than the one on the file, the file is regenerated. The tool sends a notification on the system D-Bus to all running applications instructing them to re-read their settings.

Lockdown

Lockdown is supported by creating a 'locks' subdirectory in the keyfile directory (ie: /etc/dconf/db/local.d/locks). The files contained in this directory contain a list of keys to lock, one per line. Just as with the keyfiles, you may add any number of files to this directory. Here's an example of what one might look like:

# prevent changes to the company wallpaper
/org/gnome/desktop/background/picture-uri

Of course, you need to run the 'dconf update' tool after changing the locks. The tool will notice if the timestamp on the 'locks' directory has changed, so there is no need to touch the ".d" directory as well.

Summary

In summary, following the above steps, you should end up with something like the following:

==> /etc/dconf/db/site.d/00_site_settings <==
# 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'

==> /etc/dconf/db/site.d/locks/00_wallpaper <==
# prevent changes to the company wallpaper
/org/gnome/desktop/background/picture-uri

==> /etc/dconf/profile/user <==
user-db:user
system-db:site

and then you should run 'dconf update'.