community.general.dconf – Modify and read dconf database

Note

This plugin is part of the community.general collection (version 3.8.1).

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.

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 around dconf 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 via dbus-run-session.

Parameters

Parameter	Choices/Defaults	Comments
key string / required		A dconf key to modify or read from the dconf database.
state string	Choices: read present ← absent	The action to take upon the key/value.
value string		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 state=present.

Notes

Note

This module depends on psutil Python library (version 4.0.0 and upwards), dconf, dbus-send, and dbus-run-session binaries. Depending on distribution you are using, you may need to install additional packages to have these available.
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 and dbus-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 be value="'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/ or dconf 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	Returned	Description
value string	success, state was "read"	value associated with the requested key Sample: 'Default'

Authors

Branko Majic (@azaghal)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/dconf_module.html

Docs

Docs4dev

Title here