1. Introduction
The gsettings application is a staple in GNOME desktop environments. It enables the export and modification of specific system settings called GSettings. In Linux, gsettings is a command-line front-end to the ubiquitous dconf command. However, due to the graphical nature of some GSettings, we might not always be able to modify them directly.
In this tutorial, we uncover how to use gsettings or dconf in a remote session or a TTY without a graphical user interface (GUI). First, we talk about the database structure behind gsettings and dconf. After that, we explore problems that might arise when managing the database in a remote session. Finally, we go over some specifics around the environment one needs to set up for gsettings and dconf to function without issues.
We tested the code in this tutorial on Debian 12 (Bookworm) with GNU Bash 5.2.15. It should work in most POSIX-compliant environments unless otherwise specified.
2. GSettings
GSettings are a database of key-value pairs within a hierarchical structure that control the behavior of applications that register values within it. Importantly, the concept behind GSettings comes from GTK GIO, but their implementation can vary.
For example, on many Linux distributions, they are stored in a dconf binary database within a single file. As mentioned, the gsettings application is the front end of the more rudimentary dconf tool. This is similar to the relationship between apt and dpkg.
Let’s briefly go over some operations with both gsettings and dconf.
2.1. Read Key
To begin with, we can perform a read with gsettings:
$ gsettings get org.gnome.calculator show-zeroes
false
Here, we employ gsettings to get the value of the show-zeroes key at org.gnome.calculator. Currently, that value is false.
Now, we can verify our result with the lower-level dconf:
$ dconf read /org/gnome/calculator/show-zeroes
false
As expected, the value is equivalent. Notably, dconf uses a slash-separated path, which ends with the key of interest.
2.2. Set Key
After checking export and read operations, let’s try to write a value with dconf:
$ dconf write /org/gnome/calculator/show-zeroes true
$ dconf read /org/gnome/calculator/show-zeroes
true
Now, let’s turn to gsettings for the same:
$ gsettings set org.gnome.calculator show-zeroes false
$ gsettings get org.gnome.calculator show-zeroes
false
As expected, all operations work locally without issues.
3. Manage Graphical GSettings in Remote or Non-graphical Session
At this point, we use a remote session such as an SSH connection or similar to execute the commands below.
3.1. Reading
First, we attempt to read /org/gnome/calculator/show-zeroes with both gsettings and dconf:
$ dconf read /org/gnome/calculator/show-zeroes
true
$ gsettings get org.gnome.calculator show-zeroes
true
The operation exhibits no issues.
3.2. Write Problems and $DISPLAY
However, let’s attempt a modification:
$ dconf write /org/gnome/calculator/show-zeroes false
error: Cannot autolaunch D-Bus without X11 $DISPLAY
$ gsettings set org.gnome.calculator show-zeroes show-zeroes false
(process:666): dconf-WARNING **: 10:00:01.006: failed to commit changes to dconf: Cannot autolaunch D-Bus without X11 $DISPLAY
Here, our system rejects the modification due to a potential display server issue. In fact, we may have a screen running, but an empty or incorrect $DISPLAY variable.
So, we export $DISPLAY with the correct value:
$ export DISPLAY=0:0
Now, let’s retry the gsettings command.
3.3. Write Problems and $DBUS_SESSION_BUS_ADDRESS
After making sure $DISPLAY has the correct value, we rerun gsettings:
$ gsettings set org.gnome.calculator show-zeroes false
(process:667): dconf-WARNING **: 10:00:02.007: failed to commit changes to dconf: Could not connect: Connection refused
Again, a warning prevents the modification. However, this time it’s a bit more ambiguous. Still, the mention of D-Bus in the previous warning can be a clue that our $DBUS_SESSION_BUS_ADDRESS environment variable is invalid. Since DBus ensures proper inter-process communication (IPC), such an invalid value may prevent how we commit values to the GSettings database.
So, let’s amend the variable value with another export:
$ export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus
At this point, we can retry our modifications:
$ gsettings set org.gnome.calculator show-zeroes true
$ gsettings get org.gnome.calculator show-zeroes
true
$ dconf write /org/gnome/calculator/show-zeroes false
$ dconf read /org/gnome/calculator/show-zeroes
false
Now, all operations are successful.
4. Correct $DISPLAY and $DBUS_SESSION_BUS_ADDRESS Values
Of course, the value of $DISPLAY can and often should come from the output of xrandr in a graphical environment.
On the other hand, if we configure an empty $DBUS_SESSION_BUS_ADDRESS value, we might get another error:
$ export DBUS_SESSION_BUS_ADDRESS=
$ gsettings set org.gnome.calculator show-zeroes false
(process:668): dconf-WARNING **: 10:00:02.008: failed to commit changes to dconf: The given address is empty
Alternatively, an incorrect value can produce other errors that pertain to the syntax:
$ export DBUS_SESSION_BUS_ADDRESS=incorrect
$ gsettings set org.gnome.calculator show-zeroes false
(process:669): dconf-WARNING **: 10:00:03.009: failed to commit changes to dconf: Address element “random” does not contain a colon (:)
Although we could get the proper value of $DBUS_SESSION_BUS_ADDRESS via a script, it depends on the environment of external processes:
$ QUERY_ENVIRON="$(tr '\0' '\n' < /proc/${DBUSPID}/environ | grep "DBUS_SESSION_BUS_ADDRESS" | cut -d "=" -f 2-)"
Here, $DBUSPID should contain the process ID of a process that contains the correct value of $DBUS_SESSION_BUS_ADDRESS in its environment. There are different examples:
- nautilus
- kdeinit
- kded4
- pulseaudio
- trackerd
Interestingly, in some environments, using unset on $DBUS_SESSION_BUS_ADDRESS still enables us to perform GSettings modifications:
$ unset DBUS_SESSION_BUS_ADDRESS
$ gsettings set org.gnome.calculator show-zeroes false
$ gsettings get org.gnome.calculator show-zeroes
false
That’s usually due to the correct value of another variable, $XDG_RUNTIME_DIR. It defines the base directory for storage of user-specific non-essential runtime and similar files. In fact, normally, the values of $DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR are similar:
$ echo $DBUS_SESSION_BUS_ADDRESS
unix:path=/run/user/0/bus
$ echo $XDG_RUNTIME_DIR
/run/user/0
Further, all of the variables above are set at login, so any session should initialize them automatically. Despite this, we might encounter the problems we discussed.
5. Summary
In this article, we explored how to use the gsettings application and dconf tool in a remote session.
In conclusion, regardless of the context, whether we can set GSettings keys depends on the values of several environment variables.