puppet-rspamd

Table of Contents

1. Description
2. Setup
   • What rspamd affects
   • Beginning with rspamd
3. Usage
4. Reference
5. Development
   • Contributing

Description

This module installs and manages the Rspamd spam filter, and provides resources and functions to configure the Rspamd system. It does, however, not configure the systems beyond the upstream defaults.

Please note that while all versions starting from 1.6.3 should still be supported, this module is intended to be run with the latest version of Rspamd, and compatibility with older versions will not be tested for new releases.

Setup

What rspamd affects

By default, this module...

• installs the rspamd.com package repository for Debian/Ubuntu and RHEL/CentOS/Fedora
• installs the rspamd package
• recursively purges all custom rspamd config (e.g. local.d and override.d directories)

Beginning with rspamd

The simplest way to use this module is:

include rspamd

This will setup the rspamd service the upstream default configuration.

Usage

The rspamd::config resource can be used to specify custom configuration entries. The easiest way to use it, is to put both the file and the hierachical config key into the resource title:

class { 'rspamd': }
rspamd::config {
  'classifier-bayes:backend': value => 'redis';
  'classifier-bayes:servers': value => '127.0.0.1:6379';
  'classifier-bayes:statfile[0].symbol': value => 'BAYES_HAM';
  'classifier-bayes:statfile[0].spam':   value => false;
  'classifier-bayes:statfile[1].symbol': value => 'BAYES_SPAM';
  'classifier-bayes:statfile[1].spam':   value => true;
}

This results the following config file /etc/rspamd/local.d/classifier-bayes.conf:

# This file is managed by Puppet. DO NOT EDIT.
backend = redis;
servers = "127.0.0.1:6379";
statfile {
  spam = false;
  symbol = 'BAYES_HAM';
}
statfile {
  spam = true;
  symbol = 'BAYES_SPAM';
}

Using the rspamd $config parameter, values for multiple config files can easily be provided from hiera:

rspamd::config:
  classifier-bayes:
    backend: redis
    servers: "127.0.0.1:6379"
    statfile:
      - symbol: BAYES_HAM
        spam: false
      - symbol: BAYES_SPAM
        spam: true
  milter_headers:
    use:
      - authentication-results
      - x-spam-status
  'worker-proxy.inc':
    bind_socket: 'localhost:11332'
    upstream:
      local:
        self_scan: true
  dkim_signing:
    sign_local: true

This uses the provided rspamd::create_config_resources and rspamd::create_config_file_resources functions, which can be used in custom profiles for extended use cases:

class profile::mail::rspamd (
  Hash $config,
  Hash $override_config,
) {
  class { 'rspamd': }

  rspamd::create_config_file_resources($config)
  rspamd::create_config_file_resources($override_config, { mode => 'override' })
}

Reference

Classes and parameters are documented in REFERENCE.md.

Development

Contributing

Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.

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']

Changelog

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

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

2.1.0 - 2023-08-08

Changed

• Update module dependencies
• Update PDK to 3.0.0

2.0.0 - 2023-05-16

Added

• Add support for managing RPM/YUM repositories (#14)
• Add limited support for UCL ".include" macro (#15)
• Add basic acceptance test
• Enable GitHub Actions

Changed

• Drop the "inherit" keyword and declare private classes (#13)
• Bump module dependencies and OS versions
• Update PDK version (#16)
• Replace legacy facts with modern facts
• Assorted coding style fixes
• Convert to Puppet Strings

Fixed

• Fix unit tests

1.3.0 - 2021-02-03

Added

• Increase compatible dependency versions in metadata (#8)
• Add parameter $package_ensure (#10)
• Convert to PDK

1.2.0 - 2020-04-07

This release solely changes documentation and metadata.

Changed

• Increase compatible dependency versions in metadata (#7)
• Extend README examples (#5)

Release 1.1.0 - 2019-03-03

This version adds a convenience parameter for simplified hiera usage.

Added

• $rspamd::config parameter to simplify usage from hiera out of the box (#2).

Release 1.0.2 - 2018-01-28

This version fixes a regression introduced in 1.0.0 that caused a non-working APT repo to be added on Debian/Ubuntu by default.

Fixed

• Fix links in this changelog
• Fix repo being added with undef URL by default on Debian/Ubuntu.

Release 1.0.1 - 2018-01-28

This version contains some minor documentation fixes only

Fixed

• Fix links in this changelog

Release 1.0.0 - 2018-01-28

First stable release. This version now requires Puppet 4.9 or greater.

Added

• FreeBSD support (no repo management)

Changed

• Large refactoring to adhere to standard module layout
• $packages_install has been renamed to $package_manage
• Minimum required Puppet version is now 4.9
• Several style/lint related changes

Release 0.2.1 - 2017-07-31

First public release. This version is used by the author on a production system.

Fixed

• Fixes several style/lint related issues

Release 0.2.0 - 2017-07-31

This version removes rmilter support in favor of the rspamd_proxy milter support added in Rspamd 1.6

Version 0.1.0 (unreleased)

Initial development, was not used or tested on a production system