Skip to content

Latest commit

 

History

History
855 lines (500 loc) · 22.5 KB

REFERENCE.md

File metadata and controls

855 lines (500 loc) · 22.5 KB

Reference

Table of Contents

Classes

Public Classes

  • dovecot: This class allows simple configuration of the dovecot server.

Private Classes

  • dovecot::configuration: This class handles dovecot configuration.
  • dovecot::install: This class handles packages.
  • dovecot::poolmon: Installs and configures Poolmon.
  • dovecot::service: This class handles services.

Defined types

Functions

Classes

dovecot

There is no semantic abstraction done in this class, all config parameters are passed directly to dovecot via config files.

Examples

Using a profile to load merged values from hiera:
$config = hiera_hash("${title}::config", {})
$configs = hiera_hash("${title}::configs", {})
$plugins = hiera_array("${title}::plugins", undef)
class { 'dovecot':
  plugins => $plugins,
  config => $config,
  configs => $configs,
}

Parameters

The following parameters are available in the dovecot class:

config

Data type: Hash

A hash of config file entries, with nested hashes parsed as sections.

config_path

Data type: String

The path to the dovecot config dir.

configs

Data type: Hash

A hash of conf.d file names to $config-style hashes.

configs_mode

Data type: String

The file permissions that should be applied.

directory_private_manage

Data type: Boolean

Whether to manage the private directory.

extconfigs

Data type: Hash

A hash of external config files.

extconfigs_mode

Data type: String

The file permissions that should be applied.

package_ensure

Data type: String

Whether to install the dovecot package, and what version to install. Values: 'present', 'latest', or a specific version number. Default value: 'present'.

package_manage

Data type: Boolean

Whether to install the dovecot core and plugin packages.

package_name

Data type: Array[String]

The name of the main dovecot package.

plugin

Data type: Hash

Contains a package_name parameter for each plugin (if available).

plugins

Data type: Array[String[1]]

The list of plugins to install.

poolmon_archive_params

Data type: Hash

Additional parameters that should be passed through to the archive resource.

poolmon_basepath

Data type: String

The base path for installing poolmon.

poolmon_config

Data type: Hash

A list of config options.

poolmon_config_file

Data type: String

The path and filename of the configuration file.

poolmon_exec

Data type: String

The path to the poolmon binary.

poolmon_manage

Data type: Boolean

Whether to manage the poolmon service. Default value: false.

poolmon_service_enable

Data type: Boolean

Whether the poolmon service should be configured for automatic startup.

poolmon_service_ensure

Data type: Enum['running', 'stopped']

The desired state for the service.

poolmon_service_file

Data type: String

The path to the service file.

poolmon_service_mode

Data type: String

File permissions for the service file.

poolmon_service_provider

Data type: Enum['init', 'rc', 'systemd']

The provider used to handle services, e.g. systemd.

poolmon_version

Data type: String

The version of poolmon that should be installed.

purge_unmanaged

Data type: Boolean

Whether to purge all unmanaged files in the dovecot directory.

service_enable

Data type: Boolean

Whether to enable the dovecot service at boot. Default value: true.

service_ensure

Data type: Enum['running', 'stopped']

Whether the dovecot service should be running. Default value: 'running'.

service_manage

Data type: Boolean

Whether to manage the dovecot service.

service_name

Data type: String

The dovecot service to manage. Default value: varies by operating system.

sievec

Data type: Stdlib::Absolutepath

The path to the sievec binary.

Defined types

dovecot::config

Dovecot uses its own config format. This format basically allows to define a hierarchy of configuration sections (and syntactically identical filters, so they will just be treated as sections by this module).

Since in puppet, we want to map each single config entry as its own resource, the hierarchy has been "flattened" to hierarchical keys.

A key/value pair foo = bar nested in a section object, would look like this in a dovecot config file:

section {
  foo = bar
}

To reference this key in a dovecot::config variable, you would use the notation section.foo.

Title/Name format

This module can manage both a global dovecot.conf and single conf.d files. The module author recommends single file setups for puppet-managed hosts, but users can choose to split their managed config into single files.

To specify which file a config entry should got to, you can use the file parameter.

For convenience reasons, however, this resource also allows to encode the values for $sections, $key, and $file into the resource's name (which is usally the same as its title).

If the $name of the resource matches the format "[:][.]", and all of $file, $sections, and $key have not been specified, the values from the name are used. This simplifies creating unique resources for identical settings in different files.

Parameters

The following parameters are available in the dovecot::config defined type:

sections

Data type: Optional[Array[String]]

An array of section names that define the hierarchical name of this key. E.g. ["protocol imap", "plugin"] to denote the protocol imap { plugin {` section.

Default value: undef

key

Data type: Optional[String]

The key name of the config setting. The key is expected as a single non-hierachical name without any sections/filters. The special values !include and !include_try can be used for includes.

Default value: undef

file

Data type: Optional[String]

The file to put the value in. If undef (the default), the value is put into the global dovecot.conf, otherwise the value si written to conf.d/${file}.conf The value of this parameter must not include any path information or file extension. E.g. 10-auth

Default value: undef

value

Data type: Variant[Boolean, Integer, String]

the value of this config entry.

comment

Data type: Optional[String]

an optional comment that will be written to the config file above the entry

Default value: undef

ensure

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

whether this entry should be present or absent. Usually not needed at all, because the config file will be fully managed by puppet and re-created each time.

Default value: 'present'

dovecot::configentry

Manages a single dovecot config entry.

  • Note This class is only for internal use, use dovecot::config instead.

  • See also

    • dovecot::config

Parameters

The following parameters are available in the dovecot::configentry defined type:

comment

Data type: Optional[String]

an optional comment to be printed above the entry

Default value: undef

ensure

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

Whether the entry should be present or absent.

Default value: 'present'

file

Data type: Stdlib::Absolutepath

The file to put the entry in.

key

Data type: String

The entry's key, or !include/!include_try.

sections

Data type: Array[String]

The entry's sections as an array.

Default value: []

value

Data type: Variant[Boolean, Integer, String]

The entry's value.

dovecot::configfile

Manages a single dovecot config file

  • Note This define is only for internal use, use dovecot::config instead.

  • See also

    • dovecot::config

Parameters

The following parameters are available in the dovecot::configfile defined type:

comment

Data type: Optional[String]

An optional comment to be printed at the top of the file instead of the default warning.

Default value: undef

ensure

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

Whether the file should be present or absent.

Default value: 'present'

file

Data type: Stdlib::Absolutepath

The file to put the entry in.

Default value: $title

group

Data type: Variant[Integer, String]

The group that should own the file.

Default value: 0

mode

Data type: Variant[Integer, String]

The permissions for the file.

Default value: $dovecot::configs_mode

owner

Data type: Variant[Integer, String]

The user that should own the file.

Default value: 'root'

dovecot::extconfigfile

Resource for external config files providing a very basic key-value interface.

Parameters

The following parameters are available in the dovecot::extconfigfile defined type:

additional_content

Data type: Optional[String]

Additional content for the file.

Default value: undef

entries

Data type: Hash[String, String]

A hash of string=string entries. All values will be written as-is to the file, any escaping must already be applied.

group

Data type: Variant[Integer, String]

The group that should own the file.

Default value: 0

mode

Data type: Variant[Integer, String]

The permissions for the file.

Default value: $dovecot::extconfigs_mode

owner

Data type: Variant[Integer, String]

The user that should own the file.

Default value: 'root'

relpath

Data type: String

The path of the external config file relative to dovecot::config_path, including the desired extension. Defaults to the resource title.

Default value: $title

warn

Data type: Variant[Boolean, String]

Whether to prepend the default warning (if true), a custom warning (if a String), or nothing at all.

Default value: true

dovecot::file

Simple file resource that notifies the dovecot service.

Parameters

The following parameters are available in the dovecot::file defined type:

content

Data type: String

The content of the file.

group

Data type: Variant[Integer, String]

The group that should own the file.

Default value: 0

mode

Data type: Variant[Integer, String]

The permissions for the file.

Default value: '0644'

owner

Data type: Variant[Integer, String]

The user that should own the file.

Default value: 'root'

path

Data type: Stdlib::Absolutepath

The target path for the file.

dovecot::sieve

notifies the dovecot service.

Parameters

The following parameters are available in the dovecot::sieve defined type:

content

Data type: String

The content of the file.

Default value: undef

group

Data type: Variant[Integer, String]

The group that should own the file.

Default value: 0

mode

Data type: Variant[Integer, String]

The permissions for the file.

Default value: '0644'

owner

Data type: Variant[Integer, String]

The user that should own the file.

Default value: 'root'

path

Data type: Stdlib::Absolutepath

The target path for the file.

Default value: $name

sievec

Data type: Stdlib::Absolutepath

The path to the sievec binary.

Default value: $dovecot::sievec

source

Data type: Optional[String]

Optional source for the file resource to use instead of $content.

Default value: undef

Functions

dovecot::create_config_file_resources

Type: Puppet Language

Function: dovecot::create_config_file_resources()

Create {dovecot::config} resources from a nested hash, suitable for conveniently loading values from hiera.

The first level of keys is the config files to be written to, the values being the hierarchical values that will be passed to the {dovecot::create_config_resources} function

dovecot::create_config_file_resources(Hash[String, Hash] $configfile_hash, Boolean $include_in_main_config = true, Hash $params = {})

Function: dovecot::create_config_file_resources()

Create {dovecot::config} resources from a nested hash, suitable for conveniently loading values from hiera.

The first level of keys is the config files to be written to, the values being the hierarchical values that will be passed to the {dovecot::create_config_resources} function

Returns: Any

configfile_hash

Data type: Hash[String, Hash]

a hash of config file names mapped to config hashes

include_in_main_config

Data type: Boolean

whether the single config files should be included from dovecot.conf

params

Data type: Hash

a hash of params passed to the {dovecot::config} resource (:file will be overridden)

dovecot::create_config_resources

Type: Puppet Language

Create dovecot::config resources from a nested hash, suitable for conveniently loading values from hiera. The key-value pairs from the hash represent config keys and values passed to dovecot::config for simple values, Hash values recursively create nested sections, and Array values are joined with spaces.

dovecot::create_config_resources(Hash[String, NotUndef] $config_hash, Hash $params = {}, Array[String] $sections = [])

Create dovecot::config resources from a nested hash, suitable for conveniently loading values from hiera. The key-value pairs from the hash represent config keys and values passed to dovecot::config for simple values, Hash values recursively create nested sections, and Array values are joined with spaces.

Returns: Any

config_hash

Data type: Hash[String, NotUndef]

a hash of (non-hierarchical) key names mapped to values

params

Data type: Hash

a hash of params passed to dovecot::config (must not include :sections, :key, or :value)

sections

Data type: Array[String]

the section names of the hierarchical key, will usually only be specified on recursive calls from within this function itself

dovecot::create_extconfigfile_resources

Type: Puppet Language

Function: dovecot::create_extconfigfile_resources()

Create {dovecot::extconfigfile} resources from a nested hash, suitable for conveniently loading values from hiera.

The first level of keys is the config files to be written to, the values being the hierarchical values that will be passed to the extconfigfile resource.

Values can either be a Hash[String, String], or a hash containing two properties entries and additional_content.

dovecot::create_extconfigfile_resources(Hash[String, Hash] $configfile_hash)

Function: dovecot::create_extconfigfile_resources()

Create {dovecot::extconfigfile} resources from a nested hash, suitable for conveniently loading values from hiera.

The first level of keys is the config files to be written to, the values being the hierarchical values that will be passed to the extconfigfile resource.

Values can either be a Hash[String, String], or a hash containing two properties entries and additional_content.

Returns: Any

configfile_hash

Data type: Hash[String, Hash]

a hash of config file names mapped to config hashes

dovecot::print_config_value

Type: Puppet Language

Function: dovecot::print_config_value()

dovecot::print_config_value(Any $value)

Function: dovecot::print_config_value()

Returns: Any the formatted config value suitable for inclusion in a dovecot config file

value

Data type: Any

the value to be printed