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 setdconf
values. Thegsettings
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.WarningAs a user or application developer, do not use the
dconf
utility directly.To manipulate
dconf
values, always use the dconf editor application or thegsettings
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
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 type | GVariant text format examples |
---|---|
Boolean |
|
String |
|
Number |
|
Tuple |
|
Array |
|
Dictionary |
|
Variant |
|
Maybe |
|
Byte string |
|
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 nameduser
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
andsite
-
System databases, located in
/etc/dconf/db/
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
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 ongsettings
, see Working with GSettings keys on command line.Ensure that the
/etc/dconf/profile/user
configuration file enables the user profile:user-db:user system-db:local
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
.In the keyfile, specify the default settings in the following format:
[path/to/schema] key-name=value another-key-name=another-value
ImportantSeparate 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
Update the system databases:
# dconf update
- 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 adconf
database. For more information, see thedconf(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
-
Create the
/etc/dconf/db/local.d/locks/
directory. - 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
- Set a default wallpaper.
-
Create the
/etc/dconf/db/local.d/locks/
directory. 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
Update the system databases:
# dconf update
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:
Monitor the
favorite-apps
key:$ gsettings monitor org.gnome.shell favorite-apps
In another terminal, change the
favorite-apps
key:$ gsettings set org.gnome.shell favorite-apps \ "['firefox.desktop', 'evolution.desktop', 'rhythmbox.desktop']"
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.