REFERENCE.md

Reference

Table of Contents

Classes

Public Classes

• rspamd: this class allows you to install and configure the Rspamd system and its services
• rspamd::repo: Manages the rspamd.com package repository

Private Classes

• rspamd::configuration: This class handles configuration. Avoid modifying private classes.
• rspamd::install: This class handles packages. Avoid modifying private classes.
• rspamd::repo::apt_stable: Includes the rspamd.com/apt-stable APT repository
• rspamd::repo::rpm_stable: Includes the rspamd.com/rpm-stable RPM repository
• rspamd::service: This class handles services. Avoid modifying private classes.

Defined types

• rspamd::config: this type manages a single config entry
• rspamd::ucl::config: manages a single UCL (Universal Configuration Language) config entry
• rspamd::ucl::file: manages a single UCL (Universal Configuration Language) config file

Functions

• rspamd::create_config_file_resources: create {rspamd::config} resources from a nested hash (e.g. from hiera)
• rspamd::create_config_resources: create rspamd::config resources from a nested hash (e.g. from hiera)
• rspamd::ucl::print_config_value: returns a properly quoted UCL config value
• rspamd::ucl::quote_string_value: quotes a string as a valid UCL string

Data types

• Rspamd::Ucl::ValueType: simple enum for possible types of config values.

Classes

rspamd

Class: rspamd

Main entry point for the rspamd module

Examples

include rspamd

Parameters

The following parameters are available in the rspamd class:

• package_ensure
• package_manage
• package_name
• service_manage
• repo_baseurl
• manage_package_repo
• config
• config_path
• purge_unmanaged

package_ensure

Data type: String

specifies the ensure state of the rspamd package

package_manage

Data type: Boolean

whether to install the rspamd package

package_name

Data type: String

rspamd package name

service_manage

Data type: Boolean

whether to manage the rspamd service

repo_baseurl

Data type: Optional[String]

use a different repo url instead of rspamd.com upstream repo

manage_package_repo

Data type: Boolean

whether to add the upstream package repo to your system (includes {rspamd::repo})

config

Data type: Hash

a Hash of configuration parameters

config_path

Data type: String

the path containing the rspamd config directory

purge_unmanaged

Data type: Boolean

whether local.d/override.d config files not managed by this module should be purged

rspamd::repo

Manages the rspamd.com package repository

Examples

include rspamd::repo

Defined types

rspamd::config

rspamd::config

Rspamd uses its own UCL (Unified Configuration Language) format. This format basically allows to define a hierarchy of configuration objects.

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 UCL:

section {
  foo = bar
}

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

UCL also allows to define arrays, by specifying the same key multiple times. To map this feature to a flattened key name, we use a numerical index in brackets. For example, this UCL snippet

statfile {
  token = "BAYES_HAM"
}
statfile {
  token = "BAYES_SPAM"
}

would be mapped to

statfile[0].token = "BAYES_HAM"
statfile[1].token = "BAYES_SPAM"

Title/Name format

This module manages keeps Rspamd's default configuration untouched, and manages only local override config files. This matches the procedure recommended by the Rspamd authors.

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 rspamd::config defined type:

• sections
• key
• file
• value
• type
• mode
• comment
• ensure

sections

Data type: Optional[Array[String]]

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

If arrays of values are required (including arrays of maps, i.e. multiple sections with the same name), the key must be succeeded by an bracketed index, e.g.

sections => ["statfile[0]"],
key      => "token",
value    => "BAYES_HAM",

sections => ["statifle[1]"],
key      => "token",
value    => "BAYES_SPAM",

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/maps.

Default value: undef

file

Data type: Optional[String]

The file to put the value in. This module keeps Rspamd's default configuration and makes use of its overrides. The value of this parameter must not include any path information. If it contains no dot, .conf will be appended. E.g. bayes-classifier

Default value: undef

value

Data type: Any

the value of this config entry. See type for allowed types.

type

Data type: Rspamd::Ucl::ValueType

The type of the value, can be auto, string, number, boolean.

The default, auto, will try to determine the type from the input value: Numbers and strings looking like supported number formats (e.g. "5", "5s", "10min", "10Gb", "0xff", etc.) will be output literally. Booleans and strings looking like supported boolean formats (e.g. "on", "off", "yes", "no", "true", "false") will be output literally. Everything else will be output as a strings, unquoted if possible but quoted if necessary. Multi-line strings will be output as <<EOD heredocs.

If you require string values that look like numbers or booleans, explicitly specify type => 'string'

Default value: 'auto'

mode

Data type: Enum['merge', 'override']

Can be merge or override, and controls whether the config entry will be written to local.d or override.d directory.

Default value: 'merge'

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'

rspamd::ucl::config

rspamd::ucl::config

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

• See also

  • rspamd::config

Parameters

The following parameters are available in the rspamd::ucl::config defined type:

• file
• key
• sections
• value
• type
• comment
• ensure

file

Data type: Stdlib::Absolutepath

the file to put the entry in

key

Data type: String

the entry's key

sections

Data type: Array[String]

the entry's sections as an array

Default value: []

value

Data type: Any

the entry's value

type

Data type: Rspamd::Ucl::ValueType

the type to enforce (or auto for auto-detection)

Default value: 'auto'

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'

rspamd::ucl::file

Class: rspamd::ucl::file

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

• See also

  • rspamd::config

Parameters

The following parameters are available in the rspamd::ucl::file defined type:

• file
• comment
• ensure

file

Data type: Stdlib::Absolutepath

the file to put the entry in

Default value: $title

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'

Functions

rspamd::create_config_file_resources

Type: Puppet Language

Function: rspamd::create_config_file_resources()

Create {rspamd::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 {rspamd::create_config_resources} function

rspamd::create_config_file_resources(Hash[String, Hash] $configfile_hash, Hash $params = {})

Function: rspamd::create_config_file_resources()

Create {rspamd::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 {rspamd::create_config_resources} function

Returns: Any

configfile_hash

Data type: Hash[String, Hash]

a hash of config file names mapped to config hashes

params

Data type: Hash

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

rspamd::create_config_resources

Type: Puppet Language

Function: rspamd::create_config_resources()

Create rspamd::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 rspamd::config for simple values, Hash values recursively create nested sections. Arrays that only contain Hash values are created as multi-value keys (or "duplicate sections"), while all other arrays are printed inline (e.g. [a,b,c]).

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

Function: rspamd::create_config_resources()

Create rspamd::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 rspamd::config for simple values, Hash values recursively create nested sections. Arrays that only contain Hash values are created as multi-value keys (or "duplicate sections"), while all other arrays are printed inline (e.g. [a,b,c]).

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 rspamd::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

rspamd::ucl::print_config_value

Type: Puppet Language

Function: rspamd::ucl::print_config_value()

rspamd::ucl::print_config_value(Any $value, Rspamd::Ucl::ValueType $type = 'auto')

Function: rspamd::ucl::print_config_value()

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

value

Data type: Any

the value to be printed

type

Data type: Rspamd::Ucl::ValueType

the type to be enforced (or auto to detect from value)

rspamd::ucl::quote_string_value

Type: Ruby 4.x API

quotes a string as a valid UCL string

• Note this is internal API and should never be required by users

rspamd::ucl::quote_string_value(String $value)

The rspamd::ucl::quote_string_value function.

Returns: Any

value

Data type: String

Data types

Rspamd::Ucl::ValueType

== Type: Rspamd::ValueType

Simple enum for possible types of config values.

Can be used in rspamd::config definitions to force a certain type.

Alias of Enum['auto', 'string', 'number', 'boolean', 'array']