dconf – Modify and read dconf database

New in version 2.4.

Synopsis
Parameters
Notes
Examples
Return Values
Status

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 - / required		A dconf key to modify or read from the dconf database.
state -	Choices: read present ← absent	The action to take upon the key/value.
value -		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.
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
  dconf:
    key: "/org/gnome/desktop/input-sources/sources"
    value: "[('xkb', 'us'), ('xkb', 'se')]"
    state: present

- name: Read currently available keyboard layouts in Gnome
  dconf:
    key: "/org/gnome/desktop/input-sources/sources"
    state: read
  register: keyboard_layouts

- name: Reset the available keyboard layouts in Gnome
  dconf:
    key: "/org/gnome/desktop/input-sources/sources"
    state: absent

- name: Configure available keyboard layouts in Cinnamon
  dconf:
    key: "/org/gnome/libgnomekbd/keyboard/layouts"
    value: "['us', 'se']"
    state: present

- name: Read currently available keyboard layouts in Cinnamon
  dconf:
    key: "/org/gnome/libgnomekbd/keyboard/layouts"
    state: read
  register: keyboard_layouts

- name: Reset the available keyboard layouts in Cinnamon
  dconf:
    key: "/org/gnome/libgnomekbd/keyboard/layouts"
    state: absent

- name: Disable desktop effects in Cinnamon
  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'

Status

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]

Authors

Branko Majic (@azaghal)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/dconf_module.html