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 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
The dconf-editor is not installed on the system by default. To install it, run the following command as the
# yum install dconf-editor
- 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
$ gsettings get org.gnome.desktop.background picture-uri
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
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
userand 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
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
site are system databases, located in
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.
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.
- the user profile exists
- the value for the key was added to a dconf database
For example, to set the default background:
Create the user profile in
localis the name of a dconf database.
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 Name Possible Values Description
"none", "wallpaper", "centered", "scaled", "stretched", "zoom", "spanned"
Determines how the image set by wallpaper_filename is rendered.
filename with the path
URI to use for the background image. Note that the backend only supports local
Left or Top color when drawing gradients, or the solid color.
Right or Bottom color when drawing gradients, not used for solid color.
Edit the keyfile according to your preferences.
For more information, see Section 6.3, “Displaying GSettings values for desktop applications”.
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.
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
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.
To lock down a GSettings key:
Create a locks subdirectory in the keyfile directory such as
- 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
- Set a default wallpaper.
Create a new
Create a new file in
/etc/dconf/db/local.d/locks/00-default-wallpaperwith 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
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.
Ensure that the
glib2-fampackage is installed on the system.
# yum install glib2-fam
Create or edit the
/etc/dconf/profile/userfile on every client.
At the very beginning of the
/etc/dconf/profile/userfile, add the following line:
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:
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
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
$ 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
$ 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
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
$ gsettings get org.gnome.shell remember-mount-password
As a result, the return code displays
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
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]
[--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
$ 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
$ 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
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.