Configuration

Table of content

  1. Configuration Syntax
    1. YAML Datatypes
      1. Scalar
      2. List
      3. Hash
    2. You should know ..
  2. Basic configuration
    1. Folder structure
    2. Module configurations
      1. Example for included module config
      2. Shared server configuration
        1. database
        2. cache
        3. logging
        4. exclusions
      3. Shared module configuration
        1. disabled
        2. timeout

There are two different servers:

Doorman

Detective

Both are "self-sufficient". You have to start each of them stand alone, but it is not required to run each server on each mail server instance.

Configuration Syntax

All Decency configurations are YAML files. YAML (short for: YAML Ain't Markup Language) is a very easy, but very powerful configuration language (not only!!) which was designed to represent complex data structures while still being easily accessible by human maintainers. I will provide a short introduction, for a complete description visit the official YAML website, read the Wikipedia article or try google.

YAML Datatypes

YAML understands three basic data types: hash, list and scalar. Before introducing them in detail, let's start with a short example in YAML:

---
keyname: value

# another scalar
otherkey: "other value"

# list example
list:
  - 1
  - 2
  - 3

# hash example
hash:
  key1: value1
  key2: value2

This example shows all the mentioned data types. The values on the right side could be in double or single quotations, but as long as they do not contain special characters, you can elide them. There are no punctuation marks as comma or dots at the end of a line.

Scalar

keyname: value

This is the scalar data type. A classical key = value construct, where the left side, before the colon, represents a parameter name for identification. The right side, after the colon, represents the actual data/content. The value can be quoted (single or double).

List

list:
  - 1
  - 2
  - 3

In this list (or array) example a core YAML concept is introduced: the indention. First, there is the parameter name "list", then there are the values 1, 2 and 3. The parameter name is written in the same format as for scalars, but has no value on the right side. The values are below, prefixed with a dash "-" and indented in the same left justification (this is important). The actual amount of spaces (not tabs!) is arbitrary, as long you use the same amount for all list items.

You can write lists also in a shorter, but less readable, manner like this:

list: [ 1, 2, 3 ]

Hash

hash:
  key1: value1
  key2: value2

A hash or associative array is akin to lists, but different. In opposition to lists, each item has a parameter name associated with it. Again, the indention is required but the amount of spaces is optional as long as you use the same for all items.

Here is also a short notation:

hash: { key1: "value1", key2: "value2" }

You should know ..

Basic configuration

Each server has its unique configuration options. Those are explained in detail on their configuration pages.

Folder structure

If you've used the debian or the installer package, you would have a configuration directory in /etc/decency, a spool directory in /var/spool/decency, a log file directory in /var/log/decency and a run directory in /var/run/decency. If you've installed via CPAN, you should create this for you self as required.

The structure from the installer is quite simple and should look like this:

Module configurations

All module configurations can be outsourced, as well as written in the main configuration file of the server.

Example for included module config

modules:
  - DNSBL: doorman/dnsbl.yml

Shared server configuration

All servers are capable of three basic configurations: logging, cache and database. The Detective and the Doorman server implement also exclusions.

database

Allowed values: Database Hash
Default: none
Required: yes

Many policy modules require databases. If you enable persistent statistics, the policy server itself requires a database. Therefore it is mandatory to provide a database - even if your policy server does not require any. If the latter is true, simple provide a simple SQLite database, and ignore it (maybe in /tmp-folder).

See cache and database for more detailed informations.

database:
    type: DBD
    args:
        - 'dbi:SQLite:dbname=/tmp/decency.db'

cache

Allowed values: Database Hash
Default: none
Required: yes

The cache is very important, because it increases the performance a lot. Nearly any module requires a cache, therefore it is mandatory to provide some.

See cache and database for more detailed informations.

cache:
    class: FastMmap
    share_file: /tmp/decency.mmap
    expire_time: 24h
    cache_size: 64m

logging

Default: -
Required: yes

You can enable/disable logging facilities. There are three: syslog, console and directory.

logging.syslog

Can be set to 1 or 0. If enabled, the syslog will be used.

Default: 0

logging.console

If enabled, the STDERR console will be used for logging. Either 1 or 0.

Default: 0

logging.directory

Can be set to a path, eg ‘/var/log/decency/'. Will write three log files: info.log, error.log and debug.log - depending on the log level.

logging.log_level

---

logging:
    syslog: 1
    console: 1
    log_level: 20
    directory: /var/log/decency

exclusions

Default: -
Required: no

Exclusions are rules to elide a certain module for a determined sender/recipient domain/address. Eg, if you use DNSBL module in the Doorman server but want to disable DNSBL checks for all mails to recpientdomain.tld, then you define an exclusion.

There are three different ways to define those exclusions, trying to match most use cases.

exclusions.modules

The config exclusions reside here.

exclusions:
    modules:
    
        DNSBL:
            sender_domain:
                - sender.tld
                - somedomain.tld
            recipient_domain:
                - recipient.tld
                - anotherdomain.tld
            sender_address:
                - some@sender.tld
            recipient_address:
                - bla@recipient.tld

exclusions.file

Path to the plain text file containing exclusions. Example of file contents:

sender_domain:DNSBL:sender.tld
sender_domain:DNSBL:somedomain.tld
recipient_domain:GeoWeight:recipient.tld
recipient_domain:GeoWeight:anotherdomain.tld
sender_address:SPF:some@sender.tld
recipient_address:SPF:bla@recipient.tld

exclusions.database

Bool value. Either 0 or 1.

Detective SQL Example (SQLite)

-- TABLE: exclusions_detective (SQLITE):
CREATE TABLE EXCLUSIONS_DETECTIVE (value varchar(255),
    type varchar(20), module varchar(32), id INTEGER PRIMARY KEY);
CREATE UNIQUE INDEX EXCLUSIONS_DETECTIVE_MODULE_TYPE_VALUE ON
    EXCLUSIONS_DETECTIVE (module, type, value);

Doorman SQL Example (SQLite):

-- TABLE: exclusions_DETECTIVE (SQLITE):
CREATE TABLE EXCLUSIONS_DOORMAN (value varchar(255),
    type varchar(20), module varchar(32), id INTEGER PRIMARY KEY);
CREATE UNIQUE INDEX EXCLUSIONS_DOORMAN_MODULE_TYPE_VALUE ON
    EXCLUSIONS_DETECTIVE (module, type, value);

Shared module configuration

Those configuration parameters can be set to any module

disabled

Default: 0
Required: no
Allowed values: Bool (0 or 1)

Each module can be disabled. Set this value to 1 in the module configuration (inline or file) and the module will not be loaded. This is useful, if you want to disable a module but not remove it from the configuration.

timeout

Default: 15 (Doorman), 30 (Detective)
Required: no
Allowed values: Integer (seconds)

Timeout for a single module check. For Doorman server, this should not be to long cause it delays the mail server and reduces the amount of receivable mails. Filtering mails in the Detective level does not slow down the amount of receivable mail, but increases the amount of mails in the queue and can thereby delay delivery.