Baruwa Documentation Release 1.1.2
Andrew Colin Kissa
June 27, 2016
Contents
1 Introduction 3
2 Features 5
3 Screenshots 7
4 Requirements 9 4.1 Baruwa requirements...... 9 4.2 MailScanner requirements...... 9
5 Source Installation 11 5.1 Install Baruwa...... 11 5.2 Configure RabbitMQ...... 12 5.3 Configure Baruwa...... 12 5.4 Configure MailScanner...... 14 5.5 Testing...... 15 5.6 Need help...... 16 5.7 Distribution / OS installation...... 16
6 Baruwa on RHEL/SL/Centos 17 6.1 Install EPEL...... 17 6.2 Baruwa installation...... 17 6.3 Configure RabbitMQ...... 17 6.4 Configure Baruwa...... 18 6.5 Configure MailScanner...... 19 6.6 Testing...... 20 6.7 Need help...... 20
7 Baruwa on Fedora 21 7.1 Baruwa Installation...... 21 7.2 Configure RabbitMQ...... 21 7.3 Configure Baruwa...... 22 7.4 Configure MailScanner...... 23 7.5 Testing...... 24 7.6 Need help...... 24
8 Baruwa on Ubuntu/Debian 25 8.1 Install & Configure RabbitMQ...... 25 8.2 Configure RabbitMQ...... 25 8.3 Baruwa Apt install...... 25 8.4 Automated configuration...... 26 8.5 Configure MailScanner...... 26 8.6 Configure Baruwa...... 27
i 8.7 Testing...... 27 8.8 Need help...... 28
9 External authentication 29 9.1 SMTP, POP3, IMAP and RADIUS/RSA SECURID...... 29 9.2 ACTIVE DIRECTORY...... 29 9.3 LDAP...... 30
10 MTA Integration 31 10.1 Postfix...... 31 10.2 Exim...... 32
11 Clustered setups 33
12 Other batteries included 35 12.1 Command options and help...... 35 12.2 Quarantine management...... 35 12.3 Quarantine reports...... 35 12.4 Database maintenance...... 35 12.5 Spamassassin rule description updates...... 35 12.6 PDF reports...... 36 12.7 Mailq Stats updates...... 36 12.8 Email Signatures configuration...... 36
13 Getting Help 37 13.1 How do I do X? Why doesn’t Y work? Where can I go to get help?...... 37 13.2 I think I’ve found a security problem! What should I do?...... 37 13.3 Can i get Commercial Support or pay for an installation...... 37
14 Contributing to Baruwa 39 14.1 Reporting bugs...... 39 14.2 Submitting patches...... 39 14.3 Documentation...... 39 14.4 Donations...... 39 14.5 Translation...... 40
15 Upgrading 41 15.1 1.1.2...... 41 15.2 1.1.1...... 41 15.3 1.1.0...... 42 15.4 1.0.2...... 42 15.5 1.0.1...... 42
16 Migrate from Mailwatch 43 16.1 User contributed tips...... 43
17 User Guide 45 17.1 Interface primer...... 45 17.2 FAQ’s...... 47
18 Older documentation 49
ii Baruwa Documentation, Release 1.1.2
Release 1.1.2 Build Date June 27, 2016 Baruwa (swahili for letter or mail) is a web 2.0 MailScanner front-end. It provides an easy to use interface for managing a MailScanner installation. It is used to perform operations such as releasing quarantined messages, bayesian learning, whitelisting and blacklisting addresses, monitoring the health of the services etc. Baruwa is implemented using web 2.0 features (AJAX) where deemed fit, graphing is also implemented on the client side using SVG, Silverlight or VML. Baruwa has full support for i18n, letting you support any language of your choosing. It includes reporting functionality with an easy to use query builder, results can be displayed as message lists or graphed as colorful and pretty interactive graphs. Custom MailScanner modules are provided to allow for logging of messages to the mysql database with SQLite as backup, managing whitelists and blacklists and managing per user spam check settings. Baruwa is open source software, written in Python/Perl using the Django Framework and MySQL or PostgreSQL for storage, it is released under the GPLv2 and is available for free download.
Contents 1 Baruwa Documentation, Release 1.1.2
2 Contents CHAPTER 1
Introduction
Baruwa (swahili for letter or mail) is a web 2.0 MailScanner front-end. It provides an easy to use interface for managing a MailScanner installation. It is used to perform operations such as releasing quarantined messages, bayesian learning, whitelisting and blacklisting addresses, monitoring the health of the services etc. Baruwa is implemented using web 2.0 features (AJAX) where deemed fit, graphing is also implemented on the client side using SVG, Silverlight or VML. Baruwa has full support for i18n, letting you support any language of your choosing. It includes reporting functionality with an easy to use query builder, results can be displayed as message lists or graphed as colorful and pretty interactive graphs. Custom MailScanner modules are provided to allow for logging of messages to the mysql database with SQLite as backup, managing whitelists and blacklists and managing per user spam check settings. Baruwa is open source software, written in Python/Perl using the Django Framework and MySQL or PostgreSQL for storage, it is released under the GPLv2 and is available for free download.
3 Baruwa Documentation, Release 1.1.2
4 Chapter 1. Introduction CHAPTER 2
Features
• AJAX support for most operations • Reporting with AJAX enabled query builder • I18n support, allows use of multiple languages • Signature management / Branding • Mail queue management and reporting • Interactive SVG graphs • Emailed PDF reports • Archiving of old message logs • SQLite backup prevents data loss when MySQL or PostgreSQL is down • MTA integration for relay domains and transports configuration • Multi user profiles (No restrictions on username format) • User profile aware white/blacklist management • Ip / network addresses supported in white/blacklist manager • Easy plug-in authentication to external authentication systems (POP3, IMAP, SMTP, Active Directory and RADIUS supported out of the box) • Tools for housekeeping tasks (quarantine management, rule updates, quarantine notifications, etc) • Easy clustering of multiple servers • Works both with and without Javascript enabled (graphs require Javascript)
5 Baruwa Documentation, Release 1.1.2
6 Chapter 2. Features CHAPTER 3
Screenshots
Screenshots are on our site.
7 Baruwa Documentation, Release 1.1.2
8 Chapter 3. Screenshots CHAPTER 4
Requirements
4.1 Baruwa requirements
• Python >= 2.4 • Django >= 1.2 • django-celery • django-south • MySQL-Python >= 1.2.1p2 or Psycopg • GeoIP-Python • iPy • Any Web server that can run Django (Apache/mod_wsgi recommended) • A supported Message broker (RabbitMQ recommended) • MySQL or PostgreSQL • Dojo toolkit >= 1.5.0 • Reportlab • Lxml • Anyjson • UUID (Only for python 2.4) • Sphinx (Optional - to build documentation) • Pyrad (Optional for RADIUS/RSA SECURID authentication) • Python ldap (optional for Active directory authentication)
4.2 MailScanner requirements
• MailScanner >= 4.80.10-1 • DBI • DBD-MySQL or DBD-Pg • DBD-SQLite
9 Baruwa Documentation, Release 1.1.2
10 Chapter 4. Requirements CHAPTER 5
Source Installation
Note: Packages are available for Debian/Ubuntu, RHEL/SL/Centos and Fedora if you are using one of those OS’s rather install using the packages.
If you do not want to install to your global python directories or are just testing it is advised that you use a virtualenv python install. Virtualenv allows you to run multiple python installs and is easily managed as you do not need to be a privileged user to install packages. For more info on virtualenv please refer to its documentation.
5.1 Install Baruwa
You can install Baruwa either via the Python Package Index (PyPI) or from source.
5.1.1 Install via the Python Package Index (PyPI)
To install using pip: # pip install baruwa < 2.0.0
To install using easy_install: # easy_install baruwa < 2.0.0
5.1.2 Downloading and installing from source
Download the latest version of Baruwa 1.0 from PyPI You can install it by doing the following,: # tar xvfz baruwa-
5.1.3 Using the development version
You can clone the repository by doing the following:
11 Baruwa Documentation, Release 1.1.2
# git clone git://github.com/akissa/baruwa.git # cd baruwa # python setup.py install
5.1.4 Install the Python GeoIP module
You need to install this manually as it does not build cleanly when installed automatically during Baruwa’s instal- lation: # wget http://geolite.maxmind.com/download/geoip/api/python/GeoIP-Python-1.2.4.tar.gz # tar xzvf GeoIP-Python-1.2.4.tar.gz # cd GeoIP-Python-1.2.4 # python setup.py install
Link the Baruwa settings file to /etc/baruwa: # mkdir /etc/baruwa # baruwa_path=$(python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()") # ln -s $baruwa_path/baruwa/settings.py /etc/baruwa/
5.2 Configure RabbitMQ
Create a user and virtual host for baruwa: # rabbitmqctl add_user baruwa your_password # rabbitmqctl add_vhost baruwa # rabbitmqctl set_permissions -p baruwa baruwa ".*" ".*" ".*"
Delete the guest user: # rabbitmqctl delete_user guest
See the RabbitMQ Admin Guide for more information.
Note: Please ensure that you control access to your RabbitMQ install as to prevent an unauthorized clients from accessing your broker.
5.3 Configure Baruwa
Create the database: # mysqladmin -u root -p create baruwa
Create a Mysql user for baruwa Run the command from the mysql prompt: mysql> GRANT ALL ON baruwa.* TO baruwa@localhost IDENTIFIED BY '
Note: You may want to secure your system by creating several users will limited rights as opposed to the above where the user has full access to the DB.
Configure the Baruwa settings
12 Chapter 5. Source Installation Baruwa Documentation, Release 1.1.2
Edit the Baruwa settings.py file: # vi /etc/baruwa/settings.py
Set the following options under the default DATABASE option: NAME='baruwa' USER='baruwa' PASSWORD='
Populate the database: # baruwa-admin syncdb --noinput # for name in $(echo "accounts messages lists reports status fixups config"); do baruwa-admin migrate $name; done
Create the admin user account: # baruwa-admin createsuperuser
Set the rabbitMQ settings: CELERY_CONCURRENCY= 20 BROKER_HOST="localhost" BROKER_PORT= 5672 BROKER_USER="baruwa" BROKER_PASSWORD="your_password" BROKER_VHOST="baruwa"
Edit the settings.py file and make configuration changes to suit your site.: # vi /etc/baruwa/settings.py
Warning: Make sure you change the SECRET_KEY, DO NOT USE THE DEFAULT, If you have a cluster the key should be the same on all the machines in the cluster.
Link to the dojo toolkit: # ln -s /path/to/dojo $baruwa_path/baruwa/static/js # ln -s /path/to/dojox $baruwa_path/baruwa/static/js # ln -s /path/to/dijit $baruwa_path/baruwa/static/js
Configure celeryd to run as a daemon You need to run celeryd as a daemon in order to process tasks such as Bayesian learning and message releases from the quarantine etc etc. Download the appropriate init script for your OS from the celery repository, then read the celery documentation on how to run celeryd as a daemon on your specific OS. Make sure you configure your system using the Django configuration examples. If you have any difficulties please refer to the Baruwa mailing list for assistance. Configure Email Signature management Baruwa now supports the management of email signatures / disclaimers from within the web interface. Signatures are configured on a domain and user level. Both HTML and text signatures are supported, HTML signatures support embedding of one graphical image, which can be uploaded via the HTML editor interface. The backend that handles the signatures needs to be initialized before you can begin to manage the signatures via the interface. To initialize the backend run:
5.3. Configure Baruwa 13 Baruwa Documentation, Release 1.1.2
# baruwa-admin initconfig
This will ask you for the hostname of the system you are setting up, and then initialize the system for you. The command does attempt to guess your hostname, so if its correct just press enter. You need to initialize each of your machines if you are running a clustered setup. If you are installing from source you need to create the directory structure to store you signature files: # install -p /etc/MailScanner/signatures/{users,domains}/{html,text,imgs} # chown celeryd.celeryd -R /etc/MailScanner/signatures/{users,domains}
5.3.1 Configure the Web server
Apache/mod_wsgi Make sure you have mod_wsgi installed and enabled. Use the sample configuration provided (extras/baruwa-mod_wsgi.conf) as a template. Copy to your apache con- figuration directory usually /etc/httpd/conf.d on Redhat and clones or /etc/apache2/conf.d/ on debian and clones. For others refer to your system docs for the location. Make sure that your apache is configured for name based virtual hosting such that you can run other sites on the same box if you wish to. Edit baruwa-mod_wsgi.conf and set ServerName to the hostname you will use to access baruwa
Note: If you installed using virtualenv, you need to customize and use virtual.wsgi instead of baruwa.wsgi in your mod_wsgi configuration.
Restart apache for the configuration to take effect.: # /etc/init.d/httpd reload
Lighttpd Use the generic Lighttpd django instructions. Nginx Use the nginx instructions from the nginx wiki Cherokee Use the cherokee cookbook instructions.
5.4 Configure MailScanner
It is assumed that you have a working MailScanner system already installed and configured, if you are installing from scratch please refer to their documentation on how to install and configure MailScanner. Install the Baruwa MailScanner Custom modules Copy them to the MailScanner custom functions directory: # confdir=$(/usr/sbin/Quick.Peek 'Custom Functions Dir' /etc/MailScanner/MailScanner.conf) # cp extras/{BaruwaSQL.pm, BaruwaLists.pm, BaruwaUserSettings.pm} $confdir/
Note: Starting with Baruwa version 1.1.0 you no longer have to edit and set the DB authentication details in each and every Custom module, you just set them up once in the MailScanner configuration file, A sample
14 Chapter 5. Source Installation Baruwa Documentation, Release 1.1.2 configuration file is provided you simply customize that and drop it into the configuration directory and it will override the settings in your MailScanner.conf file.
Edit the provided MailScanner config file extras/baruwa-mailscanner.conf, you need to make sure the following options are correct: Quarantine User = exim #(Or what ever your `Run As User` is set to) DB DSN = DBI:mysql:database=baruwa;host=spam01;port=3306 #set to valid DSN DB Username = baruwa # your DB username DB Password = password # your DB password
To actually quarantine and later process messages with in Baruwa, set store as one of your keywords for the Spam Actions and High Scoring Spam Actions MailScanner options. The provided MailScanner configuration provides for SQL logging, Whitelists and Blacklists and Per user settings. Copy the file into the MailScanner configuration directory: # cp extras/baruwa-mailscanner.conf /etc/MailScanner/conf.d/baruwa.conf
In some cases your MailScanner configuration directory is under /opt: # cp extras/baruwa-mailscanner.conf /opt/etc/MailScanner/conf.d/baruwa.conf
Apply configuration changes Test your configuration for any errors: # MailScanner --lint
Restart MailScanner: # /etc/init.d/MailScanner restart
5.5 Testing
Verify that is working Check your log files you should see Baruwa SQL logger: Aug 9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL Aug 9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL
Baruwa Lists: Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 xxx.xx.xxx.0/26
Baruwa User settings: Aug 9 15:00:03 localhost MailScanner[25708]: Baruwa - Populating spam score settings Aug 9 15:00:03 localhost MailScanner[25708]: Read 1 spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Baruwa - Populating high spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Read 1 high spam score settings
Point your browser to http://hostname_used login with admin user and password and start working. You can now use the interface to add users, domains and process messages, etc etc.
5.5. Testing 15 Baruwa Documentation, Release 1.1.2
5.6 Need help
If your installation is not working as expected, support is available, you can get free and friendly support from the list or paid support from the author or other companies that support baruwa.
5.7 Distribution / OS installation
• Baruwa on RHEL/SL/Centos. • Baruwa on Fedora. • Baruwa on Ubuntu/Debian.
16 Chapter 5. Source Installation CHAPTER 6
Baruwa on RHEL/SL/Centos
The Baruwa rpm that is provided only supports Apache out of the box, if you are running a different web server, please install from source or rebuild the source rpm to support your web server.
6.1 Install EPEL
The EPEL repo provides packages which are in Fedora but no yet included in RHEL/SL/CENTOS. Instructions on installing it can be found on EPEL You need to install this repo in order to access certain packages that are required by Baruwa.
6.2 Baruwa installation
A Baruwa RHEL/SL/Centos repo is now available at http://repo.baruwa.org/ To install from this repo you need to enable the repo EL-5: # rpm -Uvh http://repo.baruwa.org/el5/i386/baruwa-release-5-0.noarch.rpm
EL-6: # rpm -Uvh http://repo.baruwa.org/el6/i386/baruwa-release-6-0.noarch.rpm
Install the dependencies: # yum install mysql-server mod_wsgi rabbitmq-server
Note: If you are installing on RHEL/CENTOS 6 you need to run yum install django-picklefield
Install Baruwa, all the required dependencies not in the other repo’s will be resolved by packages shipped by the Baruwa repo: # yum install baruwa
6.3 Configure RabbitMQ
Create a user and virtual host for baruwa:
17 Baruwa Documentation, Release 1.1.2
# rabbitmqctl add_user baruwa your_password # rabbitmqctl add_vhost baruwa # rabbitmqctl set_permissions -p baruwa baruwa ".*" ".*" ".*"
Delete the guest user: # rabbitmqctl delete_user guest
See the RabbitMQ Admin Guide for more information.
Note: Please ensure that you control access to your RabbitMQ install as to prevent an unauthorized clients from accessing your broker.
6.4 Configure Baruwa
Create the database: # mysqladmin -u root -p create baruwa
Create a Mysql user for baruwa Run the command from the mysql prompt: mysql> GRANT ALL ON baruwa.* TO baruwa@localhost IDENTIFIED BY '
Note: You may want to secure your system by creating several users will limited rights as opposed to the above where the user has full access to the DB.
Configure the Baruwa settings Edit the Baruwa settings.py file: # vi /etc/baruwa/settings.py
Set the following options under the default DATABASE option: NAME='baruwa' USER='baruwa' PASSWORD='
Populate the database: # baruwa-admin syncdb --noinput # for name in $(echo "accounts messages lists reports status fixups config"); do baruwa-admin migrate $name; done
Create the admin user account: # baruwa-admin createsuperuser
Set the rabbitMQ settings: CELERY_CONCURRENCY= 20 BROKER_HOST="localhost" BROKER_PORT= 5672 BROKER_USER="baruwa"
18 Chapter 6. Baruwa on RHEL/SL/Centos Baruwa Documentation, Release 1.1.2
BROKER_PASSWORD="your_password" BROKER_VHOST="baruwa"
Edit the settings.py file and make configuration changes to suit your site.: # vi /etc/baruwa/settings.py
Warning: Make sure you change the SECRET_KEY, DO NOT USE THE DEFAULT, If you have a cluster the key should be the same on all the machines in the cluster.
Configure celeryd to run as a daemon You need to run celeryd as a daemon in order to process tasks such as Bayesian learning and message releases from the quarantine etc etc. An init script /etc/init.d/baruwa and configuration file /etc/sysconfig/baruwa are installed by the Baruwa rpm all you need to do is enable celeryd to be started at system boot by running: # chkconfig --level 35 baruwa on # service baruwa start
Configure Email Signature management Baruwa now supports the management of email signatures / disclaimers from within the web interface. Signatures are configured on a domain and user level. Both HTML and text signatures are supported, HTML signatures support embedding of one graphical image, which can be uploaded via the HTML editor interface. The backend that handles the signatures needs to be initialized before you can begin to manage the signatures via the interface. To initialize the backend run: # baruwa-admin initconfig
This will ask you for the hostname of the system you are setting up, and then initialize the system for you. The command does attempt to guess your hostname, so if its correct just press enter. You need to initialize each of your machines if you are running a clustered setup. Setup Web server Edit your apache configurations to enable virtual hosting if not enabled already. Then set the correct hostname in /etc/httpd/conf.d/baruwa.conf: # change to your hostname ServerName baruwa-alpha.local
Make sure mod_wsgi is enabled, uncomment the following line in /etc/httpd/conf.d/wsgi.conf: LoadModule wsgi_module modules/mod_wsgi.so
Restart apache.
6.5 Configure MailScanner
It is assumed that you have a working MailScanner system already configured, if you are installing from scratch please refer to their documentation on how to configure MailScanner. The Baruwa repo includes mailscanner and it will be installed automatically when you install baruwa.
6.5. Configure MailScanner 19 Baruwa Documentation, Release 1.1.2
Note: Starting with Baruwa version 1.1.0 you no longer have to edit and set the DB authentication details in each and every Custom module, you just set them up once in the MailScanner configuration file, A Baruwa MailScanner configuration file is installed as /etc/MailScanner/conf.d/baruwa.conf
Edit the provided Baruwa MailScanner config file /etc/MailScanner/conf.d/baruwa.conf, you need to make sure the following options are correct: Quarantine User = exim #(Or what ever your `Run As User` is set to) DB DSN = DBI:mysql:database=baruwa;host=spam01;port=3306 #set to valid DSN DB Username = baruwa # your DB username DB Password = password # your DB password
To actually quarantine and later process messages with in Baruwa, set store as one of your keywords for the Spam Actions and High Scoring Spam Actions MailScanner options. The provided MailScanner configuration provides for SQL logging, Whitelists and Blacklists and Per user settings. Apply configuration changes Test your configuration for any errors: # MailScanner --lint
Restart MailScanner: # /etc/init.d/mailscanner restart
6.6 Testing
Verify that is working Check your log files you should see Baruwa SQL logger: Aug 9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL Aug 9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL
Baruwa Lists: Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 xxx.xx.xxx.0/26
Baruwa User settings: Aug 9 15:00:03 localhost MailScanner[25708]: Baruwa - Populating spam score settings Aug 9 15:00:03 localhost MailScanner[25708]: Read 1 spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Baruwa - Populating high spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Read 1 high spam score settings
Point your browser to http://hostname_used login with admin user and password and start working. You can now use the interface to add users, domains and process messages, etc etc.
6.7 Need help
If your installation is not working as expected, support is available, you can get free and friendly support from the list or paid support from the author or other companies that support baruwa.
20 Chapter 6. Baruwa on RHEL/SL/Centos CHAPTER 7
Baruwa on Fedora
The Baruwa rpm that is provided only supports apache out of the box, if you are running a different web server, please install from source or rebuild the source rpm to support your web server.
7.1 Baruwa Installation
A Baruwa Fedora repo is now available at http://repo.baruwa.org/
Note: The Baruwa Fedora repo also ships the mailscanner rpm package.
To install from this repo you need to enable the repo: # rpm -Uvh http://repo.baruwa.org/f15/i386/baruwa-release-15-0.noarch.rpm
Install the dependencies: # yum install mysql-server rabbitmq-server python-amqplib django-picklefield
Install Baruwa: # yum install baruwa
7.2 Configure RabbitMQ
Create a user and virtual host for baruwa: # rabbitmqctl add_user baruwa your_password # rabbitmqctl add_vhost baruwa # rabbitmqctl set_permissions -p baruwa baruwa ".*" ".*" ".*"
Delete the guest user: # rabbitmqctl delete_user guest
See the RabbitMQ Admin Guide for more information.
Note: Please ensure that you control access to your RabbitMQ install as to prevent an unauthorized clients from accessing your broker.
21 Baruwa Documentation, Release 1.1.2
7.3 Configure Baruwa
Create the database: # mysqladmin -u root -p create baruwa
Create a Mysql user for baruwa Run the command from the mysql prompt: mysql> GRANT ALL ON baruwa.* TO baruwa@localhost IDENTIFIED BY '
Note: You may want to secure your system by creating several users will limited rights as opposed to the above where the user has full access to the DB.
Configure the Baruwa settings Edit the Baruwa settings.py file: # vi /etc/baruwa/settings.py
Set the following options under the default DATABASE option: NAME='baruwa' USER='baruwa' PASSWORD='
Populate the database: # baruwa-admin syncdb --noinput # for name in $(echo "accounts messages lists reports status fixups config"); do baruwa-admin migrate $name; done
Create the admin user account: # baruwa-admin createsuperuser
Set the rabbitMQ settings: CELERY_CONCURRENCY= 20 BROKER_HOST="localhost" BROKER_PORT= 5672 BROKER_USER="baruwa" BROKER_PASSWORD="your_password" BROKER_VHOST="baruwa"
Edit the settings.py file and make configuration changes to suit your site.: # vi /etc/baruwa/settings.py
Warning: Make sure you change the SECRET_KEY, DO NOT USE THE DEFAULT, If you have a cluster the key should be the same on all the machines in the cluster.
Configure celeryd to run as a daemon You need to run celeryd as a daemon in order to process tasks such as Bayesian learning and message releases from the quarantine etc etc. An init script /etc/init.d/baruwa and configuration file /etc/sysconfig/baruwa are installed by the Baruwa rpm all you need to do is enable celeryd to be started at system boot by running:
22 Chapter 7. Baruwa on Fedora Baruwa Documentation, Release 1.1.2
# chkconfig --level 35 baruwa on # service baruwa start
Configure Email Signature management Baruwa now supports the management of email signatures / disclaimers from within the web interface. Signatures are configured on a domain and user level. Both HTML and text signatures are supported, HTML signatures support embedding of one graphical image, which can be uploaded via the HTML editor interface. The backend that handles the signatures needs to be initialized before you can begin to manage the signatures via the interface. To initialize the backend run: # baruwa-admin initconfig
This will ask you for the hostname of the system you are setting up, and then initialize the system for you. The command does attempt to guess your hostname, so if its correct just press enter. You need to initialize each of your machines if you are running a clustered setup. Setup Web server Edit your apache configurations to enable virtual hosting if not enabled already. Then set the correct hostname in /etc/httpd/conf.d/baruwa.conf: # change to your hostname ServerName baruwa-alpha.local
Make sure mod_wsgi is enabled, uncomment the following line in /etc/httpd/conf.d/wsgi.conf: LoadModule wsgi_module modules/mod_wsgi.so
Restart apache.
7.4 Configure MailScanner
It is assumed that you have a working MailScanner system already configured, if you are installing from scratch please refer to their documentation on how to configure MailScanner. The Baruwa repo includes mailscanner and it will be installed automatically when you install baruwa.
Note: Starting with Baruwa version 1.1.0 you no longer have to edit and set the DB authentication details in each and every Custom module, you just set them up once in the MailScanner configuration file, A Baruwa MailScanner configuration file is installed as /etc/MailScanner/conf.d/baruwa.conf
Edit the provided Baruwa MailScanner config file /etc/MailScanner/conf.d/baruwa.conf, you need to make sure the following options are correct: Quarantine User = exim #(Or what ever your `Run As User` is set to) DB DSN = DBI:mysql:database=baruwa;host=spam01;port=3306 #set to valid DSN DB Username = baruwa # your DB username DB Password = password # your DB password
To actually quarantine and later process messages with in Baruwa, set store as one of your keywords for the Spam Actions and High Scoring Spam Actions MailScanner options. The provided MailScanner configuration provides for SQL logging, Whitelists and Blacklists and Per user settings. Apply configuration changes Test your configuration for any errors:
7.4. Configure MailScanner 23 Baruwa Documentation, Release 1.1.2
# MailScanner --lint
Restart MailScanner: # /etc/init.d/mailscanner restart
7.5 Testing
Verify that is working Check your log files you should see Baruwa SQL logger: Aug 9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL Aug 9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL
Baruwa Lists: Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 xxx.xx.xxx.0/26
Baruwa User settings: Aug 9 15:00:03 localhost MailScanner[25708]: Baruwa - Populating spam score settings Aug 9 15:00:03 localhost MailScanner[25708]: Read 1 spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Baruwa - Populating high spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Read 1 high spam score settings
Point your browser to http://hostname_used login with admin user and password and start working. You can now use the interface to add users, domains and process messages, etc etc.
7.6 Need help
If your installation is not working as expected, support is available, you can get free and friendly support from the list or paid support from the author or other companies that support baruwa.
24 Chapter 7. Baruwa on Fedora CHAPTER 8
Baruwa on Ubuntu/Debian
As of Baruwa 1.1.0 an Apt repo is provided to enable users of Ubuntu and Debian to install Baruwa using apt-get.
8.1 Install & Configure RabbitMQ
Install RabbitMQ: # apt-get install rabbitmq-server
8.2 Configure RabbitMQ
Create a user and virtual host for baruwa: # rabbitmqctl add_user baruwa your_password # rabbitmqctl add_vhost baruwa # rabbitmqctl set_permissions -p baruwa baruwa ".*" ".*" ".*"
Delete the guest user: # rabbitmqctl delete_user guest
See the RabbitMQ Admin Guide for more information.
Note: Please ensure that you control access to your RabbitMQ install as to prevent an unauthorized clients from accessing your broker.
8.3 Baruwa Apt install
The Baruwa Apt server is located at http://apt.baruwa.org/ To install from this server you need to enable it by adding its gpg key and adding it to your /etc/apt/sources.list file:
# wget -O - http://apt.baruwa.org/baruwa-apt-keys.gpg | apt-key add -
Then add the following to your sources file debian: deb http://apt.baruwa.org/debian "dist" main
25 Baruwa Documentation, Release 1.1.2
Replace “dist” with the name of the release you are running: (squeeze, wheezy, sid) ubuntu: deb http://apt.baruwa.org/ubuntu "dist" main
Replace “dist” with the name of the release you are running: (lucid, maverick, natty oneiric) You can now install Baruwa from the APT repo: # apt-get update # apt-get install baruwa
8.4 Automated configuration
The installation process will also configure apache, mysql and baruwa should you choose let the install configure the system for you. The install asks you for the following info • apache virtualhost name (The name used to configure the baruwa apache virtualhost) • database host (The hostname or ip of the host running your mysql database) • database admin user (A user account with admin access on the database server) • database admin password (The password fo the above user) • database user (The user baruwa will use to connect to the database) • database password (The password for the above) • database name (The name of the baruwa database) • rabbitmq host (The rabbitMQ hostname or IP address) • rabbitmq vhost (The RabbitMQ vhost) • rabbitmq user (The RabbitMQ user) • rabbitmq password (The RabbitMQ password) • baruwa admin user (The baruwa admin user) • baruwa admin password (The baruwa admin user password) • baruwa admin email (The baruwa admin user email address) Populate the database: # baruwa-admin syncdb --noinput # for name in $(echo "accounts messages lists reports status fixups config"); do baruwa-admin migrate $name; done
Create the admin user account: # baruwa-admin createsuperuser
8.5 Configure MailScanner
It is assumed that you have a working MailScanner system already configured, if you are installing from scratch please refer to their documentation on how to configure MailScanner. The Baruwa repo includes mailscanner and it will be installed automatically when you install baruwa.
26 Chapter 8. Baruwa on Ubuntu/Debian Baruwa Documentation, Release 1.1.2
Note: Starting with Baruwa version 1.1.0 you no longer have to edit and set the DB authentication details in each and every Custom module, you just set them up once in the MailScanner configuration file, A Baruwa MailScanner configuration file is installed as /etc/MailScanner/conf.d/baruwa.conf
Edit the provided Baruwa MailScanner config file /etc/MailScanner/conf.d/baruwa.conf, you need to make sure the following options are correct: Quarantine User = exim #(Or what ever your `Run As User` is set to) DB DSN = DBI:mysql:database=baruwa;host=spam01;port=3306 #set to valid DSN DB Username = baruwa # your DB username DB Password = password # your DB password
To actually quarantine and later process messages with in Baruwa, set store as one of your keywords for the Spam Actions and High Scoring Spam Actions MailScanner options. The provided MailScanner configuration provides for SQL logging, Whitelists and Blacklists and Per user settings. Apply configuration changes Test your configuration for any errors: # MailScanner --lint
Restart MailScanner: # /etc/init.d/mailscanner restart
8.6 Configure Baruwa
Edit the settings.py file and make configuration changes to suit your site.: # vi /etc/baruwa/settings.py
Warning: Make sure you change the SECRET_KEY, DO NOT USE THE DEFAULT, If you have a cluster the key should be the same on all the machines in the cluster.
Configure Email Signature management Baruwa now supports the management of email signatures / disclaimers from within the web interface. Signatures are configured on a domain and user level. Both HTML and text signatures are supported, HTML signatures support embedding of one graphical image, which can be uploaded via the HTML editor interface. The backend that handles the signatures needs to be initialized before you can begin to manage the signatures via the interface. To initialize the backend run: # baruwa-admin initconfig
This will ask you for the hostname of the system you are setting up, and then initialize the system for you. The command does attempt to guess your hostname, so if its correct just press enter. You need to initialize each of your machines if you are running a clustered setup.
8.7 Testing
Verify that is working
8.6. Configure Baruwa 27 Baruwa Documentation, Release 1.1.2
Check your log files you should see Baruwa SQL logger: Aug 9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL Aug 9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL
Baruwa Lists: Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 xxx.xx.xxx.0/26
Baruwa User settings: Aug 9 15:00:03 localhost MailScanner[25708]: Baruwa - Populating spam score settings Aug 9 15:00:03 localhost MailScanner[25708]: Read 1 spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Baruwa - Populating high spam score settings Aug 9 14:59:53 localhost MailScanner[25668]: Read 1 high spam score settings
Point your browser to http://hostname_used login with admin user and password and start working. You can now use the interface to add users, domains and process messages, etc etc.
8.8 Need help
If your installation is not working as expected, support is available, you can get free and friendly support from the list or paid support from the author or other companies that support baruwa.
28 Chapter 8. Baruwa on Ubuntu/Debian CHAPTER 9
External authentication
Baruwa can be configured to authenticate to external authentication systems, such as LDAP, RADIUS, IMAP, POP3, SMTP, OAUTH.
9.1 SMTP, POP3, IMAP and RADIUS/RSA SECURID
Baruwa supports authentication to external authentication systems. SMTP, POP3, IMAP, RADIUS/RSA SE- CURID Active Directory are supported out of the box. TLS, APOP are also supported to ensure user authentica- tion details are protected over the wire. Authentication is setup on a per domain basis.
9.1.1 Configuration
As the administrator click on the domain name and add an authentication server. The options are • Address (Either a hostname or IP address) • Protocol (POP3, IMAP, SMTP, RADIUS/RSA SECURID) • Port • Enabled • Split address (usernames with @ split into user and domain parts user part used to authenticate)
9.1.2 RADIUS secret
The RADIUS secret need to be set in the settings file on a per Address basis: RADIUS_SECRET['127.0.0.1']='radius secret'
9.2 ACTIVE DIRECTORY
Active directory authentication support has been introduced and is still experimental. Its configured by using the AD_* options in the settings file, and adding an authentication server within the web interface. The following features are supported: • Authentication of users including admin users • Creation and update of users alias addresses • Creation and update of user profile information
29 Baruwa Documentation, Release 1.1.2
9.3 LDAP
Ldap authentication can be enabled by installing the Django-auth-ldap package. Please refer to their documenta- tion on how to configure the package.
30 Chapter 9. External authentication CHAPTER 10
MTA Integration
Baruwa can be integrated with the MTA to enable configuring of some MTA features from with in Baruwa. Postfix and Exim are the only MTA’s supported at the moment as Sendmail lacks native SQL support.
10.1 Postfix
At the moment the following features can be integrated • Relay domains • Transports • Relay recipient maps • Global whitelists
10.1.1 Relay domains
In your postfix main.cf file set: relay_domains = mysql:/etc/postfix/mysql-relay_domains.cf
Then create the /etc/postfix/mysql-relay_domains.cf file with the following content: user = baruwa password = password dbname = baruwa query = SELECT address FROM user_addresses WHERE \ address='%s' AND enabled=1 AND address_type=1; hosts = 127.0.0.1
10.1.2 Transports
In your postfix main.cf file set: transport_maps = mysql:/etc/postfix/mysql-transports.cf
Then create the /etc/postfix/mysql-transports.cf file with the following content: user = baruwa password = password dbname = baruwa query = SELECT CONCAT('smtp:[', mail_hosts.address, ']:', port) \ FROM mail_hosts, user_addresses WHERE user_addresses.address = '%s' AND \ user_addresses.id = mail_hosts.useraddress_id; hosts = 127.0.0.1
31 Baruwa Documentation, Release 1.1.2
10.1.3 Relay recipient maps
In your postfix main.cf file set: relay_recipient_maps = mysql:/etc/postfix/mysql-relay_recipients.cf
Then create the /etc/postfix/mysql-relay_recipients.cf file with the following content: user = baruwa password = password dbname = baruwa query = SELECT 1 FROM user_addresses WHERE address='%s' AND address_type=2 \ UNION SELECT 1 FROM auth_user WHERE username = '%s' OR email = '%s' \ hosts = 127.0.0.1
10.1.4 Global Whitelist
In your postfix main.cf file set: whitelist_policy = check_client_access mysql:/etc/postfix/mysql-global_lists.cf smtpd_recipient_restrictions = whitelist_policy
Then create the /etc/postfix/mysql-global_lists.cf with the following content: user = baruwa password = password dbname = baruwa query = SELECT CONCAT('PERMIT') FROM lists WHERE from_address='%s' AND list_type=1 \ UNION SELECT CONCAT('REJECT') FROM lists WHERE from_address='%s' AND list_type=2; hosts = 127.0.0.1
10.2 Exim
At the moment the following features can be integrated. • Route Data • Relay domains
10.2.1 Route Data
You can use the following route_data option in your routers used to deliver the cleaned mail: route_data = ${lookup mysql {SELECT GROUP_CONCAT(CONCAT(mail_hosts.address,\ '::',mail_hosts.port) SEPARATOR ':') a FROM mail_hosts, \ user_addresses WHERE useraddress_id=user_addresses.id AND \ user_addresses.address = '${quote_mysql:$domain}' AND \ mail_hosts.enabled = 1 AND user_addresses.enabled = 1}}
10.2.2 Relay domains
Use the following domain list in your acl’s: domainlist relay_sql_domains = mysql;SELECT address FROM user_addresses WHERE \ address_type=1 AND enabled=1 AND address='${quote_mysql:$domain}';
32 Chapter 10. MTA Integration CHAPTER 11
Clustered setups
Baruwa is capable of running in a cluster, The only requirement is that the nodes share session information and have access to either the same MQ broker or use a MQ broker that is clustered with the other brokers serving the other nodes. If you are running your nodes from the same database backend or running multi master replication and using a single MQ broker then this will work out of the box. You will be able to run the same message management operations on any of the nodes within a cluster.
Note: As of version 1.1.0 the status view will only show the status of the host you are connected to, In future versions you will be able to view the global cluster status as well as select a remote node in order to view its status.
33 Baruwa Documentation, Release 1.1.2
34 Chapter 11. Clustered setups CHAPTER 12
Other batteries included
Baruwa provides custom django manage.py commands to enable scripting of house keeping tasks such as quaran- tine management and Database maintenance.
12.1 Command options and help
These commands may take options to get details on the supported options run: # baruwa-admin help command_name
12.2 Quarantine management
# baruwa-admin cleanquarantine
Deletes quarantined files older than QUARANTINE_DAYS_TO_KEEP. QUARANTINE_DAYS_TO_KEEP is set in the settings.py file
12.3 Quarantine reports
# baruwa-admin sendquarantinereports
Generates an email report of the quarantined messages for the past 24 hours, for each user that has quarantine report enabled.
12.4 Database maintenance
# baruwa-admin dbclean
Deletes records older than 60 days from the maillog table of the database, and archives them to the archive table.
12.5 Spamassassin rule description updates
# baruwa-admin updatesarules
Updates the Spamassassin rule descriptions in the database.
35 Baruwa Documentation, Release 1.1.2
12.6 PDF reports
# baruwa-admin sendpdfreports
Sends PDF reports by email.
12.7 Mailq Stats updates
# baruwa-admin queuestats
Query the inbound and outbound queues and write stats to the database.
12.8 Email Signatures configuration
# baruwa-admin initconfig
Sets up the backend for configuring of domain and user email signatures via the interface.
36 Chapter 12. Other batteries included CHAPTER 13
Getting Help
13.1 How do I do X? Why doesn’t Y work? Where can I go to get help?
If the documentation does not contain an answer to your issue try the Baruwa mailing list, Feel free to ask any questions on installing, configuring, integrating and troubleshooting Baruwa. Please subscribe to the mailing-list or if you prefer to use a forum interface
13.2 I think I’ve found a security problem! What should I do?
If you think you’ve found a security vulnerability with Baruwa, please send a message to [email protected]
13.3 Can i get Commercial Support or pay for an installation
The author of Baruwa provides commercial support on both an ad-hoc and contract basis for Baruwa and all the associated applications. Any issues big or small from custom features to running entire clusters on a day to day basis.
37 Baruwa Documentation, Release 1.1.2
38 Chapter 13. Getting Help CHAPTER 14
Contributing to Baruwa
There are so many ways to help Baruwa’s development, • Blog about it. • Report bugs and request features • Submit patches for new and fixed behaviour • Join the mailing lists and share ideas • Donate to the project • Documentation • Translation
14.1 Reporting bugs
Please use the Github issue tracking system to report bugs and request new features.
14.2 Submitting patches
Baruwa source code is maintained in a git repository at Github You can either: • Send me a pull request on Github • Submit old style patches to the mailing-list
14.3 Documentation
The documentation is part of the source, clone the repo make the changes then either: • Send me a pull request on Github • Submit old style patches to the mailing-list You can also contribute tips and sightings on the baruwa wiki at Github.
14.4 Donations
Donations are appreciated please use the Pledge system which accepts paypal payments
39 Baruwa Documentation, Release 1.1.2
14.5 Translation
Clone the source code from Github, create a new language if it does not exist, translate and test then send me a pull request on Github
40 Chapter 14. Contributing to Baruwa CHAPTER 15
Upgrading
15.1 1.1.2
This is a minor release with various bug fixes and a few new features. • Backup your current install then upgrade. • Review the new settings and add the ones that apply to you, The settings added are: – AD_HOST_NAME – AD_LDAP_PORT – AD_SEARCH_DN – AD_ADMIN_GROUP – AD_USER_GROUP – AD_SEARCH_FIELDS – AD_LDAP_SCHEME – AD_LOG_FILE
15.2 1.1.1
This is a minor release with bug fixes and new features, • Backup your current install then upgrade. • Run syncdb to create the Django south tables: # baruwa-admin syncdb
• Run fake migration 0001 for all the modules.: # for name in $(echo "accounts messages lists reports status config"); do baruwa-admin migrate $name 0001 --fake; done
• Run actual migration for all the modules.: # for name in $(echo "accounts messages lists reports status fixups config"); do baruwa-admin migrate $name; done
• Review the new settings and add the ones that apply to you, The settings added are: – POSTFIX_ALT_CONF = ‘/etc/postfix-ms’
41 Baruwa Documentation, Release 1.1.2
– LOAD_BARUWA_DEFAULT_FILTER = True – MAX_USERNAME_LENGTH = 128 – EMAIL_SIGNATURES_DIR = ‘/etc/MailScanner/signatures’ – BARUWA_NUM_RECENT_MESSAGES = 50 • If you intend on using email signatures/disclaimers, Run: # baruwa-admin initconfig
15.3 1.1.0
This is a major release, with a major code rewrite of the backend functionality, there are a few DB schema changes. • Backup your current install then upgrade • Configure the new settings.py • run baruwa-admin syncdb • run baruwa-admin compilemessages • Install new perl modules • Configure DB settings in MailScanner.conf • Fix quarantine ownership “chgrp -R celery /var/spool/MailScanner/quarantine”
15.4 1.0.2
This is a bug fix release with no schema changes. • Backup your settings.py then upgrade. • Restore the settings.py. • If using the debian package select no when asked if you want to configure mysql
15.5 1.0.1
This is a minor upgrade with no schema changes. • Backup your settings.py then upgrade. • Restore the settings.py.
42 Chapter 15. Upgrading CHAPTER 16
Migrate from Mailwatch
Out of the box migration from Mailwatch to Baruwa is no longer supported as from 1.0.0.
16.1 User contributed tips
Please use the Baruwa Wiki to find user contributed tips on migrating from Mailwatch to Baruwa.
43 Baruwa Documentation, Release 1.1.2
44 Chapter 16. Migrate from Mailwatch CHAPTER 17
User Guide
Release 1.1.2 Date June 27, 2016
17.1 Interface primer
The interface is simplified and AJAX is supported for most operations The following have full AJAX support:: • Messages • Lists • Reports
17.1.1 Messages
The messages tab provides access to the following functionality:: • Recent messages (top 50) automatically refreshed every 60 seconds • Full message list, paginated access to all records • Quarantine, split into – full quarantine – spam – non spam • Archive, paginated access to all archived records • Message details with quarantine processing, list operations – message release – bayesian learning – message deletion – whitelist, blacklist from email address or IP address • Message release – Automated release from quarantine
45 Baruwa Documentation, Release 1.1.2
17.1.2 Whitelists/Blacklists
The lists tab provides access to the following:: • Management of black and whitelists
17.1.3 Settings
The settings tab provides access to the following:: • User accounts management • Domain management – SMTP delivery host management – Authentication management – Signature management • Scanner engine configuration
17.1.4 Reports
The reports tab provides access to the following:: • Running of reports • Management of filters • Construction of custom queries
17.1.5 Status
The status tab provides access to the following:: • System status – Message totals (daily) – Service status • Bayesian status • Spamassassin lint check • Mail Queues status – Inbound queue – Outbound queue
17.1.6 Account
The accounts tab provides access to the following:: • Account management • Profile management • Signature management
46 Chapter 17. User Guide Baruwa Documentation, Release 1.1.2
17.2 FAQ’s
Answers to many common questions.
17.2.1 General
17.2.2 What is the default admin password ?
Answer: None, There is no default admin password, you need to run baruwa-admin syncdb or baruwa-admin createsuperuser to create an initial admin user.
Admin tasks
17.2.3 How do i add domains ?
Answer: Domains can be added to accounts of type “Domain admin” You need to create an account, edit the ac- count profile and set account type to “Domain admin”, then add the domain under the accounts managed domains.
17.2.4 Can i add domains to the Administrator account ?
Answer: No, Domains can only be added to accounts of “Domain admin” type, the administrator account is for managing all other aspects of the system.
17.2.5 Can a user have multiple email addresses on a single account ?
Answer: Yes You can add associated addresses to a users account. All emails to these addresses will undergo the same lists checks as the primary address and will be viewable by the user.
17.2.6 Can users use their current mail password to login to Baruwa ?
Answer: Yes Setup external authentication with either POP3, IMAP, SMTP, LDAP and RADIUS / RSA SecurID.
17.2.7 How do i route mail to the final destination ?
Answer: You can add multiple final destinations to a domain. Go to the domain in Baruwa and add “Delivery SMTP server”. The servers can either be load balanced or fail over, this is dependent on what MTA you are using. Refer to MTA integration for details.
17.2.8 Are there any restrictions on username format ?
Answer: No, However users that authenticate to external systems will have their email address automatically configured as their username locally.
Interface usage
17.2. FAQ’s 47 Baruwa Documentation, Release 1.1.2
48 Chapter 17. User Guide CHAPTER 18
Older documentation
Previous versions of documentation can be found online at http://readthedocs.org/projects/baruwa/
49