PostfixAdmin for IPSMail Bullseye

gistfile1.md

Forenote

this guide is written to install PostfixAdmin with ISPMail Bullseye

All references to example.org should be replaced with your actual domain

Install Dependencies

1. As root or using sudo, apt install php7.4-curl php7.4-mysqli php7.4-sqlite3 php7.4-xml php7.4-mbstring php7.4-imap

Download PostfixAdmin

1. install git on your server - in a shell as root or using sudo apt install git
2. cd /srv
3. git clone https://github.com/postfixadmin/postfixadmin.git
4. cd postfixadmin
5. git checkout postfixadmin-3.3.10 (or whatever the current release is or use master - skipping this step is same as git check master too)
6. if using master, then running as a non-root (e.g., also don't use sudo) user /bin/bash install.sh (See note below)
7. Create a symlink in your /var/www/webmail.example.org: ln -s /srv/postfixadmin/public /var/www/webmail.example.org/postfixadmin

Note - not sure why it cautions about not running as root, i couldn't make it work any other way. Moreover, no matter which release is used, i found that i had to run the install.sh script in order to install the missing dependencies or whatever - otherwise there are issues connecting to the database. The install.sh script is calling composer to install a number of php related packages. It spits out these messages:

Package phpunit/php-token-stream is abandoned, you should avoid using it. No replacement was suggested.
Package webmozart/path-util is abandoned, you should avoid using it. Use symfony/filesystem instead.

I ignored the first because there was no suggested replacement package, but i installed the 2nd by entering the following at a shell prompt as root (still in the /srv/postfixadmin directory):

php composer.phar require symfony/filesystem and it installed about 80 packages

After that additional step postfixadmin works.

Create the Mailserver Database and Users

1. Note that you can follow some of the setup in the Bullseye prepare-database pageto set up the database. In case you're also reading the INSTALL.TXT file on the PostfixAdmin github site it has similar setup instructions - just note that the usernames and database names are different, and the SQL is slightly different but achieves the same thing.
2. You may skip the Adminer setup - you shouldn't need this if using PostfixAdmin, but may wish to install if you want a GUI into the database for anything.
3. Skip creating the Database Tables - PostfixAdmin will do this

So net of above is you need to:

1. at the shell generate 2 passwords, pwgen -s1 30 2 and save them somewhere
2. from the shell enter mysql, mysql
3. in the mysql shell, enter create database mailserver;
4. in the mysql shell, enter grant all on mailserver.* to 'mailadmin'@'localhost' identified by 'your-first-generated-password';
5. still in mysql shell, enter grant select on mailserver.* to 'mailserver'@'127.0.0.1' identified by 'your-second-generated-password';
6. ctrl-d to exit mysql

Configure PostfixAdmin

Before moving on with the ISPMail Bullseye guide, we need to configure PostfixAdmin and get it up and running. Below is essentially steps 4 & 5 from the PostfixAdmin instructions, but I've added a few more specifics in config.local.php that are particular to the Bullseye ISPMail guide. These configuration options are extracted from config.inc.php, which has the full set of options with more explanation.

1. In a shell on your Bullseye server navigate to PostfixAdmin:

cd /srv/`
chown -R www-data:www-data postfixadmin
cd postfixadmin

2. create a file named config.local.php in current directory - nano config.local.php with following content:

<?php
$CONF['configured'] = true;

// Postfix Admin Path
// Set the location of your Postfix Admin installation here.
// YOU MUST ENTER THE COMPLETE URL e.g. http://domain.tld/postfixadmin
$CONF['postfix_admin_url'] = 'https://webmail.example.org';
 
// Database connection details.
$CONF['database_type'] = 'mysqli';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'mailadmin';
$CONF['database_password'] = 'your-first-generated-password'; //from step above
$CONF['database_name'] = 'mailserver';

// system & account specific settings
$CONF['encrypt'] = 'dovecot:BLF-CRYPT';
$CONF['default_aliases'] = array (
'abuse' => 'abuse@example.org',
'hostmaster' => 'hostmaster@example.org',
'postmaster' => 'postmaster@example.org',
'webmaster' => 'webmaster@example.org');
$CONF['footer_text'] = 'Return to webmail.example.org';
$CONF['footer_link'] = 'https://webmail.example.org';
// refer to instructions in /srv/postfixadmin/config.inc.php to set Mailbox paths -
// $CONF['domain_path'] & $CONF['domain_in_mailbox'] - i used NO & YES, respectively.
// (which results in mailbox paths like: /var/vmail/domain/username/Maildir/... ie, username sans the @domainname)
$CONF['domain_path'] = 'NO';
$CONF['domain_in_mailbox'] = 'YES';
$CONF['create_mailbox_subdirs_prefix']=''; //(''for Dovecot)

// If using ISPMail quotas:
$CONF['quota'] = 'YES'; //to enforce user quotas
$CONF['quota_multiplier'] = '1024000'; // You can either use '1024000' or '1048576'
$CONF['new_quota_table'] = 'YES'; //for postfix >= 1.2

// these may not have any effect on ISPMail quota architecture,
$CONF['domain_quota'] = 'YES'; //this may not impact ISPMail Quota
$CONF['domain_quota_default'] = '2048'; //this may not impact ISPMail Quota
$CONF['maxquota'] = '100'; //this is the maxquota per user, but doesn't seem to have any effect or may be a file limit
//of some kind.  When the domain is defined in PostfixAdmin, or editing it afterwards in the GUI, define the MB quota there

// quota display in PostfixAdmin GUI
$CONF['used_quotas'] = 'YES'; //optional - it shows quota used in PostfixAdmin GUI
// these may not have any effect - ISPMail guide defines limits in the /etc/dovecot/conf.d/90-quota.conf file
// fill state threshold (in per cent) for medium level (displayed as orange)
$CONF['quota_level_med_pct'] = 80;
// fill state threshold (in per cent) for high level (displayed as red)
$CONF['quota_level_high_pct'] = 95;
?>

This directory with corresponding settings should exist, otherwise run these in a shell:

3. mkdir -p /srv/postfixadmin/templates_c
4. chown -R www-data /srv/postfixadmin/templates_c
5. chmod 750 /srv/postfixadmin/templates_c
6. modify dovecot settings to match PostfixAdmin encryption scheme - edit /etc/dovecot/dovecot-sql.conf.ext and add this line: default_pass_scheme = BLF-CRYPT. I put it near the Default password scheme section which is all commented out.

Setup PostfixAdmin via the web

1. Open a web browser and navigate to https://webmail.example.org/postfixadmin/setup.php
2. you should be prompted to enter a setup password and you may have some warnings about the environment, however if there are also errors about being unable to connect to the database, then something didn't get set up properly.
3. Enter a setup password of your choice. (remember it you'll use it again in step 7.)
4. You'll be presented with a line like this:
5. $CONF['setup_password'] = '$a-really-long-string-of-ascii-characters';
6. Copy the whole line as it, leave the web page open, & go back to a shell in your Bullseye server and edit /srv/postfixadmin/config.local.php and add it to the end of the file (or wherever). Save the file.
7. Now go back to the browser and refresh the page. You'll be presented with some system checks and you will now enter the Setup Admin account information beginnning with the same setup password you typed above. This may be slightly confusing because you'll be tempted to use admin@example.org - and this is fine to do so. Just realize this is only the admin account for logging into PostfixAdmin to do administrative-like things, e.g., add domains, user mailboxes etc. But once logged in, you may also wish to set up an email account for your domain and use admin@example.org (which is also fine) as a catch all for webmaster, abuse, etc, so just realize these are two distinct accounts and passwords - one for administering PostfixAdmin and the other as a domain user in your webmail.example.org domain. Phew!

Use PostfixAdmin

1. If you made it here, PostfixAdmin should be up and working and now you can add your mail domain, webmail.example.org and then add mailboxes from the the Virtual List dropdown.
2. Add forwards as needed.
3. These additions/changes will be entered into the Mariadb / MySQL database you created in the earlier part of the guide.

Continuing with the ISPMail Guide there are some additional changes that need to be made in the SQL in the following sections of the guide

1. In the making postfix get its information from the mysql database section make the following changes to the SQL queries on this page:

    1. virtual_mailbox_domains sql query: query = SELECT 1 FROM domain WHERE domain='%s'
    2. virtual_mailbox_maps sql query: query = SELECT 1 FROM mailbox WHERE username='%s'
    3. virtual_alias_maps query: query = SELECT goto FROM alias WHERE address='%s'
    4. email2email sql query: query = SELECT username FROM mailbox WHERE username='%s'

2. On the setting up dovecot page, make the following changes to the SQL queries on this page:

    1. user_query = SELECT username as user, \
       concat('*:bytes=', quota) AS quota_rule, \
       '/var/vmail/%d/%n' AS home, \
       5000 AS uid, 5000 AS gid \
       FROM mailbox WHERE username='%u'
    2. password_query = SELECT password FROM mailbox WHERE username='%u'
    3. iterate_query = SELECT username AS user FROM mailbox

3. On the roundcube page, change the SQL password_query to this:

    $config['password_query'] = "UPDATE mailbox SET password=%P WHERE username=%u";