Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Configuring GNOME at low level

6.1. Introduction to configuring GNOME

The following components store settings in the GNOME desktop environment:

GSettings
A high-level API for GNOME application settings.
The dconf database
A key-based Binary Large Object (BLOB) database for storing GNOME configurations. It manages user settings such as GDM, application, and proxy settings, and serves as the back end for GSettings.

You can view and edit GSettings values using either of the following tools:

The dconf-editor graphical application
The dconf-editor provides a GUI for browsing the settings and their editing. It presents the hierarchy of settings in a tree-view and also displays additional information about each setting, including the description, type and default value.
The gsettings command-line utility
The gsettings utility can be used to display and set dconf values. The gsettings utility supports Bash completion for commands and settings. This tools also enables you to automate configuration in shell scripts.
The dconf command-line utility

A command-line utility which is used for reading and writing individual values or entire directories from and to a dconf database.

Warning

As a user or application developer, do not use the dconf utility directly.

To manipulate dconf values, always use the dconf editor application or the gsettings utility.

The only exception to use dconf directly is when setting system-wide default configurations, because the other tools do not allow to manipulate such configurations.

These tools share the following features:

  • Browsing and changing options for system and application preferences
  • Changing preferences
  • Running by regular users, because both tools are intended to browse and modify the current user’s GSettings database

Figure 6.1. dconf editor showing the org.gnome.desktop.background keys

dconf editor screenshot new

6.2. GSettings schemas and keys

The GSettings database stores all settings in a tree of schemas and keys:

  • A key stores a particular value of a setting.
  • A schema defines a group and subgroups of related settings, including a summary and description of each setting and its default value.

Usually, there is a specific, well-known path associated with each schema in the GSettings database. However, in some situations schemas are relocatable, so that they can be applied to more than one path in the GSettings database. A relocatable schema can have an arbitrary number of instances. For example, this is useful if the schema describes an account, and you want to be able to store a arbitrary number of accounts in GSettings.

A schema path usually refers to a domain name associated with the configured program or library.

The gsettings utility specifies schemas and keys in a format where the key is separated with a space:

Copy to Clipboard Toggle word wrap 
domain.name key

If a schema is relocatable, you must also specify a path after the schema name:

Copy to Clipboard Toggle word wrap 
domain.name:path key

The dconf utility specifies schemas and keys as a single slash-separated string:

Copy to Clipboard Toggle word wrap 
/domain/name/key

Example 6.1. The folder view setting in Files

You can access the setting that controls the folder view in the Files application using the following format.

With gsettings:

Copy to Clipboard Toggle word wrap 
org.gnome.nautilus.preferences default-folder-viewer

With dconf:

Copy to Clipboard Toggle word wrap 
/org/gnome/nautilus/preferences/default-folder-viewer

6.3. GSettings values

Each GSettings key stores the value of a particular setting as a GVariant data type. To modify the value of a key, you must specify the value in the GVariant text format.

GVariant supports the following data types:

Data typeGVariant text format examples

Boolean

  • true
  • false

String

  • 'option1'
  • "option2"

Number

  • 5
  • 37.5
  • 3.75e1

Tuple

  • ("hello", 42)

Array

  • [1, 2, 3]

Dictionary

  • {1: "one", 2: "two", 3: "three"}

Variant

  • [<"hello">, <42>]

Maybe

  • just 'hello'
  • nothing

Byte string

  • b’abc'
  • b"abc"

Additional resources

6.4. Managing user and system GNOME settings

The dconf database provides several levels of control over GNOME configuration for system administrators and users:

  • Administrators can define default settings that apply to all users.
  • Users can override the defaults with their own settings.
  • Administrators can also lock settings to prevent users from overriding them.

6.5. dconf profiles

A dconf profile is a list of system’s hardware and software configuration databases, which the dconf system collects.

The dconf profiles enable you to compare identical systems to troubleshoot hardware or software problems.

The dconf system stores its profiles in the text files that can be located either within the /etc/dconf/profile/ directory or elsewhere. The $DCONF_PROFILE environment variable can specify a relative path to the file from /etc/dconf/profile/, or an absolute path, such as in a user’s home directory.

Note that key pairs that are set in a dconf profile override the default settings.

On startup, dconf consults the $DCONF_PROFILE environment variable to find the name of the dconf profile to open. The result depends on whether the variable is set or not:

  • If set, dconf attempts to open the profile named in the variable and aborts if this step fails.
  • If not set, dconf attempts to open the profile named user and uses an internal hard-wired configuration if this step fails.

Each line in a dconf profile specifies one dconf database.

The first line indicates the database used to write changes. The remaining lines show read-only databases.

The following is a sample profile stored in /etc/dconf/profile/user:

Copy to Clipboard Toggle word wrap 
user-db:user
system-db:local
system-db:site

In this example, the dconf profile specifies three databases:

user
The name of the user database that can be found in ~/.config/dconf
local and site
System databases, located in /etc/dconf/db/
Note

To apply a new dconf user profile to the user’s session, you need to log out and log in, because the dconf profile for a session is determined at login.

6.6. Configuring custom default values

You can set machine-wide default settings by providing a default for a key in a dconf profile. Users can override these defaults.

Procedure

  1. Identify the GSettings schemas, keys, and allowed values of the settings that you want to configure.

    You cna either use the dconf editor application or the gsettings utility. For details on gsettings, see Working with GSettings keys on command line.

  2. Ensure that the /etc/dconf/profile/user configuration file enables the user profile:

    Copy to Clipboard Toggle word wrap 
    user-db:user
system-db:local

  3. Create a plain text keyfile for the default settings in the /etc/dconf/db/local.d/ directory.

    Choose a file name that represents the settings. The file name usually starts with a number, such as /etc/dconf/db/local.d/01-background.

  4. In the keyfile, specify the default settings in the following format:

    Copy to Clipboard Toggle word wrap 
    [path/to/schema]
key-name=value
another-key-name=another-value
    Important

    Separate the schema components with a slash (/), not a dot (.) here.

    Example 6.2. A default background

    For example, to set a default desktop background, specify the following configuration in /etc/dconf/db/local.d/01-background:

    Copy to Clipboard Toggle word wrap 
    [org/gnome/desktop/background]
picture-uri='file:///usr/local/share/backgrounds/wallpaper.jpg'
    1 
    
picture-options='scaled'
    2 
    
primary-color='000000'
    3 
    
secondary-color='FFFFFF'
    4
    1
    URI to use for the background image. Note that the backend only supports local file:// URIs.
    2
    Determines how the image set by wallpaper_filename is rendered.
    3
    Left or Top color when drawing gradients, or the solid color.
    4
    Right or Bottom color when drawing gradients, not used for solid color.

  5. Update the system databases:

    Copy to Clipboard Toggle word wrap 
    # dconf update
  6. The user must log out and log in again for the changes to take effect.

Additional resources

  • If you want to avoid creating a user profile, you can use the dconf utility to read and write individual values or entire directories from and to a dconf database. For more information, see the dconf(1) man page on your system.

6.7. Locking down specific settings

By default, any settings that users make take precedence over the system settings. Therefore, users can override the system settings with their own. Using the lockdown mode in dconf, you can prevent users from changing specific settings.

Procedure

  1. Create the /etc/dconf/db/local.d/locks/ directory.
  2. In this directory, add any number of files listing keys that you want to lock.

Example 6.3. Locking the settings for the default wallpaper

  1. Set a default wallpaper.
  2. Create the /etc/dconf/db/local.d/locks/ directory.

  3. Create the /etc/dconf/db/local.d/locks/00-default-wallpaper file with the following content, listing one key per line:

    Copy to Clipboard Toggle word wrap 
    # Prevent users from changing values for the following keys:
/org/gnome/desktop/background/picture-uri
/org/gnome/desktop/background/picture-options
/org/gnome/desktop/background/primary-color
/org/gnome/desktop/background/secondary-color

  4. Update the system databases:

    Copy to Clipboard Toggle word wrap 
    # dconf update

6.8. Configuring GNOME to store user settings on home directories hosted on an NFS share

If you use GNOME on a system with home directories hosted on an NFS server, you must change the keyfile backend of the dconf database. Otherwise, dconf might not work correctly.

This change affects all users on the host because it changes how dconf manages user settings and configurations stored in the home directories.

Note that the dconf keyfile backend only works if the glib2-fam package is installed. Without this package, notifications on configuration changes made on remote machines are not displayed properly.

With Red Hat Enterprise Linux 8, glib2-fam package is available in the BaseOS repository.

Prerequisites

  • The glib2-fam package is installed:

    Copy to Clipboard Toggle word wrap 
    # yum install glib2-fam

Procedure

  1. Add the following line to the beginning of the /etc/dconf/profile/user file. If the file does not exist, create it.

    Copy to Clipboard Toggle word wrap 
    service-db:keyfile/user

    With this setting, dconf polls the keyfile back end to determine whether updates have been made, so settings might not be updated immediately.

  2. The changes take effect when the users logs out and in.

6.9. Working with GSettings keys on command line

You can use the gsettings utility to configure, manipulate and manage GSettings keys. Look at the examples of use cases that involve using the gsettings utility:

6.9.1. Setting the value of a key

Copy to Clipboard Toggle word wrap 
$ gsettings set SCHEMA[:PATH] KEY VALUE

Note that the value is specified as a serialised GVariant.

If the operation succeeds, the command display no output. The change is valid immediately.

Example 6.4. Adding selected applications among your favorite applications

Copy to Clipboard Toggle word wrap 
$ gsettings set org.gnome.shell favorite-apps \
                "['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop']"

6.9.2. Monitoring key changes

To monitor a key for changes and print values that change:

Copy to Clipboard Toggle word wrap 
$ gsettings monitor SCHEMA[:PATH] [KEY]

If you do not specify the KEY argument, all keys in the schema are monitored. Monitoring continues until you stop the process.

Example 6.5. Monitoring changes of the favorite applications key

To monitor the changes in your favorite applications:

  1. Monitor the favorite-apps key:

    Copy to Clipboard Toggle word wrap 
    $ gsettings monitor org.gnome.shell favorite-apps

  2. In another terminal, change the favorite-apps key:

    Copy to Clipboard Toggle word wrap 
    $ gsettings set org.gnome.shell favorite-apps \
                "['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop']"

  3. As a result, the command in the first terminal displays a notification that the favorite-apps key has changed:

    Copy to Clipboard Toggle word wrap 
    favorite-apps: ['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop']

6.9.3. Checking whether a key is writable

Copy to Clipboard Toggle word wrap 
$ gsettings writable SCHEMA[:PATH] KEY

Example 6.6. Checking whether the favorite applications key is writable

The following key is writable:

Copy to Clipboard Toggle word wrap 
$ gsettings writable org.gnome.shell favorite-apps

True

6.9.4. Listing the valid values for a key

Copy to Clipboard Toggle word wrap 
$ gsettings range SCHEMA[:PATH] KEY

Example 6.7. Checking the range of valid values for the remember-mount-password key

The following key stores a Boolean value:

Copy to Clipboard Toggle word wrap 
$ gsettings range org.gnome.shell remember-mount-password

type b

For more information, see GVariant Format Strings.

6.9.5. Displaying the description of a key

Copy to Clipboard Toggle word wrap 
$ gsettings describe SCHEMA[:PATH] KEY

Example 6.8. Displaying the description of the picture-uri key

Copy to Clipboard Toggle word wrap 
$ gsettings describe org.gnome.desktop.screensaver picture-uri

URI to use for the background image. Note that the backend only supports local `file://` URIs.

6.9.6. Displaying the value of a key

Copy to Clipboard Toggle word wrap 
$ gsettings get SCHEMA[:PATH] KEY

Note that the value is displayed as a serialised GVariant.

Example 6.9. Displaying value of the remember-mount-password key

Copy to Clipboard Toggle word wrap 
$ gsettings get org.gnome.shell remember-mount-password

false

6.9.7. Resetting the value of a key

Copy to Clipboard Toggle word wrap 
$ gsettings reset SCHEMA[:PATH] KEY

If resetting succeeds, the command displays no output.

Default values are stored in dconf and gsettings-desktop-schemas files.

Example 6.10. Resetting the lock-delay key to its default value

The default value of the lock-delay key is 0, and it is stored in the /usr/share/glib-2.0/schemas/org.gnome.desktop.screensaver.gschema.xml file.

Copy to Clipboard Toggle word wrap 
$ gsettings reset org.gnome.desktop.screensaver lock-delay

As a result, the value of lock-delay value is set to 0.

6.9.8. Resetting a whole schema

Copy to Clipboard Toggle word wrap 
$ gsettings reset-recursively SCHEMA[:PATH]

Example 6.11. Resetting the org.gnome.desktop.screensaver schema to its default values

Copy to Clipboard Toggle word wrap 
$ gsettings reset-recursively org.gnome.desktop.screensaver

As a result, the lock-delay value is reset to 0, and other keys within the org.gnome.desktop.screensaver schema that were changed by user are reset to their defaults as well.

6.9.9. Listing installed non-relocatable schemas

Copy to Clipboard Toggle word wrap 
$ gsettings list-schemas

Example 6.12. Listing installed non-relocatable schemas

To list all schemas installed on your system that are non-relocatable:

Copy to Clipboard Toggle word wrap 
$ gsettings list-schemas

org.gnome.rhythmbox.library
org.gnome.shell.overrides
org.gnome.system.proxy.https
org.gnome.clocks
org.gnome.eog.fullscreen
org.gnome.login-screen
org.gnome.eog.view
...

6.9.10. Listing all keys in a schema

Copy to Clipboard Toggle word wrap 
$ gsettings list-keys SCHEMA[:PATH]

Example 6.13. Listing all keys in the org.gnome.shell schema

Copy to Clipboard Toggle word wrap 
$ gsettings list-keys org.gnome.shell

enabled-extensions
command-history
remember-mount-password
always-show-log-out
had-bluetooth-devices-setup
looking-glass-history
disable-user-extensions
app-picker-view
disable-extension-version-validation
development-tools
favorite-apps
...

6.9.11. Listing all schemas nested in a schema

Copy to Clipboard Toggle word wrap 
$ gsettings list-children SCHEMA[:PATH]

Note that the list is empty if the schema contains no other schemas.

Example 6.14. Listing schemas in the org.gnome.shell schema

Copy to Clipboard Toggle word wrap 
$ gsettings list-children org.gnome.shell

keyboard org.gnome.shell.keyboard
keybindings org.gnome.shell.keybindings

6.9.12. Listing the keys and values in a schema recursively

Copy to Clipboard Toggle word wrap 
$ gsettings list-recursively [SCHEMA[:PATH]]

If you do not specify any schema, the command lists all keys within all schemas.

Example 6.15. Listing all keys and values on the system recursively

Copy to Clipboard Toggle word wrap 
$ gsettings list-recursively

org.gnome.nautilus.desktop network-icon-visible false
org.gnome.nautilus.desktop font ''
org.gnome.nautilus.desktop network-icon-name 'Network Servers'
org.gnome.nautilus.desktop home-icon-name 'Home'
org.gnome.nautilus.desktop volumes-visible true
org.gnome.Vinagre always-enable-listening false
org.gnome.Vinagre always-show-tabs false
org.gnome.Vinagre show-accels false
org.gnome.Vinagre history-size 15
org.gnome.Vinagre shared-flag true
...

6.10. Acknowledgements

Certain portions of this text first appeared in the GNOME Desktop System Administration Guide. Copyright © 2014 The GNOME Project, Michael Hill, Jim Campbell, Jeremy Bicha, Ekaterina Gerasimova, minnie_eg, Aruna Sankaranarayanan, Sindhu S, Shobha Tyagi, Shaun McCance, David King, and others. Licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

The editors of this Red Hat Enterprise Linux 8 documentation would like to thank the GNOME community members for their valuable contributions to the GNOME Desktop System Administration Guide.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.