community.general.dconf – Modify and read dconf database

Note

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

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)