GConf configuration system

GConf is a system for storing application preferences. It is intended for user preferences; not configuration of something like Apache, or arbitrary data storage.

After you read this page, you might be interested in thoughts on future gconf improvements.


This page introduces GConf - read on for some simple docs and FAQs and troubleshooting information. The GConf reference manual is sort of incomplete - it can be found at http://library.gnome.org/devel/gconf/stable/. For now you should really use the version in the GConf tarball instead, it has some important updates.

There's an article about GConf at http://developer.gnome.org/feature/archive/gconf/gconf.html.


Find the latest GConf at ftp://ftp.gnome.org/pub/GNOME/sources/GConf/.

What's cool about GConf?

The root motivation for GConf is to make application preferences more manageable for system administrators. The initial GConf implementation has some shortcomings in this area; however, the client-side API should be correct, and the initial implementation is a decent first cut. See the "Future Directions" section for some ways we might improve it. We should be able to enhance the implementation without having to modify applications.

Another important motivation for GConf is that it's "process transparent." This means that if I change a setting from one application, it instantly updates in all other applications that are interested in that setting. This technology is vital for the snazzy "instant apply" UI of GNOME 2, and vital for writing applications made up of multiple out-of-process components.

The article at http://developer.gnome.org/feature/archive/gconf/gconf.html goes into some more detail on some of this.

Introduction to GConf

Here are some quick-and-easy docs with some key points everyone should know.

GConf involves a few new concepts, but no rocket science. Essentially GConf provides a preferences database, which is like a simple filesystem. The filesystem contains keys organized into a hierarchy. Each key is either a directory containing more keys, or has a value. For example, the key /apps/metacity/general/titlebar_font contains an integer value giving the size of the titlebar font for the Metacity window manager.

GConf comes with a command line tool called gconftool-1 (for version 1) or gconftool-2 (for version 2) that you can use to get an idea what's going on. Try this command:

    $ gconftool-2 -R /desktop/gnome

That will display some of the GNOME 2 desktop settings if you've installed GNOME 2.

Configuration Sources

GConf looks for each value in a series of storage locations called configuration sources. These are specified in a file called /etc/gconf/<version>/path. Each configuration source has a backend that knows how to read it - for now, this is always the "xml" backend, which stores data in XML files.

By default, GConf comes configured as follows:

   include "$(HOME)/.gconf.path"

If a value is set in the first source, which is read only, then users can't delete that value, and thus can't set a value of their own. These settings become mandatory for all users.

The "include" line allows users to insert their own configuration sources into the search path by creating a file in their home directory called .gconf.path.

The readwrite source ~/.gconf is where user settings are normally written.

The last source is where schemas are usually stored - see the next section. A different default schema source can be specified by creating the file /etc/gconf/schema-install-source; this file changes the return value of gconftool-2 --get-default-source, which causes applications and RPM/deb packages to install schemas to the new source.

In addition to $(HOME), the variable $(USER) can be used, and any variable $(ENV_FOO) will be replaced by the value of the environment variable FOO. So $(ENV_DISPLAY) might be handy, for example.


Keys normally have simple values such as integers, strings, or lists of those. However, a special kind of value called a schema can also be stored in GConf.

A schema is a bundle of metainformation describing a configuration setting. This metainformation includes the type of value, short documentation on the setting, and the factory default for that value. Schemas are conventionally stored in the database under the /schemas toplevel directory.

For example:

    $ gconftool-2 --get /schemas/apps/metacity/general/num_workspaces
    Type: int
    List Type: *invalid*
    Car Type: *invalid*
    Cdr Type: *invalid*
    Default Value: 4
    Owner: metacity
    Short Desc: Number of workspaces
    Long Desc: 
              Number of workspaces. Must be more than zero, and 
              has a fixed maximum (to prevent accidentally destroying 
              your desktop by asking for 34 million workspaces).

If the "Type:" field is "list", then the "List Type:" field will be "integer" or the like indicating that the list is a list of integers. Similarly, if the "Type:" field is "pair", then types of the first and second members of the pair are given as "Car Type:" and "Cdr Type:" (the names are an odd Lisp inheritance).

Note the "Default Value:" and documentation fields.

Keys can have a schema name associated with them. For example, the above schema name is associated with the key /apps/metacity/general/num_workspaces; you can check this with gconftool:

    $ gconftool-2 --get-schema-name /apps/metacity/general/num_workspaces

Note that by convention, the schema for a key is obtained by prefixing the key with /schemas/ - but this is only a convention. The convention can't be followed when multiple keys need to share the same schema, which happens from time to time.

When a key's value has not been set by the user, GConf will fall back to the factory default in the key's schema. So if /apps/metacity/general/num_workspaces has not been set, the default value of "4" would be used.

Schema files

Application developers create files called schema files, traditionally ending in the .schemas extension. These are in a nice human-readable format.

These files are not used by GConf directly. Instead, when you "make install" or install an RPM/deb package, gconftool can be invoked to take the schemas in the schema file for an application and install them into one of the configuration sources. The schema install process also associates schema names with keys, so GConf can find the right schema for a given key.

Conventionally, schema files are also placed in /etc/gconf/schemas/; this is primarily for the convenience of system administrators, who can use these files to initialize a newly-created configuration source. If the schema files weren't installed, then creating a new configuration source would require reinstalling all applications.

Applications and RPM/deb packages install to the config source returned by gconftool-2 --get-default-source; this source can be overridden by placing a different source address in the file /etc/gconf/schema-install-source.

GConf per-user daemon (gconfd)

The current GConf implementation involves a per-user daemon. This daemon's primary purpose is to notify applications when a configuration value has changed. As a secondary task, it caches values, so each application doesn't have to parse XML files.

The daemon normally exits a couple of minutes after the last application using it has exited.

Since the daemon caches values it may not notice when new schemas are installed from "make install" or an RPM/deb package. However, it is possible to notify the daemon to re-load its caches by sending it a SIGHUP signal.

Application developer information

Be sure to read the key naming conventions in the reference manual. In particular, your application should place its preferences under a /apps/myappname directory, and keys should be named in all lowercase with underscores separating words.

Avoid placing values directly below /apps/myappname. Instead, create subdirectories that divide up the values into logical groups. This will make GConf internals more efficient, and will also allow you to listen for changes with finer granularity.

Always use a model-view architecture with GConf; i.e. don't change the state of your application except in response to preference change notifies.

Do not store anything but preferences in GConf. Documents, session state, random data blobs do not belong in GConf. Stuff breaks if you do this. Moreover, THERE IS NO GUARANTEE THAT IT'S EVEN POSSIBLE TO WRITE TO THE GCONF DATABASE. Which means you may not use GConf as an IPC mechanism or when it's required to be able to store a piece of data.

Use GConfClient, not GConfEngine directly.

Your application should not allow the user to change any key for which gconf_client_key_is_writable() returns FALSE. If you're feeling elaborate, you can recheck this flag anytime you receive a notify (call gconf_entry_get_is_writable() on the entry in the notification).

To test that you're handling non-writable keys correctly, edit /etc/gconf/1/path or /etc/gconf/2/path and comment out the line with the "readwrite" storage location, then use gconftool-2 --shutdown to restart gconfd, then restart your app and see how it works.

Values received from GConf are UNTRUSTED, just as if they came from a file on disk. You need to check the validity of incoming values, including the value type. Use gconftool --break-key to verify that your application is robust. When you get an invalid value, the right thing to do is usually nothing; just keep the value you were using prior to notification of the new one.

As a rule of thumb, NEVER modify a GConf key in response to receiving a notification from GConf. This is a recipe for infinite loops and generally indicates a conceptual/design problem as well.

To install schemas, your Makefile.am should have something like:

    schemadir   = @GCONF_SCHEMA_FILE_DIR@
    schema_DATA = metacity.schemas

      GCONF_CONFIG_SOURCE=$(GCONF_SCHEMA_CONFIG_SOURCE) $(GCONFTOOL) --makefile-install-rule $(srcdir)/$(schema_DATA)

For those Makefile.am rules, you need AM_GCONF_SOURCE_2 in your configure.in.

RPM/deb packages should disable schema installation during the "make install" phase, as follows:

    make install

And then in the post-install script, run something like:

    export GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source`
    gconftool-2 --makefile-install-rule %{_sysconfdir}/gconf/schemas/metacity.schemas > /dev/null

Conventional value formats

Some kinds of value have conventional representations in the GConf database. gconf-editor will eventually have special knowledge of these formats.

Backward/forward compatibility

Here are the base rules:

To implement the rules:

If you rename a config key due to a change in possible values, you could have your app copy the old key to the new key on startup, for the case where the new key is unset. However it would be wrong to delete the old key here (because the user may still use old versions of the app simultaneously). You should only create the new key.

The reason why you need to be backward compatible is so that users don't lose their settings when they upgrade the application version. The reason why you need to be forward compatible is that many times users share the same home directory for many different computers running different OS versions or even different operating systems entirely.


GNOME has a prototype-quality unfinished program called gconf-editor which is sort of the GUI equivalent of gconftool. Try it out.


This section assumes the background information in the Introduction to GConf section above.

How do I use GConf 1 and 2 at the same time?

Things should just work - GConf 1 apps can talk to the GConf 2 daemon, and vice versa.

The tricky part is if you install GConf 1 and 2 to different prefixes. This means that by default they will use different sources to find schemas. You can fix this in several ways; one is to install the schemas for each application to both source locations, another is to edit prefix/etc/gconf/2/path to point at the same sources as prefix/etc/gconf/1/path and then create a file prefix/etc/gconf/schema-install-source containing the address of the source where you want newly-installed applications to install their schemas.

I'm having a lock file problem. What do I do?

Usually a problem here involves either NFS, or a kernel bug.

The per-user daemon locks two files in the default configuration:


The first lock is to ensure that only one gconfd is running. The second lock is to ensure only one program accesses the XML config source at a time.

If you have an NFS-mounted home directory, you must be running an rpc.statd/rpc.lockd setup on both NFS client and NFS server, so that file locking works. On Red Hat Linux, this means the "nfslock" service must be running. Enable it permanently with the chkconfig tool - see its manual page. Turn it on or off at any given time with service nfslock start or service nfslock stop. You must be root to do this.

If the kernel crashes (or the power cord gets pulled) on an NFS client machine, theoretically when you reboot the client machine it will notify the NFS server that it has rebooted and all previously-held locks should be released. However, many operating systems including Red Hat Linux 7.2 do not properly do this; so you will have stale locks after a crash. If no gconfd is running, these locks may safely be removed. If gconfd is running though, DO NOT remove them; if you have two gconfd processes for a single user, bad things may happen to that user's preferences once in a while.

See also the next question.

Can I bypass the lockfile stuff?

Red Hat Linux 8.0 contains an experimental patch that allows you to set the environment variable "GCONF_LOCAL_LOCKS=1" - do this in a script in /etc/profile.d for example. Then locks will be kept in /tmp. This has two important caveats. First, there is a security flaw where users can keep each other from logging in by creating someone else's lock file. YOU SHOULD NOT ENABLE GCONF_LOCAL_LOCKS IF THIS IS A PROBLEM FOR YOUR SITE. However, it's "only" a denial of service attack, and the user would have to leave the problem-causing file owned by themselves, so you could track them down and get angry. Second, preferences notification won't work between machines; you will get "last machine to write preferences wins" behavior instead of "state is shared" behavior. You can probably live with that.

This patch will probably be in GNOME 2.2, ideally with the denial-of-service issue fixed.

How do I log in from two machines at once?

You can only have one gconfd accessing a given configuration source at the same time. This means you need to share the same gconfd between the two machines.

This Just Works, with two common catches:

To enable remote CORBA connections, add the line "ORBIIOPIPv4=1" to /etc/orbitrc and then restart gconfd using gconftool-2 --shutdown.

How can I see log messages from gconfd?

If you're having gconf problems, the first step is to see if gconfd is printing error messages. To do this, you need to look at the user.* level of syslog. Red Hat Linux has this level of logging turned off by default, other systems have it enabled. If you don't have it by default, add a line like this to /etc/syslog.conf:

 user.* /var/log/user

Then run a command such as service syslog restart to reload the config file. At that point /var/log/user will begin to log gconfd messages.

To put gconfd in hugely verbose mode, you can send it the USR1 signal with kill -USR1 <process-id> or killall -USR1 gconfd-2. Send USR1 a second time to toggle huge verbosity back off. Note that GConf will get really, really slow when in verbose mode; syslog is not efficient.

How can I turn off log messages from gconfd?

Change where user.* messages end up. Syslog unfortunately does not let you redirect messages according to which daemon sends them, but very little other than gconfd uses user.*.

gconfd keeps me from unmounting my home directory, how can I get it to exit?

It should exit a couple of minutes after the last application using GConf has exited. You could put a "gconftool --shutdown" in your .logout script or the like, if you want it to exit sooner.

GConf should really be enhanced in the future to exit immediately when all apps using it have exited. This can only be done in GConf 2 since ORBit 2 has the required features. Patches are welcome, otherwise I'll get to it eventually.

What are some tools for debugging/profiling gconf or apps that use it?

One handy trick is to set the GCONF_DEBUG_TRACE_CLIENT environment variable when running a GConf client application. This will give copious debug output about what that client is doing.

Some other weird thing is wrong with my gconf!!!

Try shutting down gconfd (gconftool-2 --shutdown) and running the gconf-sanity-check-1 or gconf-sanity-check-2 applications - these will tell you about common problems. Also, be sure you have the latest GConf version.

If you can't figure out what's going on, mail gconf-list@gnome.org with the following information:

Before you mail, please read this whole web page.

Where do I report bugs or make suggestions?

Go to http://bugzilla.gnome.org and enter a new bug, or run the GNOME "bug-buddy" application.

DO NOT put support requests in bugzilla; mail gconf-list as noted in the previous question.

Future Directions

See this page for thoughts on future gconf improvements.