Chapter 6. Configuring GNOME at low level

6.1. Introduction to configuring GNOME

To be able to configure the GNOME Desktop Environment, you need to understand these basic terms:

  • dconf
  • GSettings
  • gsettings

dconf has two different meanings.

Firstly, dconf is a key-based Binary Large Object (BLOB) database for storing GNOME configurations. dconf manages user settings such as GDM, application, and proxy settings, and serves as the back end for GSettings.

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

GSettings is a high-level API for application settings which serves as the front end for dconf.

gsettings is a command-line tool which is used to view and change user settings.

6.2. Managing user and system GNOME settings

dconf allows system administrators and users several levels of control over GNOME configuration:

  • 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.3. Displaying GSettings values for desktop applications

Viewing and editing of the GSettings values can be achieved with one of the following tools:

  • dconf-editor GUI tool
  • gsettings command-line utility

The dconf-editor application and gsettings utility have the following in common:

  • allow browsing and changing options for system and application preferences
  • allow to change preferences
  • can be run by regular users, because both tools are intended to browse and modify the current user’s GSettings database

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 utility can be used to display and set dconf values. gsettings utility supports Bash completion for commands and settings. This tools also allows you to automate configuration in shell scripts. ⁠

Figure 6.1. dconf-editor showing org.gnome.desktop.background GSettings keys

dconf editor screenshot new

Prerequisites

  • The dconf-editor is not installed on the system by default. To install it, run the following command as the root user: 

    # yum install dconf-editor

Procedure

  • To list GSettings values in the GUI, open the dconf-editor application.

  • To list a specific GSettings value on the command line, use the following command: 

    $ gsettings get schema key

    For example: 

$ gsettings get org.gnome.desktop.background picture-uri

Additional resources

  • For more information on the dconf-editor tool, see the dconf-editor(1) man page and the dconf-editor Project documentation.
  • For more information on the gsettings utility, see the gsettings(1) man page.

6.4. Using dconf profiles

The dconf system stores configuration in several different databases. You can configure dconf profiles, which specify the databases that dconf uses.

6.4.1. Introduction to dconf profiles

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

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

The dconf system stores its profiles in the text files which 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 which are set in a dconf profile override the default settings.

6.4.2. Selecting a dconf profile

On startup, dconf consults the $DCONF_PROFILE environment 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: 

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

In this example, the dconf profile specifies three databases. user is the name of the user database which can be found in ~/.config/dconf, and local and site are 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.

Warning

As a user or application developer, do not manipulate dconf directly. To manipulate dconf, always use the dconf-editor or the gsettings utility. The only exception to use dconf directly is when setting system-wide default configurations, because the aforementioned tools do not allow to manipulate such configurations.

6.5. Configuring custom default values

Machine-wide default settings can be set by providing a default for a key in a dconf profile. These defaults can be overridden by the user.

Prerequisites

  • the user profile exists
  • the value for the key was added to a dconf database

Procedure

For example, to set the default background:

  1. Create the user profile in /etc/dconf/profile/user: 

    user-db:user
system-db:local

    where local is the name of a dconf database.

  2. Create a keyfile for the local database in /etc/dconf/db/local.d/01-background, which contains the following default settings: 

    # dconf path

[org/gnome/desktop/background]

# GSettings key names and their corresponding values
picture-uri='file:///usr/local/share/backgrounds/wallpaper.jpg'
picture-options='scaled'
primary-color='000000'
secondary-color='FFFFFF'

    In the default setting of the keyfile, the following GSettings keys are used:

    Table 6.1. org.gnome.desktop.background schemas GSettings Keys

    Key NamePossible ValuesDescription

    picture-options

    "none", "wallpaper", "centered", "scaled", "stretched", "zoom", "spanned"

    Determines how the image set by wallpaper_filename is rendered.

    picture-uri

    filename with the path

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

    primary-color

    default: 000000

    Left or Top color when drawing gradients, or the solid color.

    secondary-color

    default: FFFFFF

    Right or Bottom color when drawing gradients, not used for solid color.

  3. Edit the keyfile according to your preferences.

    For more information, see Section 6.3, “Displaying GSettings values for desktop applications”.

  4. Update the system databases: 

    ~]# dconf update

When the user profile is created or changed, the user needs to log out and log in again before the changes will be applied.

Additional resources

  • If you want to avoid creating a user profile, you can use the dconf command-line 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.

6.6. Locking down specific settings

By using the lockdown mode in dconf, you can prevent users from changing specific settings.

Without enforcing the system settings using a lockdown, any settings that users make take precedence over the system settings. User can thus override the system settings with their own.

Procedure

To lock down a GSettings key:

  1. Create a locks subdirectory in the keyfile directory such as /etc/dconf/db/local.d/locks/.
  2. Add any number of files with keys that you want to lock into this directory.

Example 6.1. Locking the settings for the default wallpaper

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

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

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

    ~]# dconf update

6.7. Storing user settings over NFS

For dconf to work correctly when using Network File System (NFS) home directories, the dconf keyfile back end must be used.

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

Procedure

  1. Ensure that the glib2-fam package is installed on the system. 

    # yum install glib2-fam
  2. Create or edit the /etc/dconf/profile/user file on every client.

  3. At the very beginning of the /etc/dconf/profile/user file, add the following line: 

    service-db:keyfile/user

The dconf keyfile back end takes effect the next time that the user logs in. It polls the keyfile to determine whether updates have been made, so settings might not be updated immediately.

6.8. Setting GSettings keys properties

This section describes how to set GSettings keys properties for a single-logged user.

Each GSettings key can have only one value in a dconf database. Setting the same key to a different value at a different place of the dconf database overrides the previous value.

Values of some keys are of array type. For array type, you can specify the value of the key as a list of multiple elements separated by a comma.

To set a GSettings key of array type, follow this syntax: 

key=['option1', 'option2']

The following example shows setting of the org.gnome.desktop.input-sources.xkb-options GSettings key whose value is of array type: ⁠

Example settings of the org.gnome.desktop.input-sources.xkb-options GSettings Key

[org/gnome/desktop/input-sources]
# Enable Ctrl-Alt-Backspace for all users
# Set the Right Alt key as the Compose key and enable it
xkb-options=['terminate:ctrl_alt_bksp', 'compose:ralt']

6.9. Working with GSettings keys on command line

This section focuses on using of the gsettings command to configure, manipulate and manage the GSettings keys. The most frequent use cases that can be resolved by using the gsettings command are shown.

6.9.1. Setting key value

To set a value of a key: 

gsettings set SCHEMA [:PATH] KEY

Note that the value is specified as a serialised GVariant.

Example 6.2. Adding selected applications into the favorite applications key

To add selected applications among your favorite applications: 

$ gsettings set org.gnome.shell favorite-apps "['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop', 'shotwell.desktop', 'org.gnome.Nautilus.desktop', 'org.gnome.Software.desktop', 'yelp.desktop', 'org.gnome.Terminal.desktop', 'org.gnome.clocks.desktop']"

If the operation succeeds, no return code is shown. As a result, all listed applications are added to favorite applications. The change is valid immediately.

6.9.2. Monitoring key changes

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

gsettings monitor SCHEMA [:PATH] [KEY]

Note that if the KEY argument is not specified, all keys in the schema are monitored. Monitoring continues until the process is terminated.

Example 6.3. Monitoring changes of the favorite applications key

To monitor the changes of the favorite applications key, open two terminals and run:

In the first terminal: 

$ gsettings monitor org.gnome.shell favorite-apps

In the second terminal: 

$ gsettings set org.gnome.shell favorite-apps "['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop', 'shotwell.desktop', 'org.gnome.Nautilus.desktop', 'org.gnome.Software.desktop', 'yelp.desktop', 'org.gnome.Terminal.desktop']"

As a result, a notification whether and how favorite applications changed is displayed in the first terminal: 

favorite-apps: ['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop', 'shotwell.desktop', 'org.gnome.Nautilus.desktop', 'org.gnome.Software.desktop', 'yelp.desktop', 'org.gnome.Terminal.desktop']

6.9.3. Checking whether key is writable

To check whether a key is writable: 

gsettings writable SCHEMA [:PATH] KEY

Example 6.4. Checking whether the favorite applications key is writable

To check whether the favorite applications key is writable: 

$ gsettings writable org.gnome.shell favorite-apps

As a result, the return code shows True.

6.9.4. Checking key valid values

To check the range of valid values for a key: 

gsettings range SCHEMA [:PATH] KEY

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

To check valid values for the remember-mount-password key: 

$ gsettings range org.gnome.shell remember-mount-password

As a result, the return code displays type of the key value, which is type b in this particular case. For more information, see GNOME developer.

6.9.5. Checking description of valid key values

To check the description of valid values for a key: 

gsettings describe SCHEMA [:PATH] KEY

Example 6.6. Checking the description of valid values for the picture-uri key

To check the description of valid values for the picture-uri key: 

$ gsettings describe org.gnome.desktop.screensaver picture-uri

As a result, the following output is displayed: 

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

6.9.6. Querying key value

To get the value of a key: 

gsettings get SCHEMA [:PATH] KEY VALUE

Note that the value is displayed as a serialised GVariant.

Example 6.7. Querying value of the remember-mount-password key

To get value of the remember-mount-password key: 

$ gsettings get org.gnome.shell remember-mount-password

As a result, the return code displays false.

6.9.7. Resetting key value

To reset the value of a key: 

gsettings reset SCHEMA [:PATH] KEY

If resetting succeeds, no return code is displayed. Default values are in stored dconf and gsettings-desktop-schemas files.

Example 6.8. 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.

Users can set the value of lock-delay as needed.

For example, to set the lock-delay key for screensaver to 200: 

$ gsettings set org.gnome.desktop.screensaver lock-delay 200

To reset the lock-delay key for screensaver to its default value: 

$ 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 schema

To reset a schema: 

gsettings reset-recursively SCHEMA [:PATH]

Example 6.9. Resetting the org.gnome.desktop.screensaver schema to its defaults

To reset the org.gnome.desktop.screensaver schema to its defaults: 

$ 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

To list installed schemas that are non-relocatable: 

gsettings list-schemas [--print-paths]

If the [--print-paths] argument is specified , the path where each schema is mapped is printed as well.

Example 6.10. Listing installed non-relocatable schemas

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

$ gsettings list-schemas

As a result, a full list of schemas is returned. The following list is truncated. 

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 schema keys

To list the keys that are in the selected schema: 

gsettings list-keys SCHEMA [:PATH]

Example 6.11. Listing keys in the org.gnome.shell schema

To list keys in the org.gnome.shell schema: 

$ gsettings list-keys org.gnome.shell

As a result, a list of keys is returned. The following list is truncated. 

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 schema children

To list children of a selected schema: 

gsettings list-children SCHEMA [:PATH]

Note that the list is empty if there are no children.

Example 6.12. Listing children of the org.gnome.shell schema

To list children of the org.gnome.shell schema: 

$ gsettings list-children org.gnome.shell

As a result, the following output is returned: 

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

6.9.12. Listing schema’s keys and values

To list keys and values of a selected schema recursively: 

gsettings list-recursively [SCHEMA [:PATH]]

Note that if the schema whose keys you want to list is not specified, all keys within all schemas are listed.

Example 6.13. Listing keys and values recursively

To list keys and values in all schemas recursively: 

$ gsettings list-recursively

As a result, all key and values in all schemas on system are listed, as shown below. Note that the following list is truncated. 

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.