Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with postfixadmin
   • Notice
   • What postfixadmin affects
   • Setup requirements
   • Beginning with postfixadmin
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
   • postfixadmin
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module
8. Todo

Overview

Downloads, installs and configures Postfix Admin.

Module Description

Postfix Admin provides a web interface to manage mailboxes, virtual domains and more. It requires PHP, Postfix and MySQL or PostgreSQL.

Besides a web interface, Postfix Admin also ships with a command line interface, postfixadmin-cli.

The parameter config_file_template has been renamed to custom_config_file in version 0.2.0, and is now a file-based resource, instead of template-based.

Setup

Notice

The parameter config_file_template has been renamed to custom_config_file in version 0.2.0, and is now a file-based resource, instead of template-based.

What postfixadmin affects

• Downloads, extracts and configures (but in a disabled state) Postfix Admin, version 3.1.
• Creates a postfixadmin user and group on Red Hat based distributions.
• Creates the parent directories for postfixadmin archive and extracted files.

Setup Requirements

This module expect either camptocamp-archive or puppet-archive to be installed. Neither are specified as dependency, but camptocamp-archive is the default.

By default, Postfix Admin will be extracted to /var/cache/puppet/archive and installed in /opt/postfixadmin-3.1, based on the specified version. Both parent directories should exist (and can be managed by setting manage_dirs to true).

Beginning with postfixadmin

To simply install postfixadmin without any configuration, (don't really) use:

class { '::postfixadmin':
  manage_dirs => true,
  configured  => true,
}

Usage

By default, postfixadmins' config.inc.php file loads config.local.php, which is the file this module manages. The bare minimum is provided, but can be easily expanded by passing a hash to options_hash.

class { '::postfixadmin':
  manage_dirs  => true,
  configured   => true,
  db_type      => 'mysqli',
  db_host      => 'localhost',
  db_user      => 'postfix',
  db_pass      => 'postfix',
  db_name      => 'postfix',
  encrypt      => 'dovecot:SHA512-CRYPT',
  options_hash => {
    'admin_email'         => 'admin@example.com',
    'password_validation' => [
      "/.{5}/'            => 'password_too_short 5",
      "/([a-zA-Z].*){3}/' => 'password_no_characters 3",
    ],
  }
}

Reference

Class: postfixadmin

When this class is declared with the default options, Puppet:

• Downloads a postfixadmin archive, version, and extracts it to install_dir/version.
• Creates a new configuration file, config.local.php.
• Removes the installer directory from install_dir/version.
• Changes the owner and group of install_dir/version/{logs,temp,config.local.php} to www-data on Debian based distributions, and to postfixadmin on RedHat and its derivatives.
• Creates a system owner and group on RedHat based distributions, based on manage_user and process.

If you would just declare the default postfixadmin class, Postfix Admin will be installed in a disabled state, since configured is set to false by default.

Parameters within postfixadmin:

version

Sets the version of Postfix Admin. Default: 3.1.

class { '::postfixadmin':
  version => '3.1',
}

checksum

Sets the checksum type, required for validating the Postfix Admin tarfile. Default: 36eaed433c673382fb5d513bc3b0d2685bf3169ead6065293d3a0f8f6d262aa4.

class { '::postfixadmin':
  checksum_type => '36eaed433c673382fb5d513bc3b0d2685bf3169ead6065293d3a0f8f6d262aa4',
}

checksum

Sets the checksum method, required for validating the Postfix Admin tarfile. Default: sha256.

class { '::postfixadmin':
  checksum => 'sha256',
}

archive_provider

Sets the archive_provider, required for downloading and extracting the Postfix Admin tarfile. Default: camptocamp.

class { '::postfixadmin':
  archive_provider => 'camptocamp',
}

manage_dirs

Creates the parent directories for install_dir and puppet_cache. Default: false.

class { '::postfixadmin':
  manage_dirs => false,
}

manage_user

Creates a system user and group, for ownership of install_dir/{logs,temp,config.local.php}. Default: true if facts[:os]['family'] == 'RedHat'.

class { '::postfixadmin':
  manage_user => false,
}

puppet_cache

Sets the parent directory for the files downloaded by the archive_provider. Default: /var/cache/puppet.

class { '::postfixadmin':
  puppet_cache => '/var/cache/puppet',
}

archive_dir

Sets the directory which contains the files downloaded by the archive_provider. Default: /var/cache/puppet/archive.

class { '::postfixadmin':
  archive_dir => '/var/cache/puppet/archive',
}

install_dir

Sets the parent directory for the Postfix Admin installation. Default: /opt.

class { '::postfixadmin':
  install_dir => '/opt',
}

process

Sets the user and group of the Postfix Admin web application. Default: Depends on your operating system.

• Debian: www-data
• Red Hat: postfixadmin

class { '::postfixadmin':
  process => 'www-data',
}

configured

Enables the use of the Postfix Admin web application. Default: false.

class { '::postfixadmin':
  configured => 'false',
}

db_type

Sets the type of the Postfix Admin database. Default: mysqli.

class { '::postfixadmin':
  db_type => 'mysqli',
}

db_host

Sets the host of the Postfix Admin database. Default: localhost.

class { '::postfixadmin':
  db_host => 'localhost',
}

db_user

Sets the user of the Postfix Admin database. Default: postfix.

class { '::postfixadmin':
  db_user => 'postfix',
}

db_pass

Sets the pass of the Postfix Admin database. Default: postfix.

class { '::postfixadmin':
  db_pass => 'postfix',
}

db_name

Sets the name of the Postfix Admin database. Default: postfix.

class { '::postfixadmin':
  db_name => 'postfix',
}

encrypt

Sets the way passwords are encrypted. Default: dovecot:SHA512-CRYPT.

class { '::postfixadmin':
  encrypt => 'dovecot:SHA512-CRYPT',
}

options_hash

You can configure other parameters by passing a hash to options_hash. Default: {}.

See config.inc.php from the Postfix Admin github repository for a full reference.

class { '::postfixadmin':
  options_hash => {
    'admin_email'         => 'admin@example.com',
    'smtp_server'         => 'mail.example.com',
    'domain_path'         => 'NO',
    'domain_in_mailbox'   => 'NO',
    'password_validation' => [
      "/.{5}/'            => 'password_too_short 5",
      "/([a-zA-Z].*){3}/' => 'password_no_characters 3",
    ],
  }
}

custom_config_file

You can use a file for creating the config.local.php file: Default: undef.

class { '::postfixadmin':
  custom_config_file => 'postfixadmin/my_custom_template.txt',
}

postfixadmin/files/my_custom_template.txt:

// Change the text between EOM.
$CONF['welcome_text'] = <<<EOM
Hi,

Welcome to your new account.
EOM;

custom_functions_file

You can use a file for adding custom functions to config.local.php file: Default: undef.

class { '::postfixadmin':
  custom_functions_file => 'postfixadmin/my_custom_function.txt',
}

postfixadmin/files/my_custom_function.txt:

function language_hook($PALANG, $language) {
    switch ($language) {
        case "de":
            $PALANG['x_whatever'] = 'foo';
            break;
        case "fr":
            $PALANG['x_whatever'] = 'bar';
            break;
        default:
            $PALANG['x_whatever'] = 'foobar';
    }
    return $PALANG;
}

Limitations

• Requires manual seeding of database, ie $ curl -v https://postfixadmin.example.com/setup.php
• Does not manage a webserver.
• Does not manage a database.
• Does not manage PHP.
• Does not manage SELinux.

Development

This project uses rspec-puppet and beaker to ensure the module works as expected and to prevent regressions.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Todo

• Refactor for Puppet 4.
• Revisit manage_dirs.
• Automate seeding of database.