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:

domain.name key

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

domain.name:path key

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

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

org.gnome.nautilus.preferences default-folder-viewer

With dconf:

/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"

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:

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:

    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:

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

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

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

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:

    # 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.8. Storing user settings over NFS

If you use GNOME on a system with NFS home directories, you must set the keyfile back end for the dconf database. Otherwise, dconf might not work correctly. With this configuration, dconf stores settings in the ~/.config/dconf-keyfile/user file.

Procedure

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

    # yum install glib2-fam

    Without this package, notifications on configuration changes made on remote machines are not displayed properly.

  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
  4. Users must log out and log back in.

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

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

$ 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

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

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

    $ gsettings monitor org.gnome.shell favorite-apps
  2. In another terminal, change the favorite-apps key:

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

    favorite-apps: ['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop']

6.9.3. Checking whether a key is writable

$ gsettings writable SCHEMA[:PATH] KEY

Example 6.6. Checking whether the favorite applications key is writable

The following key is writable:

$ gsettings writable org.gnome.shell favorite-apps

True

6.9.4. Listing the valid values for a key

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

$ 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

$ gsettings describe SCHEMA[:PATH] KEY

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

$ 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

$ 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

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

false

6.9.7. Resetting the value of a key

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

$ 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

$ gsettings reset-recursively SCHEMA[:PATH]

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

$ 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

$ gsettings list-schemas

Example 6.12. Listing installed non-relocatable schemas

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

$ 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

$ gsettings list-keys SCHEMA[:PATH]

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

$ 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

$ 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

$ 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

$ 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

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