Administration Web Interface

ViMbAdmin Logo

The ViMbAdmin project (vim-be-admin) provides a web based virtual mailbox administration system allowing mail administrators to manage domains, mailboxes and aliases.

Software Installation

ViMbAdmin is not in the Ubuntu software package repository.

ViMbAdmin is written in PHP and can be installed using the composer dependencies managegement system for PHP. But for this to work we need to install composer first.

$ curl -sS | www-data php
$ sudo mv composer.phar /usr/local/bin/composer

As per installation instructions in their Wiki we define and create a installation directory:

$ export INSTALL_PATH=/var/www/vimbadmin
$ mkdir -p $INSTALL_PATH
$ sudo chown www-data:www-data $INSTALL_PATH

Done that ViMbAdmin can be installed:

$ composer create-project opensolutions/vimbadmin $INSTALL_PATH -s dev

Answer “No” when asked: “Do you want to remove the existing VCS (.git, .svn..) history?”


Next we copy the sample configuration file to create a configuration for our server. Assuming you are still in the $INSTALL_PATH directory:

$ cp application/configs/application.ini.dist application/configs/application.ini

Open the file application/configs/application.ini.

Installation Keys and Salts

; Installation Keys and Salts
; During installation, you will be prompted to enter strings here. This
; is to verify that you are in fact the person authorised to complete the
; installation as well as provide security for cookies and passwords.

securitysalt                       = "********"
resources.auth.oss.rememberme.salt = "********"
defaults.mailbox.password_salt     = "********"

Database Connection

Find the lines with database connection settings and set the password:

;; You database and caching connection.

resources.doctrine2.connection.options.driver   = 'pdo_mysql'
resources.doctrine2.connection.options.dbname   = 'vimbadmin'
resources.doctrine2.connection.options.user     = 'vimbadmin'
resources.doctrine2.connection.options.password = '********'     = 'localhost'
resources.doctrine2.connection.options.charset  = 'utf8'

Virtual Mailbox Storage

Set the system user and groupd ID and the filesystem location for virtual mailboxes to match our settings in the section “Mailbox Location” of the MAS - Mail Access Server:

; Default values for creating mailboxes

; This sets the uid and gid columns in the mailbox table to the below values
defaults.mailbox.uid = vmail
defaults.mailbox.gid = vmail

; Set the homedir and maildir values in the mailbox table where the
; following substitutions apply:
;     %d -> domain part of email address
;     %u -> user part of email address
;     $m -> full email address

defaults.mailbox.maildir = "maildir:/var/vmail/%d/%u/Maildir:LAYOUT=fs"
defaults.mailbox.homedir = "/var/vmail/%d/%u"

Password Scheme

As the login procedure is handled by Dovecot, one of Dovecots password schemes can be selected. This should match our configuration of MAS - Mail Access Server in the section “Password Scheme”.

; The password hashing function to use. Set to one of:
;   "plain"       - password stored as clear text
;   "md5"         - password hashed using MD5 without salt (PHP md5())
;   "md5.salted"  - password hashed using MD5 with salt (see below)
;   "sha1"        - password hashed using sha1 without salt
;   "sha1.salted" - password hashed using sha1 with salt defined below
;   "crypt:XXX"   - call the PHP crypt function (with random salt) where XXX is one of: md5, blowfish, sha256, sha512
;   "dovecot:XXX" - call the Dovecot password generator (see next option below) and use the
;                      scheme specified by XXX. To see available schemes, use 'dovecotpw -l'
;                      or 'doveadm pw -l'

;defaults.mailbox.password_scheme = "dovecot:SHA512-CRYPT"
defaults.mailbox.password_scheme = "dovecot:ARGON2ID"

Mailbox Archives Storage

vimbadmin allows to archive entire mailboxes. We need to adjust the path, where those archives are stored:

; See:

server_id = 1

;;Archive options
binary.path.chown_R   = "/bin/chown -R"
binary.path.tar_cf    = "/bin/tar -cf"
binary.path.tar_xf    = "/bin/tar -xf"
binary.path.bzip2_q   = "/bin/bzip2 -q"
binary.path.bunzip2_q = "/bin/bunzip2 -q"
binary.path.rm_rf     = "/bin/rm -rf"

archive.path = "/var/vmail/"


Mail-Server Defaults

Default configuration settings for new accounts include the server settings for accessing the mailboxand submitting mail messages:

The SMTP server needs to be changed to reflect a Submission server instead of the legacy SMTP server.

Also POP3, IMAP and Webmail access needs adjustments to server names and encryption protocols used.

;; Settings email default values.
;; Substituions are as follows:
;;     %d -> domain part of email address
;;     %u -> user part of email address
;;     $m -> full email address
;; See (and skin) the following file to see how the below are used:
;;     views/mailbox/email/settings.phtml

server.smtp.enabled = 1    = "mail.%d"
server.smtp.user    = "%m"
server.smtp.port    = "785"
server.smtp.crypt   = "TLS"

server.pop3.enabled = 1  = "mail.%d"
server.pop3.user  = "%m"
server.pop3.port  = "110"
server.pop3.crypt = "TLS"

server.imap.enabled = 1  = "mail.%d"
server.imap.user  = "%m"
server.imap.port  = "143"
server.imap.crypt = "TLS"

server.webmail.enabled = 1  = "https://mail.%d"
server.webmail.user  = "%m"



At least the domain names have to be adjusted to your own one here:

;; Identity

identity.orgname  = "Example Limited"  = "Example Support Team" = ""  = "ViMbAdmin Autobot" = ""   = "ViMbAdmin Autobot"  = ""

identity.sitename = "ViMbAdmin"
identity.siteurl = "https://server.lan/vimbadmin/"

;; All mail and correspondence will come from the following;; = "ViMbAdmin Administrator" = ""



Next we create the MySQL database for ViMbAdmin:

$ mysqladmin -u root -p create vimbadmin

And set the privileges, after creating a secure password:

$ mysql -u root -p vimbadmin
GRANT ALL ON `vimbadmin`.* TO `vimbadmin`@`localhost` IDENTIFIED BY '********';

We wont use the .htaccess file with NGinx, but the script doesn’t run without it:

$ cp $INSTALL_PATH/public/.htaccess.dist $INSTALL_PATH/public/.htaccess

Now the tables can be created.

$ ./bin/doctrine2-cli.php orm:schema-tool:create
ATTENTION: This operation should not be executed in a production environment.

Creating database schema...
Database schema created successfully!

Nginx Configuration

Create a new web-application configuration file /etc/nginx/webapps/vimbadmin.conf:

# Web Application Configuration for Virtual Mailbox Administration 
# ViMbAdmin 3.0.x

# Directory where ViMbAdmin is installed
set $vimbadmin /var/www/vimbadmin

location /mail {
    alias $vimbadmin/public;
	index index.php index.html index.htm;

    location ~ ^/mail/(.*\.(js|css|gif|jpg|png|ico))$ {
        alias $vimbadmin/public/$1;

    rewrite ^/mail(.*)$ /mail/index.php last;

    # Pass PHP scripts to FastCGI server
    location ~ \.php$ {

        #try_files $uri =404;

        # NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
        fastcgi_split_path_info ^/mail/(.+\.php)(/.+)$;

        include fastcgi_params;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_param SCRIPT_FILENAME $request_filename;
        fastcgi_param APPLICATION_ENV production;
        fastcgi_index index.php;
        fastcgi_pass php-backend;
        fastcgi_intercept_errors on;

    # Temporary Debug Loggin, please remove when done
    #include /etc/nginx/debug.conf;

Include the new web-application in your server configuration:

# ViMbAdmin - Virtual Mailbox Administration
include             webapps/vimbadmin.conf;

Restart the Nginx webserver:

$ sudo service nginx restart

ViMbAdmin Upgrades

$ export INSTALL_PATH=/var/www/vimbadmin
$ export NEW_VERSION=3.0.12
$ git fetch
$ git checkout $NEW_VERSION
$ sudo composer self-update
$ sudo composer update
$ sudo chown -R www-data:www-data $INSTALL_PATH
$ bin/doctrine2-cli.php orm:validate-schema
$ bin/doctrine2-cli.php orm:schema-tool:update --force