Install Guide - Beta 2

Ideally, you should start with a fresh Debian Stretch/stable system, it should 'just work'. Of course there are always a few things here and there I'd like to improve. In any case, and as always, you should try this on a test system and make sure this is for you before using it in production.

Don't hesitate to give me feedback (good, bad or ugly), you can send an email here: mailboy.ff@manurevah.com.

Preface

Mailboy uses Free Software usually already packaged for your GNU system. In this tutorial I will be using Debian Stretch (stable), things should be very similar on other systems, especially those based on Debian, however, this has not been tested on anything other than Debian Stretch.

We will need the following software :

Ideally Apache would be useful if you'd like to use Mailboy's web interface, you can of course use any webserver you want, this is slightly beyond this howto.

Also note, this setup can be customised in many ways, for example you could chose to install each service on a separate server. You might also want to be more or less strict about how your MDA deals with other servers (HELO, PTR records, etc). The goal here is to setup something complete with OK default options to help you take control over your emails.

Mail Server

We'll start with Mailboy itself. Mailboy is really 2 things, a database that will be used by all the server bits and a web interface for users and admins to configure stuff.

Prepare Mailboy

We need to use a MariaDB database server, if you have one, great. If not, install MySQL:

apt install mariadb-server

Get and upack Mailboy

cd /usr/local/
wget https://mailboy.manurevah.com/packages/mailboy_0.7.8.tar.xz
tar Jxvf mailboy_0.7.8.tar.xz
mv mailboy_0.7.8 mailboy
cd mailboy

If you get an error like :

tar (child): xz: Cannot exec: No such file or directory"

Then you might want to install xz-utils:

apt install xz-utils

Next, import Mailboy's database into MySQL.

cd /usr/local/mailboy/
mysql -uroot -p < install/database.sql

NOTE: If you didn't set a root password for MariaDB (MySQL) then you can just press enter at the password prompt.

We need to create MySQL users to be used by mail services to query the database. We will create here 2 users, 'mailuser' will have read-only permissions and 'mailadmin' will have read-write access.

We'll also create our first Mailboy user and provide her with administrator privileges. In this example I will create the user bob@example.org, of course you should replace this.

In an attempt to make life easier I've added the file install/mailboy_init.sql which simply needs to be edited.

Replace the passwords for each user (in red: mailuser_password, mailadmin_password, bobs_password). We'll need these passwords later on (so don't lose them).

USE `mailboy`;

/* Mailboy User (read-only user for Postix, Amavis, Ejabberd, etc
   REPLACE mailuser_password with an actual password */
GRANT SELECT ON mailboy.* TO mailuser@localhost IDENTIFIED BY 'mailuser_password';

/* Mailboy Admin (read-write user, for Mailboy admin interface
   REPLACE mailuser_password with an actual password */
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER,
CREATE TEMPORARY TABLES, CREATE VIEW, SHOW VIEW, CREATE ROUTINE,
ALTER ROUTINE, EXECUTE ON mailboy.* TO 'mailadmin'@'localhost' IDENTIFIED BY 'mailadmin_password';

FLUSH PRIVILEGES;

/* Add a master user account - example for bob@example.org */
INSERT INTO virtual_domains (id, name) VALUES (1, 'example.org');
INSERT INTO virtual_users (id, domain_id, user, password, xmpp, admin) VALUES (1, 1, 'bob', CONCAT("{SHA512-CRYPT}", ENCRYPT('bobs_password', '$6$')), 1, 1);

Now we can execute the file in MySQL

mysql -uroot -p < install/mailboy_init.sql

The last step is to fill out the config files, it's pretty simple, copy the config files, then edit them. There's very little to change.

cd /usr/local/mailboy/config/
cp config.php.example config.php
cp db_config.php.example db_config.php
cp db_config.sh.example db_config.sh

Now edit the files, in most cases you'll just need to fill out the passwords.

We created 2 MySQL users, mailuser and mailadmin, we'll also need to create a system user mailboy. We will use mailboy's home directory for email storage.

Let's do:

groupadd -g 5000 mailboy && useradd -g mailboy -u 5000 mailboy -d /home/mailboy -m -k /dev/null

Dovecot

Install Dovecot:

apt install dovecot-common dovecot-imapd dovecot-pop3d dovecot-managesieved dovecot-mysql

The simplest way to start with Dovecot's configuration is to backup the default conf file and download a new one. I've provided the files directly in the package, so if you've used /usr/local/mailboy/ you can do as follows:

mv /etc/dovecot/dovecot-sql.conf.ext /etc/dovecot/dovecot-sql.conf.ext.BKP
cp /usr/local/mailboy/install/dovecot/dovecot-sql.conf.ext /etc/dovecot/dovecot-sql.conf.ext
chmod 640 /etc/dovecot/dovecot-sql.conf.ext
chown root:dovecot /etc/dovecot/dovecot-sql.conf.ext

Edit /etc/dovecot/dovecot-sql.conf.ext, we need to change 'mailuser_password' to the actual password (defined above in db_config.sh):

connect = host=127.0.0.1 dbname=mailboy user=mailuser password=mailuser_password

Copy over a global sieve file, this will filter spam for all users:

cp /usr/local/mailboy/install/dovecot/globalsieverc /home/mailboy/globalsieverc

We could have to edit a bunch of conf.d files... OR I just could include the files already edited for you to copy over... (If you want, you can make a backup of /etc/dovecot/conf.d).

cp /usr/local/mailboy/install/dovecot/conf.d/* /etc/dovecot/conf.d/

We'll mostly need to edit 3 files to make everything work, 10-ssl.conf, 15-lda.conf and 90-quota.conf.

10-ssl.conf: In this file, make sure the certificates are correct, ssl_cert and ssl_key should point to your cert and key files.

And also, let's generate a Diffie Hellman file for dovecot (warning: this could take a year or two):

openssl dhparam 4096 > /etc/dovecot/dh.pem

15-lda.conf: Change postmaster_address to something RFC-happy (like postmaster@YOURDOMAIN.TLD).

90-quota.conf: Optional, at some point you might want to come back to this file to setup quota warnings.

Amavis, ClamAV and SpamAssassin

Postfix will use Amavis as a scanner, Amavis will use ClamAV to scan for viruses and Spamassassin to check for spams. Let's install them...:

apt install amavisd-new spamassassin clamav clamav-base clamav-daemon clamav-freshclam

Edit /etc/amavis/conf.d/15-content_filter_mode to uncomment the following 4 lines:

@bypass_virus_checks_maps = (
   \%bypass_virus_checks, \@bypass_virus_checks_acl, \$bypass_virus_checks_re);

@bypass_spam_checks_maps = (
   \%bypass_spam_checks, \@bypass_spam_checks_acl, \$bypass_spam_checks_re);

Allow per user policies, for this, edit /etc/amavis/conf.d/50-user and add the following, and change 'mailuser_password' according to what you've defined. (Of course, the following goes before the "Do not modify" line):

@lookup_sql_dsn = (
	['DBI:mysql:database=mailboy;host=127.0.0.1;port=3306',
	'mailuser',
	'mailuser_password']);

$sql_select_policy = 'SELECT * FROM view_users_policies WHERE email IN(%k)';

$sql_select_white_black_list = undef;

Enable spamassassin:

systemctl enable spamassassin.service

Add the user 'clamav' to the group 'amavis' and 'clamav' to the group 'amavis':

adduser amavis clamav
adduser clamav amavis

To allow Amavis search through different files and formats, we install some extra tools. These are optionnal, but they don't cost much space or CPU:

apt install lrzip cabextract unrar-free arj p7zip-full lzop rpm2cpio liblz4-tool nomarch

DKIM

If you don't want to use DKIM, you can almost skip this part. You probably shouldn't though...

To install:

apt install opendkim opendkim-tools

Configure:

cp /usr/local/mailboy/install/opendkim.conf /etc/opendkim.conf

Create key directory:

mkdir /etc/opendkim
chown root:opendkim /etc/opendkim
chmod 750 /etc/opendkim

For each domain name you want to sign with DKIM, do the following steps:

Note: If you do not want to setup OpenDKIM for your domains, at least create the files (even empty) for OpenDKIM to be able to start.

mkdir /etc/opendkim
touch /etc/opendkim/{TrustedHosts,KeyTable,SigningTable}

Postfix

Finally, let's install Postfix. Notice the "DEBIAN_PRIORITY=critical", it's just so we can avoid Debconf for this step, that's right, we'll do it LIVE !!

DEBIAN_PRIORITY=critical apt-get install -y postfix-mysql postfix postfix-policyd-spf-python

We'll start by generating a Diffie-Hellman file.. As it will warn, "This is going to take a long time", it took about 1 whole minute here.

cd /etc/postfix/
openssl dhparam -out dhparams.pem 4096
chmod 600 dhparams.pem

I made a most basic script to ease configuration of Postfix: /usr/local/mailboy/install/configure_postfix.sh. For this script to run, you must have filled out /usr/local/mailboy/config/db_config.sh properly and run it from the install directory:

cd /usr/local/mailboy/install/
./configure_postfix.sh

For master.cf the easiest will be to make a backup and overwrite the config file with one provided (if you prefer, you can compare and edit manually, ideal for learning):

mv /etc/postfix/master.cf /etc/postfix/master.cf.ORIG
cp /usr/local/mailboy/install/postfix/master.cf /etc/postfix/master.cf
cp /usr/local/mailboy/install/postfix/submission_header_checks /etc/postfix/submission_header_checks

Setting up a certificate - for Postfix AND Dovecot

Coverage of certificates in this document is a bit light. You may want to use a certificate that is known and trusted by your users' systems, for example Let's Encrypt. That is a bit beyond the scope of this Howto, that said the idea would be to get a certificate for your mail domain and all the other domains and subdomains you may need. You can then use the same certificate for Postfix, Dovecot and everything else here.

For Dovecot, you can edit /etc/dovecot/conf.d/10-ssl.conf and use your cert files, fullchain.pem and privkey.pem like this:

ssl_cert = </path/to/certificates/DOMAIN.TLD/fullchain.pem
ssl_key = </path/to/certificates/DOMAIN.TLD/privkey.pem

For Postfix, edit /etc/postfix/main.cf and change the certificates at:

smtpd_tls_cert_file=/path/to/certificates/DOMAIN.TLD/fullchain.pem
smtpd_tls_key_file=/path/to/certificates/DOMAIN.TLD/privkey.pem

If you want to use a self signed certificate (or maybe just use this for setup/testing), you may try the following (and then do as the 2 previous steps to configure Postfix and Dovecot):

mkdir -p /etc/mailboy/certs/
openssl req -new -x509 -days 730 -nodes -out /etc/mailboy/certs/mailboy.cert.pem -keyout /etc/mailboy/certs/mailboy.key.pem
chmod o= /etc/mailboy/certs/mailboy.key.pem

Email is Ready

Just to be sure, lets restart all mail services (and hopefully there will be no errors):

service dovecot restart
service amavis restart
service clamav-daemon restart
service clamav-freshclam restart
service spamassassin restart
service opendkim restart
service postfix restart

Now you should be able to send and receive emails, you will need to use an email client. You can use IMAP/S, POP3/S, SMTP/S (25, 465, 587).

I like to also install a web base email client such as Roundcube, however that's out of scope for now. It's not complicated and perhaps I can add that later if there's demand.

The Web Server

You will need a web server to access Mailboy's web interface. The installation of a web server is a bit out of scope for this howto. However, here is the a config you can use to access Mailboy's web interface (to use in a Vhost file for example):

<Directory /usr/local/mailboy/>
	Options Indexes FollowSymLinks
	AllowOverride None
	Require all granted
</Directory>
Alias   /mailboy    /usr/local/mailboy

XMPP Server

Ejabberd allows users to write their own authentification scripts, which is great, I wrote one using PHP (simply because it's the easiest language for me). So now you can have Ejabberd authenticate users against Mailboy's database and hence it makes managing users easier. Note that I've just started working on this, for now domains must be added in Ejabberd's config file.

Installing Ejabberd is of course easy on Debian (and many other GNU distributions with modern package managers), configuration will be easy as well. Like all the bits here (Postfix, Dovecot, etc), Ejabberd can be installed on a different server, if so, you will need to install php5-cli and php5-mysql to use Mailboy's authentification script, you can alterntatively write your own that will authenticate against Mailboy's DB.

apt install ejabberd

Once installed, edit /etc/ejabberd/ejabberd.yml, edit as follows (note, the config file is as sensitive as a cornered Donald Trump, do not use TABs, only use spaces):

hosts
  - "example.org"

Mailboy is designed to be multi-domain and so is Ejabber, you may add further domains by adding a new line for each new domain.

hosts
  - "example.org"
  - "otherdomain.eu"

Further down, search for "Authentication", comment out internal auth and add the parameter for external auth, as follows: 

## auth_method: internal

## auth_method: external
## extauth_program: "/path/to/authentication/script"
auth_method: external
extauth_program: "/usr/local/mailboy/scripts/mailboy_ejabberd_ext_auth.php"

Restart Ejabberd and voilà.

/etc/init.d/ejabberd restart

For XMPP services to be easy to reach, you should probably configre some DNS entries for the domain(s) that will use this. If you use Bind, the following should work:

xmpp    3600    IN  A   YOUR.XMPP.SERVER.IP

; protocol and such         PRIORITY    WEIGHT  PORT    xmpp server
_xmpp-client._tcp   IN  SRV 10          0       5222    xmpp
_xmpp-server._tcp   IN  SRV 10          0       5269    xmpp
_jabber._tcp        IN  SRV 10          0       5269    xmpp

Mailboy is licensed under GPLv3 - The content of this website is licensed under CC-BY-NC