dconf

Table of Contents

1. Description
2. Setup - The basics of getting started with dconf
   • What dconf affects
   • Setup requirements
   • Beginning with dconf
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

This module will install dconf and allow you to manage GNOME desktop environment via Puppet.

Setup

What dconf affects

• dconf package
• dconf profiles under /etc/dconf/profile/
• dconf db files under /etc/dconf/db/
• dconf db lock files under /etc/dconf/db/YOUR_PROFILE/locks/

Setup Requirements

See module dependencies for more details.

Beginning with dconf

For basic use of this module, first make sure the module is installed on your puppet-server, then add the following to your manifest:

include dconf

On its own, this will simply install the dconf packages for your distro.

Usage

Include usage examples for common use cases in the Usage section. Show your users how to use your module to solve problems, and be sure to include code examples. Include three to five examples of the most important or common tasks a user can accomplish with your module. Show users how to accomplish more complex tasks that involve different types, classes, and functions working in tandem.

Creating a dconf profile

dconf::profile { 'user':
  entries => {
    'user' => {
      'type'  => 'user',
      'order' => 10,
     },
    'local' => {
      'type'  => 'system',
      'order' => 21,
    },
    'site' => {
      'type'  => 'system',
      'order' => 22,
    },
  },
}

Will result in the following profile at /etc/dconf/profile/user

user-db:user
system-db:local
system-db:site

Creating a dconf settings file with locks

dconf::db { 'local':
  settings => {
    'system/proxy/http' => {
      'host' => '172.16.0.1',
      'enabled' => 'true',
    },
  locks => [
    '/system/proxy/http/host',
    '/system/proxy/http/enabled',
  ],

Will result in the following dconf database structure:

/etc/dconf/
|-- db
|   |-- local
|   `-- local.d
|       |-- 00-default
|       `-- locks
|           `-- 00-default

local.d/00-default

[system/proxy/http]
host = '172.16.0.1'
enabled = true

local.d/locks/00-default

/system/proxy/http/enabled
/system/proxy/http/host

Configure dconf with hiera

This module can also be configured entirely using hiera. To configure the above with hiera, use the following snippet:

dconf::profiles:
  'user':
    entries:
      'user':
        type: 'user'
        order: 10
      'local':
        type: 'system'
        order: 21
      'site':
        type: 'system'
        order 22
dconf::dbs:
  'local':
    settings:
      'system/proxy/http':
        'host': "'172.16.0.1'"
        'enabled': 'true'
    locks:
      - '/system/proxy/http/host'
      - '/system/proxy/http/enabled'

Note that some dconf values must be double quoted to ensure the resulting dconf ini keyfile contains the correct data.

Removing dconf profiles and databases

To remove dconf profiles and databases, you can use the ensure parameter.

Resource declaration

dconf::profile { 'user':
  ensure => 'absent',
}
dconf::db { 'local':
  ensure => 'absent',
}

Hiera declaration

dconf::profiles:
  'user':
    ensure: 'absent'
dconf::dbs:
  'local':
    ensure: 'absent'

Ensuring the absence of a dconf database will cause the db file, db directory, and associated locks to all be removed. If you just want to remove the locks you can supply an empty array for the resource:

dconf::dbs:
  'local':
    locks: []

Limitations

This module only ensures the specified settings are present in your dconf keyfiles. Unmanaged INI settings in your keyfiles will not be automatically removed. This is a limitation of the puppetlabs/inifile module used to generate the dconf keyfiles.

Development

When contributing, please check your code conforms to the Puppet language style guide: https://www.puppet.com/docs/puppet/latest/style_guide.html

Reference

Table of Contents

Classes

• dconf: Installs and configures dconf

Defined types

• dconf::db: Create dconf db keyfiles
• dconf::profile: Create dconf profiles

Classes

dconf

Installs and configures dconf

Examples

Declaring the class

include dconf

Parameters

The following parameters are available in the dconf class:

• manage_packages
• packages
• db_base_dir
• profile_base_dir
• profiles
• dbs

manage_packages

Data type: Boolean

Whether to manage the dconf packages.

Default value: true

packages

Data type: Array

The packages required for dconf management. Typically sourced via hiera.

Default value: []

db_base_dir

Data type: Stdlib::Absolutepath

The base directory for dconf db files

Default value: '/etc/dconf/db'

profile_base_dir

Data type: Stdlib::Absolutepath

The base directory for dconf profiles

Default value: '/etc/dconf/profile'

profiles

Data type: Optional[Hash]

Hash of dconf profiles

Default value: undef

dbs

Data type: Optional[Hash]

Hash of dconf databases, settings and locks

Default value: undef

Defined types

dconf::db

Create dconf db keyfiles

Examples

Create a dconf db keyfile with given settings

dconf::db { 'local':
  settings => {
    'system/proxy/http' => {
      'host' => "'172.16.0.1'",
      'enabled' => 'true',
    },
    'org/gnome/desktop/background' => {
      'picture-uri' => 'file:///usr/local/rupert-corp/company-wallpaper.jpeg',
    },
  },
}

Lockdown dconf settings

dconf::db { 'local':
  settings => {
    'system/proxy/http' => {
      'host' => "'172.16.0.1'",
      'enabled' => 'true',
    },
  locks => [
    'system/proxy/http/host',
    'system/proxy/http/enabled',
  ],

Managing multiple config files for the same db

dconf::db { 'system-proxy':
  db_dir      => '/etc/dconf/db/local.d',
  db_filename => 'system-proxy',
  settings    => {
    'system/proxy/http' => {
      'host'    => "'172.16.0.1'",
      'enabled' => 'true',
    },
  },
}
dconf::db { 'disable-microphone':
  db_dir      => '/etc/dconf/db/local.d',
  db_filename => 'disable-micrphone',
  settings    => {
    'org/gnome/desktop/privacy' => {
      'disable-microphone' => 'true',
    },
  },
}

Parameters

The following parameters are available in the dconf::db defined type:

• settings
• locks
• db_dir
• db_filename
• db_file
• locks_dir
• locks_filename
• locks_file
• db_dir_mode
• db_file_mode
• locks_dir_mode
• locks_file_mode
• purge
• ensure
• inifile_defaults

settings

Data type: Optional[Hash]

Hash of dconf settings

Default value: undef

locks

Data type: Optional[Array]

Array of dconf settings to lock

Default value: undef

db_dir

Data type: Stdlib::Absolutepath

Absolute path of the dconf db directory

Default value: "${dconf::db_base_dir}/${name}.d"

db_filename

Data type: String

Name of the dconf db file

Default value: '00-default'

db_file

Data type: Stdlib::Absolutepath

Absolute path of the dconf db file

Default value: "${db_dir}/${db_filename}"

locks_dir

Data type: Stdlib::Absolutepath

Absolute path of the dconf db locks directory

Default value: "${db_dir}/locks"

locks_filename

Data type: String

Name of the dconf locks file

Default value: '00-default'

locks_file

Data type: Stdlib::Absolutepath

Absolute path of the dconf db locks file

Default value: "${locks_dir}/${locks_filename}"

db_dir_mode

Data type: String

File permissions for dconf db directory

Default value: '0755'

db_file_mode

Data type: String

File permissions for dconf db file

Default value: '0644'

locks_dir_mode

Data type: String

File permissions for dconf db locks directory

Default value: '0755'

locks_file_mode

Data type: String

File permissions for dconf db locks file

Default value: '0644'

purge

Data type: Boolean

Whether to purge unmanaged files (keyfiles and lock files)

Default value: true

ensure

Data type: Enum['present','absent']

Whether to ensure presence or absence of the resource

Default value: 'present'

inifile_defaults

Data type: Hash

Default parameters to parse to inifile provider

Default value: { ensure => 'present', path => $db_file, notify => Exec['dconf_update'], require => File[$db_file], }

dconf::profile

Create dconf profiles

Examples

Creating dconf profiles

dconf::profile { 'local':
  entries => {
    'user' => {
      'type'  => 'user',
      'order' => 10,
     },
    'local' => {
      'type'  => 'system',
      'order' => 21,
    },
    'site' => {
      'type'  => 'system',
      'order' => 21,
    },
  },
}

Parameters

The following parameters are available in the dconf::profile defined type:

• profile_file
• profile_file_mode
• ensure
• default_entry_order
• entries

profile_file

Data type: Stdlib::Absolutepath

Absolute path to dconf profile file

Default value: "${dconf::profile_base_dir}/${name}"

profile_file_mode

Data type: String

File permissions for dconf profile file

Default value: '0644'

ensure

Data type: Enum['present','absent']

Whether to ensure presence or absence of the dconf profile

Default value: 'present'

default_entry_order

Data type: String

Default order of profile entries

Default value: '25'

entries

Data type: Optional[Hash]

List of entries to include in the dconf profile

Default value: undef

Changelog

All notable changes to this project will be documented in this file.

Release 0.2.0

Breaking

• Remove dconf::db::base_dir parameter
• Remove dconf::db::base_dir_mode in favour of hard-coded value 0755
• Remove dconf::profile::profile_dir parameter
• Remove dconf::profile::profile_dir_mode parameter

Added

• New parameter dconf::db_base_dir
• New parameter dconf::profile_base_dir
• Unit testing and CI/CD workflows

Changed

• dconf::db::db_dir parameter is now formed using dconf::db_base_dir parameter
• dconf::profile::profile_file parameter is now formed using dconf::profile_base_dir parameter
• Convert if/elsif logic to case statement for dconf::db
• Convert if/elsif logic to case statement for dconf::profile
• Replace create_ini_settings() function in dconf::db with native Puppet resource iteration
• /etc/dconf/db directory is now ensured by the main class
• /etc/dconf/profile directory is now ensured by the main class
• Replace ensure_packages() function in main class with native Puppet resource iteration
• Remove unused dconf::profile::purge parameter
• Set upper bounderies for module dependencies

Fixed

• Fixed incorrect directory mode for generated dconf::db resources
• Fixed hiera lookups

Release 0.1.1

Added

• Allow multiple db files/lockfiles to be managed under a single dconf db directory (#5)
• Specify umask for dconf update command (#7)
• Allow dconf::db resource to remove empty lock directories (#9)
• Added REFERENCE.md

Fixed

• Corrected usage documentation for dconf::profile
• Corrected usage documentation for dconf::db

Release 0.1.0

Features

Bugfixes

Known Issues