yajrendrag/README.md

## README.md

      
    Raw
  

              README.md
            
          
    Background

I first came across PostfixAdmin upon implementing my first mailserver using this guide - https://www.exratione.com/2016/05/a-mailserver-on-ubuntu-16-04-postfix-dovecot-mysql/ and it's successor on Ubuntu 18.04.  With the release of Ubuntu 20.04.1, i began looking around for an update and came upon the ISPMail guide as it had a few things I had wanted to try out - namely, rspamd, and encryption.  But i wanted to be able to continue to use PostfixAdmin as i wanted to preserve the GUI administration of the database.  So i began to implement the guide and figure out how i could integrate PostfixAdmin into it.  This is the result.
Assumptions


PostfixAdmin sets up the database schema (ie, no need to manually create the database tables with SQL)
Presumption in guide below is that the Apache document root is /var/www/html
For support of encryption, part 2 of guide below shows how to modify PostfixAdmin (& roundcube) to generate / modify user encryption keys, so once a user's account is setup, only the user can change their password via PostfixAdmin (or Roundcube) - an admin should not change a user's password any longer via the PostfixAdmin GUI or the emails will no longer be decrypted.

Basic PostfixAdmin Setup

Note i did this in Ubuntu vs Debian, & most packages & paths are the same - but, let me know if you find something that seems incorrect.  You should substitute webmail.yourdomain (i.e., whatever your host's fqdn is) for all occurrences of webmail.example.org &/or substitute just yourdomain for example.org in a few instances.

Follow the Buster ISPMail guide through https://workaround.org/ispmail/buster/creating-a-tls-encryption-key-and-certificate/, but skip installation of adminer
Install postfixadmin 3.2.4 following instructions from steps 1-5 of https://github.com/postfixadmin/postfixadmin/blob/master/INSTALL.TXT as modified below:


in step 1 the mv command should be mv postfixadmin-postfixadmin-3.2.4 postfixadmin
in step 2, if following the paths in ISPMail guide, the symlink should be ln -s /srv/postfixadmin/public /var/www/html/postfixadmin
in step 3, rather than follow the database setup from the postfixadmin guide, simply follow https://workaround.org/ispmail/buster/prepare-the-database/ but skip the adminer setup, and stop before creating the database tables - postfixadmin will setup the tables.
You'll need some additional configuration in /srv/postfixadmin/config.local.php to add to what is shown in step 4:

$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)
I did not implement quotas, but if you wish to implement quotas, then per the instructions in /srv/postfixadmin/config.inc.php, you'll also need the following in /srv/postfixadmin/config.local.php & note that when you make an entry in postfixadmin for quota when setting up a new user, it's in MB:
$CONF['quota'] = 'YES';
$CONF['quota_multiplier'] = '1024000'; // You can either use '1024000' or '1048576'
$CONF['new_quota_table'] = 'YES'; //for postfix >= 1.2
// Optional:
// Show used quotas from Dovecot dictionary backend in virtual
// mailbox listing.
// See: DOCUMENTATION/DOVECOT.txt
//      http://wiki.dovecot.org/Quota/Dict
//
//$CONF['used_quotas'] = 'YES';

in step 5 follow the instructions after browsing to https://webmail.example.org/postfixadmin/setup.php - you'll need to generate the superadmin password and hash and then re-edit /srv/postfixadmin/config.local.php and enter : $CONF['setup_password'] = 'your hashed password goes here'; - this can be at end of the file.  (Note that this is not the email password for admin@example.org - you'll have to create that mailbox in addition to setting up the superadmin account).

You can now use postfixadmin - vist https://webmail.example.org/postfixadmin, login with the superadmin account that you generated, and create domains, mailboxes, & aliases.  That will populate the mysql database you created above; you can use it to set up the example data in https://workaround.org/ispmail/buster/prepare-the-database/.

Continue with the next section of the ISPMail guide - https://workaround.org/ispmail/buster/making-postfix-get-its-information-from-the-mysql-database/
here you'll need to make a few modifications to the sql queries shown 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'

Continuing with https://workaround.org/ispmail/buster/setting-up-dovecot/ you'll need to modify the sql queries in /etc/dovecot/dovecot-sql.conf.ext to these:

    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

For roundcube, referencing https://workaround.org/ispmail/buster/webmail-using-roundcube/ you'll need to modify the password query to:

$config['password_query'] = "UPDATE mailbox SET password=%D WHERE username=%u";
That should be everything needed unless you wish to implement the optional encryption option.  Users can browse to https://webmail.example.org/postfixadmin/users/login.php and login to change their password.

Additional PostfixAdmin/Roundcube Setup to Support ISPMail Optional Encryption

(Note: after 1-11-2021, postfixadmin appears to support the mail-crypt plug in, so steps 1-5 & 8 below may not be required any longer & the others only if you wish to use the command line functions &/or roundcube functions)

If continuing to setup encryption (https://workaround.org/ispmail/buster/optional-server-based-mailbox-encryption/), you'll want to continue with these additional modifications.  These next modifications will update the mailserver database to accommodate the additional crypt field and will update postfixadmin to support that field. Additionally, we'll make postfixadmin automatically issue the doveadm commands needed to generate &/or update the user keys.

Edit /srv/postfixadmin/config.local.php and add this to the end of the file:

function x_struct_mailbox_modify($struct) {
$struct['x_crypt'] = pacol(1, 1, 1, 'int', 'x_Crypt_Label', 'x_Crypt_Desc', 2, array(), 0, 0, "", "", "");
return $struct;
}
$CONF['mailbox_struct_hook'] = 'x_struct_mailbox_modify';
         
$CONF['mailbox_postdeletion_script'] = 'sudo -u root /usr/local/bin/postfixadmin-mailbox-postdeletion.sh';
This will enable postfixadmin to recognize and populate the crypt field in the mailserver database.  New
mailboxes created will be created with the crypt field set to 2 (if you wish to default to 0, then change 2 above to
0).  The last line is used to delete the Maildir folder on the server when a user is deleted via the PostfixAdmin GUI.

Edit /srv/postfixadmin/languages/en.lang and add these 2 lines just before the line $PALANG['please_keep_this_as_last_entry'] = ''; # needed for language-check.sh:

$PALANG['x_Crypt_Label'] = 'CRYPT';
$PALANG['x_Crypt_Desc'] = '2=Encrypt, 0=Read-Only';
(These provide descriptive text for PostfixAdmin's Add Mailbox GUI form)

Edit the mailbox table to add the crypt field - starting from the shell:

  $ mysql
  MariaDB [(none)]> use mailserver;
  MariaDB [mailserver]> alter table mailbox add x_crypt int(11) default 2 after quota;
  ctl-d

Edit /etc/dovecot/dovecot-sql.conf.ext and change the password query to:

password_query = SELECT password, x_crypt as userdb_mail_crypt_save_version, ‘%w’ AS userdb_mail_crypt_private_password FROM mailbox WHERE username=’%u’

Edit /srv/postfixadmin/public/users/password.php and insert these lines in the if ($error == 0) block just before the exit(0); line:

/* added to update crypto password when user changes password */
system ('sudo /usr/bin/doveadm mailbox cryptokey password -u '.escapeshellarg($username).' -n '.escapeshellarg($fPassword).' -o '.escapeshellarg($fPassword_current));

If using Roundcube, edit /usr/share/roundcube/plugins/password/password.php and insert these lines in the private function _save just after the case PASSWORD_SUCCESS: line:

/* added to update crypto password when user changes password */
system ('sudo /usr/bin/doveadm mailbox cryptokey password -u '.escapeshellarg(self::username()).' -n '.escapeshellarg($passwd).' -o '.escapeshellarg($curpass));


If using Roundcube, edit /etc/roundcube/plugins/password/config.inc.php and add $config['password_confirm_current'] = true; to the configuration.  Both the current and new passwords are needed when updating the cryptokey password.


Edit /srv/postfixadmin/model/MailboxHandler.php and insert these lines just before the if (empty($cmd)) in the protected function mailbox_post_script():


/* Added to generate encryption key for newly created mailboxes  */
if ($this->new && !empty($this->values['password']) && !empty($this->id)) {
  system ('sudo /usr/bin/doveadm -o plugin/mail_crypt_private_password='.escapeshellarg($this->values['password']).' mailbox cryptokey generate -u '.escapeshellarg($this->id).' -U');
}

Edit or create /etc/sudoers.d/local and add these lines:

www-data        ALL=(root) NOPASSWD: /usr/local/bin/postfixadmin-mailbox-postdeletion.sh
www-data        ALL=(root)      NOPASSWD:       /usr/bin/doveadm
www-data        ALL=(root)      NOPASSWD:       /usr/bin/rm
this will allow the apache2 user (www-data) to issue the specific commands above as root without requiring a password
Note that these last 5 steps enable automatic generation of the encryption key password or updating of same when a user changes their password using postfixadmin or rouudcube.

Create a symlink to the postfixadmin-cli command:

ln -s /srv/postfixadmin/scripts/postfixadmin-cli /usr/local/bin/postfixadmin-cli

Create /usr/local/bin/addmb with this content:

#!/bin/sh
#expects 4 arguments - in this order: email-address, password, name, quota (in  MB - enter 0 for unlimited)
#quote the password argument on the command line with single quotes to protect special characters from the shell, e.g., 'password'

/usr/local/bin/postfixadmin-cli mailbox add "$1" --password "$2" --password2 "$2" --name "$3" --active 1 --quota "$4"
/usr/bin/doveadm -o plugin/mail_crypt_private_password="$2" mailbox cryptokey generate -u "$1" -U

make addmb executable:

chmod +x /usr/local/bin/addmb

create /usr/local/bin/postfixadmin-mailbox-postdeletion.sh with this content:

#!/bin/sh

# userid in form of user@domain is argument 1
# domain is argument 2
if [ "$#" -eq 2 ]; then
  user=$(/usr/bin/echo "$1" | awk -F"@" '{ print $1 }')
  if [ -d "/var/vmail/$2/$user" ]; then
    sudo /usr/bin/rm  -rf /var/vmail/"$2"/"$user"/
  fi
else
  # you need domain and user@domain arguments to use this script
  exit 1
fi
exit 0
And make it executable with chmod +x /usr/local/bin/postfixadmin-mailbox-postdeletion.sh
(Note that you'll need to modify this script somewhat if you changed the $CONF['domain_path'] & CONF['domain_in_mailbox'] values in /srv/postfixadmin/config.local.php from that shown at the start of this guide.  Be careful with this script and ensure you pass it the correct values and / or modify the checks on the arguments passed - i wiped out my complete vmail directory before adding checks on $#.  Alternatively don't implement this script and leave out the last line in step 1 in this section and do any deletions manually.)

reboot or minimally restart postfix and dovecot.

After these steps, you can create new mailboxes with an associated encryption key in one of two ways: (1) via the shell by logging in to server and issuing (as root or prefix with sudo):
addmb new-email-user@example.org 'passw0rd!' "first_name last_name" numerical-quota-value
or (2) by browsing to https://webmail.example.org/postfixadmin, logging in as the admin user you created above, and creating a new mailbox in your domain.
Either of these will create a new mailbox for the user with (referring to shell instructions) email address of new-email-user@example.org with password = passw0rd! and name of first_name last_name as well as generating the user key.  The database will populate the new mailbox with the crypt field (x_crypt) = 2.
Users can then change their password with postfixadmin via GUI by visiting https://webmail.example.org/postfixadmin/users/login.php, logging in with their current password and clicking on change password.  When they do, their user key will be updated automatically.
One CAVEAT - I don't use roundcube.  If you use roundcube to change your password, you'll need to manually update encryption keys.  I'll add a to-do item to try and figure out a way to execute a shell script that would allow automating encryption keys on a password change.  The best way for users to change their passwords is to use postfixadmin as the enryption keys are updated automatically per above.
Users can also change their password using the roundcube password plugin based on the edit in steps 6 & 7 above.
Recommend testing before deploying to production - especially if you're adding encryption to a working server.  Set the x_crypt value to 0 for all users but 1 test user for whom you can set x_crypt to 2.  That way, if you run into issues, you can simply delete the test user.
TO DO:


Error checking on the lines inserted into few php files modified (will need help from someone more experienced in php)
Optionally add a new post-domain-deletion script similar to /usr/local/bin/postfixadmin-mailbox-postdeletion.sh
Automate encryption key update if roundcube is used to change user password. Done.