Forge Home

vmail

Manage mail configurations

11,657 downloads

6,370 latest version

3.7 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.1 (latest)
  • 0.1.0
released Sep 28th 2017
This module has been deprecated by its author since Nov 4th 2019.

The reason given was: No longer maintained

Start using this module

Documentation

fraenki/vmail — version 0.1.1 Sep 28th 2017

Table of Contents

Overview

This module manages data-driven mail configuration files. It does NOT manage the mail service itself.

Module Description

You define your mail environment in HIERA - domains, addresses, routes, policies - and vmail will put this data in application-specific files. Its focus is on DATA.

Features:

  • Use HIERA to define your mail environment
  • Choose from pre-defined schemes (currently only Postfix)
  • Contribute! Create schemes for other MTAs

Currently only file-backends are supported, but it should be possible to support other backends/databases as well.

NOTE: To manage passwd-like virtual user databases, you may want to checkout the vpasswd module.

Requirements

Unlike many modules, vmail does not manage your mail service nor will it try to install any package. You need additional modules to manage your MTAs main configuration and service.

Experimental Feature

This module requires iterations/lambdas. You need puppet 3.2+ and the future parser enabled in order to use this module.

Dependencies

Currently requires the puppetlabs/concat and puppetlabs/stdlib module. I recommend to use my vpasswd module for virtual user and e-mail address management. Besides that thias-postfix and jproyo-dovecot are useful to manage the mail services.

Usage

First, you need to define your mail environment in HIERA. While this module tries to be as flexible as possible, it requires you to use the expected syntax.

Setup HIERA: Simple example (YAML)

virtual_domains:
  company.com:
    aliases: [the-company.com, company.org, mycompany.net]
  thecompany.co.uk:
  theproduct.com:

NOTE: This example does not cover the user configuration. You may want to have a look at the vpasswd module for an example user configuration.

Setup HIERA: Complex example (YAML)

virtual_domains:
  company.com:
    aliases: [the-company.com, company.org, mycompany.net]
    masquerades: [www.company.com, mx1.company.com, mx2.company.com]
  thecompany.co.uk:
  theproduct.com:
  example.com:
    hosts: [mx3.company.com, mx4.company.com]
  customer1.com:
    type: backupmx
  customer2.com:
    type: backupmx
    hosts: [mx3.company.com, mx4.company.com]
  portal.company.com:
    type: relay
    host: mx-int.company.com
  test.company.com:
    type: relay
    host: mx-test.company.com
    port: 2525

NOTE: This example does not cover the user configuration. You may want to have a look at the vpasswd module for an example user configuration.

Basic Usage

The most basic, yet fully-working example:

$virtual_domains = hiera_hash('virtual_domains')
$virtual_accounts = hiera_hash('virtual_accounts')

class { 'vmail::postfix':
  domain_hash => $virtual_domains,
  user_hash   => $virtual_accounts,
}

This will create a bunch of files for postfix:

  • aliases(.db)
  • canonical(.db)
  • relay_domains
  • relocated(.db)
  • transport(.db)
  • virtual(.db)
  • virtual_alias(.db)
  • virtual_domains

Complex Example

You may want to customize the whole thing by using vmail::file directly:

$virtual_domains = hiera_hash('my_domains')
$virtual_accounts = hiera_hash('my_accounts')

$postfixdir = '/foo/postfix/instance3/conf'

vmail::file { "${postfixdir}/virtual_alias":
  domain_hash => $virtual_domains,
  file        => "${postfixdir}/virtual_alias",
  group       => 'mail_instance3',
  owner       => 'mail_instance3',
  template    => 'vmail/postfix/virtual_alias.erb',
  user_hash   => $virtual_accounts,
}

vmail::postfix::dbfile { "${postfixdir}/virtual_alias":
  file     => "${postfixdir}/virtual_alias",
}

Reference

Feature overview

Configure domain aliases:

company.com:
  aliases: [the-company.com, company.org, mycompany.net]

Tie a domain configuration to specific hosts:

company.com:
  hosts: [mx3.company.com, mx4.company.com]

Create a backup MX configuration:

company.com:
  type: backupmx

Relay mail to a specific host (and optional port):

company.com:
  type: relay
  host: mx-test.company.com
  port: 2525

HIERA attribute reference

All currently supported attributes:

virtual_domains:
  company.com:
    aliases: [the-company.com, company.org, mycompany.net]
    masquerades: [www.company.com, mx1.company.com, mx2.company.com]
  example.com:
    hosts: [mx3.company.com, mx4.company.com]
  customer1.com:
    type: backupmx
  portal.company.com:
    type: relay
    host: mx-int.company.com
  test.company.com:
    type: relay
    host: mx-test.company.com
    port: 2525

Module parameter reference

All currently supported parameters:

class { 'vmail::postfix':
  domain_hash => $virtual_domains,
  user_hash   => $virtual_accounts,
}

vmail::file { "postfix virtual_alias file":
  domain_hash => $virtual_domains,
  file        => '/foo/postfix/virtual_alias',
  group       => 'mail',
  owner       => 'mail',
  template    => 'vmail/postfix/virtual_alias.erb',
  user_hash   => $virtual_accounts,
}

vmail::postfix::dbfile { "virtual_alias":
  file     => '/foo/postfix/virtual_alias',
}

Performance

This module does not scale well. The performance suffers from the future parser and the large number of objects being created during a puppet run, or maybe it's the concat module. If you find a way to improve performance, please let me know.

Iterations/Lambdas

Why does this module depend on experimental features like iterations/lambdas? I wanted to keep the defined types simple, but still make it possible to use the same mail data multiple times (for multiple files, multiple applications). To avoid duplicate declarations I needed to use iterations (and unique names for every object, hence separators were born).

Development

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.