Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

postfixadmin

Configures Postfix Admin, a web based administration interface for Postfix mail servers.
Project URLRSS FeedReport issues

6,379 downloads

5,707 latest version

4.6 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.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 0.2.1 (latest)
  • 0.2.0
  • 0.1.1
released Jul 3rd 2017
This version is compatible with:
  • , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'furhouse-postfixadmin', '0.2.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add furhouse-postfixadmin
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install furhouse-postfixadmin --version 0.2.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: postfix, postfixadmin

Documentation

furhouse/postfixadmin — version 0.2.1 Jul 3rd 2017

Puppet Forge Build Status

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
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  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.