PostfixAdmin Cookbook
Installs and configures PostfixAdmin, a web based interface used to manage mailboxes, virtual domains and aliases.
Also creates the required MySQL or PostgreSQL database and tables.
Table of Contents
- Requirements
- Generated Passwords
- Attributes
- Recipes
- Resources
- Usage Example
- PostgreSQL Support
- Deploy with Docker
- Testing
- Contributing
- TODO
- License and Author
Requirements
Please, if you want to upgrade the postfixadmin
cookbook version from the 1.x
branch, see the CHANGELOG.
Supported Platforms
This cookbook has been tested on the following platforms:
- Amazon Linux
- CentOS
- Debian
- Fedora
- Ubuntu
Please, let us know if you use it successfully on any other platform.
Required Cookbooks
- apache2
- ark
- database
- encrypted_attributes
- mysql
- chef_nginx
- compat_resource
- openssl
- php
- php-fpm
- postgresql
- ssl_certificate
- yum-epel
Required Applications
- Chef
12.5
or higher. - Ruby
2.2
or higher.
Only Postfix Admin version 3
or higher is supported by this cookbook. For older versions, use cookbook versions < 3
.
Other Requirements
On RedHat based platforms, you need to disable or configure SELinux correctly to work with mysql
cookbook. You can use the selinux::disabled
recipe for that.
Generated Passwords
The first time it runs, automatically generates some passwords if not specified. Generated passwords are:
From the PostfixAdmin Default Recipe
postfixadmin/setup_password
postfixadmin/setup_password_salt
postfixadmin/setup_password_encrypted
postfixadmin/database/password
When MySQL Is Used
postfixadmin/mysql/server_root_password
When PostgreSQL Is Used
postgresql/password/postgres
Attributes
Attribute | Default | Description |
---|---|---|
node['postfixadmin']['version'] |
'3.0.2' |
PostfixAdmin version |
node['postfixadmin']['url'] |
calculated | PostfixAdmin download URL |
node['postfixadmin']['checksum'] |
calculated | PostfixAdmin download file checksum |
node['postfixadmin']['port'] |
calculated | PostfixAdmin listen port |
node['postfixadmin']['server_name'] |
calculated | PostfixAdmin server name |
node['postfixadmin']['server_aliases'] |
[] |
PostfixAdmin server aliases |
node['postfixadmin']['headers'] |
{} |
PostfixAdmin HTTP headers to set as hash |
node['postfixadmin']['ssl'] |
false |
enables HTTPS (with SSL) |
node['postfixadmin']['encrypt_attributes'] |
false |
Whether to encrypt PostfixAdmin attributes containing credential secrets. |
node['postfixadmin']['setup_password'] |
calculated | PostfixAdmin Setup Password (required for chef-solo) |
node['postfixadmin']['setup_password_salt'] |
calculated | PostfixAdmin password salt (required for chef-solo) |
node['postfixadmin']['web_server'] |
'apache' |
Web server to use: 'apache' , 'nginx' or false |
node['postfixadmin']['setup_password_encrypted'] |
calculated | PostfixAdmin encrypted Password |
node['postfixadmin']['database']['manage'] |
calculated | Whether to manage database creation. |
node['postfixadmin']['database']['type'] |
'mysql' |
PostfixAdmin database type. Possible values are: 'mysql' , 'postgresql' (Please, see [below](#postgresql-support)<a></a>) |
node['postfixadmin']['database']['name'] |
'postfix' |
PostfixAdmin database name |
node['postfixadmin']['database']['host'] |
'127.0.0.1' |
PostfixAdmin database hostname or IP address |
node['postfixadmin']['database']['user'] |
'postfix' |
PostfixAdmin database login username |
node['postfixadmin']['database']['password'] |
calculated | PostfixAdmin database login password (requried for chef-solo) |
node['postfixadmin']['mysql']['instance'] |
'default' |
PostfixAdmin MySQL instance name to run by the mysql_service LWRP from the mysql cookbook |
node['postfixadmin']['mysql']['data_dir'] |
calculated | PostfixAdmin MySQL data files path |
node['postfixadmin']['mysql']['port'] |
'3306' |
PostfixAdmin MySQL port |
node['postfixadmin']['mysql']['run_group'] |
calculated | PostfixAdmin MySQL system group |
node['postfixadmin']['mysql']['run_user'] |
calculated | PostfixAdmin MySQL system user |
node['postfixadmin']['mysql']['version'] |
calculated | PostfixAdmin database MySQL version to install |
node['postfixadmin']['conf']['encrypt'] |
'md5crypt' |
The way do you want the passwords to be crypted |
node['postfixadmin']['conf']['domain_path'] |
'YES' |
Whether you want to store the mailboxes per domain |
node['postfixadmin']['conf']['domain_in_mailbox'] |
'NO' |
Whether you want to have the domain in your mailbox |
node['postfixadmin']['conf']['fetchmail'] |
'NO' |
Whether you want fetchmail tab |
node['postfixadmin']['packages']['requirements'] |
calculated | PostfixAdmin required packages array |
node['postfixadmin']['packages']['mysql'] |
calculated | PostfixAdmin required packages array for MySQL support |
node['postfixadmin']['packages']['postgresql'] |
calculated | PostfixAdmin required packages array for PostgreSQL support |
node['boxbilling']['mysql']['server_root_password'] |
calculated | PostfixAdmin MySQL root password. |
node['postfixadmin']['map_files']['path'] |
'/etc/postfix/tables' |
Path to generate map-files into |
node['postfixadmin']['map_files']['mode'] |
00640 |
Map-files file-mode bits |
node['postfixadmin']['map_files']['owner'] |
'root' |
Map-files files owner |
node['postfixadmin']['map_files']['group'] |
'postfix' |
Map-files files group |
node['postfixadmin']['map_files']['list'] |
calculated | An array with map file names to generate |
node['postfixadmin']['php-fpm']['pool'] |
'postfixadmin' |
PHP-FPM pool name to use with PostfixAdmin. |
The HTTPS Certificate
This cookbook uses the ssl_certificate
cookbook to create the HTTPS certificate. The namespace used is node['postfixadmin']
. For example:
node.default['postfixadmin']['common_name'] = 'postfixadmin.example.com'
include_recipe 'postfixadmin'
See the ssl_certificate
namespace documentation for more information.
Encrypted Attributes
This cookbook can use the encrypted_attributes cookbook to encrypt the secrets generated during the Chef Run. This feature is disabled by default, but can be enabled setting the node['postfixadmin']['encrypt_attributes']
attribute to true
. For example:
include_recipe 'encrypted_attributes::users_data_bag'
node.default['postfixadmin']['encrypt_attributes'] = true
inclure_recipe 'postfixadmin'
This will create the following encrypted attributes:
node['postfixadmin']['setup_password']
: PostfixAdmin setup.php setup password.node['postfixadmin']['setup_password_encrypted']
: PostfixAdmin setup.php setup password encrypted with a salt.node['postfixadmin']['mysql']['server_root_password']
: MySQL root user password.node['postfixadmin']['database']['password']
: MySQL PostfixAdmin user password.
Read the chef-encrypted-attributes
gem documentation to learn how to read them.
Warning: When PostgreSQL is used, the database root password will still remain unencrypted in the node['postgresql']['password']['postgres']
attribute due to limitations of the postgresql cookbook.
Recipes
postfixadmin::default
Installs and configures PostfixAdmin.
postfixadmin::map_files
Installs PostfixAdmin SQL map files to be used by Postfix.
postfixadmin::mysql
Installs MySQL server for PostfixAdmin.
postfixadmin::postgresql
Installs PostgreSQL server for PostfixAdmin.
Resources
postfixadmin_admin[user]
Create or delete a PostfixAdmin admin user.
This kind of user is used to create the domains and mailboxes, and must be used before any other resource from this cookbook.
postfixadmin_admin Actions
create
: Create a PostfixAdmin admin user (default).delete
: Remove a PostfixAdmin admin user.
postfixadmin_admin Properties
Property | Default | Description |
---|---|---|
user | name attribute | Username |
password | required | Password |
setup_password | calculated | PostfixAdmin Setup Password |
superadmin | true |
Whether it has access to all domains |
domains | [] |
List of domains it has access to |
active | true |
Active status |
login_username | optional | Admin user to use for its creation |
login_password | optional | Admin password to use for its creation |
ssl | node['postfixadmin']['ssl'] |
Whether to use SSL on HTTP requests |
If you don't provide login_username
, it will use the setup.php to create the admin. Usually this is used only to create the first administrator.
postfixadmin_admin Example
postfixadmin_admin '[email protected]' do
password 'sup3r-s3cr3t-p4ss'
action :create
end
postfixadmin_admin '[email protected]' do
password '4n0th3r-p4ss'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_domain[domain]
Create or delete a domain.
postfixadmin_domain Actions
create
delete
postfixadmin_domain Properties
Property | Default | Description |
---|---|---|
domain | name attribute | Domain name |
description | '' |
Domain description |
aliases | 10 |
Maximum number of aliases |
mailboxes | 10 |
Maximum number of mailboxes |
active | true |
Active status |
default_aliases | false |
Whether to include default aliases |
login_username | required | Admin user to use |
login_password | required | Admin password |
ssl | node['postfixadmin']['ssl'] |
Whether to use SSL on HTTP requests |
postfixadmin_domain Example
# admin user copied from the previous example
postfixadmin_domain 'foobar.com' do
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_mailbox[mailbox]
Create or delete a mailbox.
postfixadmin_mailbox Actions
create
delete
postfixadmin_mailbox Properties
Property | Default | Description |
---|---|---|
mailbox | name attribute | Mailbox address to create |
password | required | Mailbox password |
name | '' |
The name of the mailbox owner |
active | true |
Active status |
false |
Whether to send a welcome email | |
login_username | required | Admin user to use |
login_password | required | Admin password |
ssl | node['postfixadmin']['ssl'] |
Whether to use SSL on HTTP requests |
postfixadmin_mailbox Example
# admin user copied from the previous example
postfixadmin_mailbox '[email protected]' do
password 'alice'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_alias[address]
Create or delete a mailbox alias.
postfixadmin_alias Actions
create
delete
postfixadmin_alias Properties
Property | Default | Description |
---|---|---|
address | name attribute | Alias address |
goto | required | Destination mailbox address |
active | true |
Active status |
login_username | required | Admin user to use |
login_password | required | Admin password |
ssl | node['postfixadmin']['ssl'] |
Whether to use SSL on HTTP requests |
postfixadmin_alias Example
# admin user copied from the previous example
postfixadmin_alias '[email protected]' do
goto '[email protected]'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_alias_domain[address]
Create or remote a domain alias.
The domain name used as alias_domain
must already exist: in other words, it needs to be created previously with postfixadmin_domain
resource.
postfixadmin_alias_domain Actions
create
delete
postfixadmin_alias_domain Properties
Property | Default | Description |
---|---|---|
alias_domain | name attribute | Alias domain |
target_domain | required | Target domain |
active | true |
Active status |
login_username | required | Admin user to use |
login_password | required | Admin password |
ssl | node['postfixadmin']['ssl'] |
Whether to use SSL on HTTP requests |
postfixadmin_alias_domain Example
# admin user copied from the previous example
postfixadmin_alias_domain 'aliasdomain.com' do
target_domain 'foobar.com'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
Usage Example
Including in a Cookbook Recipe
A complete example:
include_recipe 'postfixadmin::default'
include_recipe 'postfixadmin::map_files'
# or include them in your run-list
postfixadmin_admin '[email protected]' do
password 'sup3r-s3cr3t-p4ss'
action :create
end
postfixadmin_domain 'foobar.com' do
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_mailbox '[email protected]' do
password 'alice'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_alias '[email protected]' do
goto '[email protected]'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_domain 'aliasdomain.com' do
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
postfixadmin_alias_domain 'aliasdomain.com' do
target_domain 'foobar.com'
login_username '[email protected]'
login_password 'sup3r-s3cr3t-p4ss'
end
Don't forget to include the postfixadmin
cookbook as a dependency in the metadata.
# metadata.rb
# [...]
depends 'postfixadmin'
Including in the Run List
Another alternative is to include the recipes in your Run List.
{
"name": "mail.example.com",
"[...]": "[...]"
"run_list": [
"[...]": "[...]",
"recipe[postfixadmin]",
"recipe[postfixadmin::map_files]"
]
}
PostgreSQL Support
PostfixAdmin with PostgreSQL may not work properly on some platforms: See for example postgresql
cookbook issue #249. Any feedback you can provide regarding the PostgreSQL support will be greatly appreciated.
PostgreSQL Versions < 9.3
If you are using PostgreSQL version < 9.3
, you may need to adjust the shmmax
and shmall
kernel parameters to configure the shared memory. You can see the example used for the integration tests.
Deploy with Docker
You can use the Dockerfile included in the cookbook source code to run the cookbook inside a container:
$ docker build -t chef-postfixadmin .
$ docker run -d -p 8080:80 chef-postfixadmin
The sample Dockerfile:
FROM zuazo/chef-local:debian-7
COPY . /tmp/postfixadmin
RUN berks vendor -b /tmp/postfixadmin/Berksfile $COOKBOOK_PATH
RUN chef-client -r "recipe[apt],recipe[postfixadmin]"
CMD ["apache2", "-D", "FOREGROUND"]
See the chef-local container documentation for more examples.
Testing
See TESTING.md.
ChefSpec Matchers
postfixadmin_admin(user)
Helper method for locating a postfixadmin_admin
resource in the collection.
resource = chef_run.postfixadmin_admin(user)
expect(resource).to notify('service[apache2]').to(:reload)
create_postfixadmin_admin(user)
Assert that the Chef Run creates a PostfixAdmin admin user.
expect(chef_run).to create_postfixadmin_admin(user)
delete_postfixadmin_admin(path)
Assert that the Chef Run deletes a PostfixAdmin admin user.
expect(chef_run).to delete_postfixadmin_admin(user)
postfixadmin_alias(address)
Helper method for locating a postfixadmin_alias
resource in the collection.
resource = chef_run.postfixadmin_alias(address)
expect(resource).to notify('service[apache2]').to(:reload)
create_postfixadmin_alias(address)
Assert that the Chef Run creates a PostfixAdmin alias.
expect(chef_run).to create_postfixadmin_alias(address)
delete_postfixadmin_alias(address)
Assert that the Chef Run deletes a PostfixAdmin alias.
expect(chef_run).to delete_postfixadmin_alias(address)
postfixadmin_alias_domain(alias_domain)
Helper method for locating a postfixadmin_alias_domain
resource in the collection.
resource = chef_run.postfixadmin_alias_domain(alias_domain)
expect(resource).to notify('service[apache2]').to(:reload)
create_postfixadmin_alias_domain(alias_domain)
Assert that the Chef Run creates a PostfixAdmin alias domain.
expect(chef_run).to create_postfixadmin_alias_domain(alias_domain)
delete_postfixadmin_alias_domain(alias_domain)
Assert that the Chef Run deletes a PostfixAdmin alias domain.
expect(chef_run).to delete_postfixadmin_alias_domain(alias_domain)
postfixadmin_domain(domain)
Helper method for locating a postfixadmin_domain
resource in the collection.
resource = chef_run.postfixadmin_domain(domain)
expect(resource).to notify('service[apache2]').to(:reload)
create_postfixadmin_domain(domain)
Assert that the Chef Run creates a PostfixAdmin domain.
expect(chef_run).to create_postfixadmin_domain(domain)
delete_postfixadmin_domain(domain)
Assert that the Chef Run deletes a PostfixAdmin domain.
expect(chef_run).to delete_postfixadmin_domain(domain)
postfixadmin_mailbox(mailbox)
Helper method for locating a postfixadmin_mailbox
resource in the collection.
resource = chef_run.postfixadmin_domain(mailbox)
expect(resource).to notify('service[apache2]').to(:reload)
create_postfixadmin_mailbox(mailbox)
Assert that the Chef Run creates a PostfixAdmin mailbox.
expect(chef_run).to create_postfixadmin_mailbox(mailbox)
delete_postfixadmin_mailbox(domain)
Assert that the Chef Run deletes a PostfixAdmin mailbox.
expect(chef_run).to delete_postfixadmin_mailbox(mailbox)
Contributing
Please do not hesitate to open an issue with any questions or problems.
See CONTRIBUTING.md.
TODO
See TODO.md.
License and Author
Author: | Xabier de Zuazo ([email protected]) |
Contributor: | chrludwig |
Contributor: | MATSUI Shinsuke (poppen) |
Contributor: | Brian Racer |
Contributor: | Bernhard Weisshuhn (a.k.a. bernhorst) |
Copyright: | Copyright (c) 2015, Xabier de Zuazo |
Copyright: | Copyright (c) 2014-2015, Onddo Labs, SL. |
License: | Apache License, Version 2.0 |
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.