community.general.dconf module – Modify and read dconf database
Note
This module is part of the community.general collection (version 8.6.4).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.dconf
.
Synopsis
This module allows modifications and reading of
dconf
database. The module is implemented as a wrapper arounddconf
tool. Please see the dconf(1) man page for more details.Since
dconf
requires a running D-Bus session to change values, the module will try to detect an existing session and reuse it, or run the tool viadbus-run-session
.
Aliases: system.dconf
Requirements
The below requirements are needed on the host that executes this module.
Optionally the
gi.repository
Python library (usually included in the OS on hosts which havedconf
); this will become a non-optional requirement in a future major release of community.general.
Parameters
Parameter |
Comments |
---|---|
A dconf key to modify or read from the dconf database. |
|
The action to take upon the key/value. Choices:
|
|
Value to set for the specified dconf key. Value should be specified in GVariant format. Due to complexity of this format, it is best to have a look at existing values in the dconf database. Required for Although the type is specified as “raw”, it should typically be specified as a string. However, boolean values in particular are handled properly even when specified as booleans rather than strings (in fact, handling booleans properly is why the type of this parameter is “raw”). |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
This module depends on
psutil
Python library (version 4.0.0 and upwards),dconf
,dbus-send
, anddbus-run-session
binaries. Depending on distribution you are using, you may need to install additional packages to have these available.This module uses the
gi.repository
Python library when available for accurate comparison of values indconf
to values specified in Ansible code.gi.repository
is likely to be present on most systems which havedconf
but may not be present everywhere. When it is missing, a simple string comparison between values is used, and there may be false positives, that is, Ansible may think that a value is being changed when it is not. This fallback will be removed in a future version of this module, at which point the module will stop working on hosts withoutgi.repository
.Detection of existing, running D-Bus session, required to change settings via
dconf
, is not 100% reliable due to implementation details of D-Bus daemon itself. This might lead to running applications not picking-up changes on the fly if options are changed via Ansible anddbus-run-session
.Keep in mind that the
dconf
CLI tool, which this module wraps around, utilises an unusual syntax for the values (GVariant). For example, if you wanted to provide a string value, the correct syntax would bevalue="'myvalue'"
- with single quotes as part of the Ansible parameter value.When using loops in combination with a value like
"[('xkb', 'us'), ('xkb', 'se')]"
, you need to be aware of possible type conversions. Applying a filter{{ item.value | string }}
to the parameter variable can avoid potential conversion problems.The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in application affected by the key, and then having a look at value set via commands
dconf dump /path/to/dir/
ordconf read /path/to/key
.
Examples
- name: Configure available keyboard layouts in Gnome
community.general.dconf:
key: "/org/gnome/desktop/input-sources/sources"
value: "[('xkb', 'us'), ('xkb', 'se')]"
state: present
- name: Read currently available keyboard layouts in Gnome
community.general.dconf:
key: "/org/gnome/desktop/input-sources/sources"
state: read
register: keyboard_layouts
- name: Reset the available keyboard layouts in Gnome
community.general.dconf:
key: "/org/gnome/desktop/input-sources/sources"
state: absent
- name: Configure available keyboard layouts in Cinnamon
community.general.dconf:
key: "/org/gnome/libgnomekbd/keyboard/layouts"
value: "['us', 'se']"
state: present
- name: Read currently available keyboard layouts in Cinnamon
community.general.dconf:
key: "/org/gnome/libgnomekbd/keyboard/layouts"
state: read
register: keyboard_layouts
- name: Reset the available keyboard layouts in Cinnamon
community.general.dconf:
key: "/org/gnome/libgnomekbd/keyboard/layouts"
state: absent
- name: Disable desktop effects in Cinnamon
community.general.dconf:
key: "/org/cinnamon/desktop-effects"
value: "false"
state: present
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
value associated with the requested key Returned: success, state was “read” Sample: |