community.general.dconf module – Modify and read dconf database

Note

This module is part of the community.general collection (version 5.8.3).

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

Comments

key

string / required

A dconf key to modify or read from the dconf database.

state

string

The action to take upon the key/value.

Choices:

  • "read"

  • "present" ← (default)

  • "absent"

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 :code:`”[(‘xkb’, ‘us’), (‘xkb’, ‘se’)]”`, you need to be aware of possible type conversions. Applying a filter :code:`”{{ 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

Description

value

string

value associated with the requested key

Returned: success, state was “read”

Sample: "'Default'"

Authors

  • Branko Majic (@azaghal)